# @abapify/ts-xsd 中文文档

规范地址：https://npmcn.com/package/%40abapify/ts-xsd/

版本：0\.4\.34
npm 元数据更新时间：2026-11-02T23:18:58.331Z
中文译文更新时间：2026-11-05T22:14:03.225Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40abapify/ts-xsd
原文对照：https://npmcn.com/package/%40abapify/ts-xsd/?lang=original
项目主页：https://github.com/abapify/adt-cli/tree/main/packages/ts-xsd#readme
源码仓库：https://github.com/abapify/adt-cli

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：754 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-04-20T21:10:41.289Z
- 最新版本发布：2026-11-02T23:18:58.012Z
- 近 30 天下载量：13560（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

W3C XSD 1. 1 解析器, 构建器, 和 TypeScript 类型推论

## 安装

```sh
npm install @abapify/ts-xsd
```

也可以使用：`pnpm add @abapify/ts-xsd`、`yarn add @abapify/ts-xsd`、`bun add @abapify/ts-xsd`

## README

# t-xsd

[![npm version](https://img.shields.io/npm/v/@abapify/ts-xsd)](https://www.npmjs.com/package/@abapify/ts-xsd) [![license](https://img.shields.io/npm/l/@abapify/ts-xsd)](https://github.com/abapify/adt-cli/blob/main/LICENSE)

**W3C XSD 1. 1 解析器, 构建器, 和 TypeScript 类型推论** —— 1:1 TypeScript 代表 XML Schema 定义.

## 为什么

在TypeScript中与XSD schemas合作,通常指从真理源来漂移的手持型. `ts-xsd` 缩小这一差距:

-   **解析** 任意 W3C XSD 1.1 计程器为打入 `Schema` 对象——没有发明属性,没有快捷键.
-   **推断** 编译时的脚本类型 `InferSchema<T>`。 。 。 .
-   **生成** TypeScript 接口在构建时,当计划过于复杂,无法编译时间推论.
-   **往返旅行** `XSD → Schema → XSD` 和语义保护.
-   **解析/ 构建 XML** 文档与计划定义相对应.

## 安装

```bash
npm install @abapify/ts-xsd
# or
pnpm add @abapify/ts-xsd
# or
bun add @abapify/ts-xsd
```

> **运行时间依赖 :** `@xmldom/xmldom` (DOM解析). `ts-morph` 财务报告和审定财务报表 `zod` 用于代码特性.

## 快速启动

### 分析并构建 XSD

```typescript
import { parseXsd, buildXsd } from '@abapify/ts-xsd';

// Parse XSD to typed Schema object
const schema = parseXsd(`
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="person" type="PersonType"/>
    <xs:complexType name="PersonType">
      <xs:sequence>
        <xs:element name="name" type="xs:string"/>
        <xs:element name="age" type="xs:int" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:schema>
`);

// Build back to XSD
const xsd = buildXsd(schema, { pretty: true });
```

### Schema 文学的推论

```typescript
import type { InferSchema } from '@abapify/ts-xsd';

const personSchema = {
  element: [{ name: 'person', type: 'PersonType' }],
  complexType: [
    {
      name: 'PersonType',
      sequence: {
        element: [
          { name: 'name', type: 'xs:string' },
          { name: 'age', type: 'xs:int', minOccurs: 0 },
        ],
      },
    },
  ],
} as const;

// Infer TypeScript type at compile time — no runtime cost
type Person = InferSchema<typeof personSchema>;
// => { name: string; age?: number }
```

### 分析并用 Schema 构建 XML

```typescript
import { parseXml, buildXml } from '@abapify/ts-xsd';

const xml = `<person><name>John</name><age>30</age></person>`;
const data = parseXml(personSchema, xml);
// => { person: { name: 'John', age: 30 } }

const rebuilt = buildXml(personSchema, data, { xmlDecl: false });
// => <person><name>John</name><age>30</age></person>
```

### 从 XSD 生成类型脚本接口

```typescript
import { parseXsd, generateInterfaces } from '@abapify/ts-xsd';

const schema = parseXsd(xsdContent);
const { code } = generateInterfaces(schema, {
  flatten: true, // Inline all nested types into one
  addJsDoc: true, // Add JSDoc comments
  rootTypeName: 'MySchema',
});

// code is a ready-to-write .ts file:
// export type MySchema = { person: { name: string; age?: number } };
```

## API 参考

### XSD 模块

```typescript
import {
  parseXsd,
  buildXsd,
  resolveImports,
  loadSchema,
  type Schema,
} from '@abapify/ts-xsd';
```

#### `parseXsd(xsd: string): Schema`

将 XSD XML 字符串分析为已键入 `Schema` 对象.

#### `buildXsd(schema: Schema, options?: BuildOptions): string`

从 a 构建 XSD XML 字符串 `Schema` 对象.

```typescript
const xsd = buildXsd(schema, {
  prefix: 'xs', // Namespace prefix (default: 'xs')
  pretty: true, // Pretty print (default: true)
  indent: '  ', // Indentation string
});
```

#### `resolveImports(schema, availableSchemas): Schema`

通过匹配解决和链接导入的策略 `import.schemaLocation` 改为 `$filename`返回新的计划 `$imports` 人口众多.

```typescript
const base = { ...parseXsd(baseXsd), $filename: 'base.xsd' };
const orders = { ...parseXsd(ordersXsd), $filename: 'orders.xsd' };

const linked = resolveImports(orders, [base]);
// linked.$imports = [base]
```

#### `loadSchema(schemaPath: string, options?: LoaderOptions): Schema`

从磁盘上装入并解析一个 XSD 文件 。 同步。 设定 `autoLink: true` 自动解决进口,或 `autoResolve: true` 将一切合并为一个计划.

```typescript
const schema = loadSchema('/path/to/schema.xsd', { autoLink: true });
```

### 推断模块

```typescript
import type { InferSchema, InferElement, SchemaLike } from '@abapify/ts-xsd';
```

#### `InferSchema<T>`

从图文体中推断出一个类型( S) :`as const`) (中文(简体) ). 返回所有根元素类型的结合.

#### `InferElement<T, Name>`

按名称推断特定根元素的类型.

```typescript
type Person = InferElement<typeof schema, 'person'>;
```

#### 内建类型映射

| XSD 类型 | 类型脚本 |
| --- | --- |
| `xs:string`, (中文(简体) ), `xs:token`, (中文(简体) ), `xs:NCName` | `string` |
| `xs:int`, (中文(简体) ), `xs:integer`, (中文(简体) ), `xs:decimal` | `number` |
| `xs:boolean` | `boolean` |
| `xs:date`, (中文(简体) ), `xs:dateTime`, (中文(简体) ), `xs:time` | `string` |
| `xs:anyURI`, (中文(简体) ), `xs:QName` | `string` |
| `xs:anyType` | `unknown` |

### XML 模块

```typescript
import { parseXml, buildXml } from '@abapify/ts-xsd';
```

#### `parseXml<T>(schema, xml: string): T`

使用 schema 定义将 XML 字符串分析成一个被输入的对象 .

#### `buildXml<T>(schema, data: T, options?: XmlBuildOptions): string`

使用 schema 定义从打字对象中构建 XML 字符串 。 默认为 `xmlDecl: true` (包括: `<?xml ...?>` 声明); 通过 `{ xmlDecl: false }` 用于裸出.

### 代码模块

```typescript
import { generateSchemaLiteral, generateInterfaces } from '@abapify/ts-xsd';
```

#### `generateSchemaLiteral(xsd: string, options?): string`

生成类型脚本 `as const` 由 XSD 内容生成的图案文字——用于 `InferSchema<T>`。 。 。 .

```typescript
const code = generateSchemaLiteral(xsdContent, {
  name: 'PersonSchema',
  features: { $xmlns: true, $filename: true },
  exclude: ['annotation'],
});
// export const PersonSchema = { ... } as const;
```

#### `generateInterfaces(schema: Schema, options?): { code: string }`

从解析的 schema 生成 TypeScript 接口 。 当计划过于复杂而无法编译时有用 `InferSchema<T>` (TypeScript TS2589 复发限制).

```typescript
const { code } = generateInterfaces(schema, {
  flatten: true, // Inline all nested types (default: false)
  addJsDoc: true, // JSDoc comments
  rootTypeName: 'MySchema',
});
```

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `flatten` | `boolean` | `false` | 将所有嵌入类型内置为一 |
| `addJsDoc` | `boolean` | `false` | 添加联合来文文件评论 |
| `rootTypeName` | `string` | 自动 | 根类型自定义名称 |

### 国 际

包装一个CLI用于代码生成:

```bash
# Config-based (recommended) — uses ts-xsd.config.ts in cwd
npx ts-xsd codegen

# Single-file mode
npx ts-xsd codegen person.xsd
npx ts-xsd codegen person.xsd ./generated/person-schema.ts
npx ts-xsd codegen person.xsd --name=PersonSchema
```

### 基于配置的生成

对于多方案项目,使用可堆肥发电机系统:

```typescript
import {
  defineConfig,
  rawSchema,
  interfaces,
} from '@abapify/ts-xsd/generators';

export default defineConfig({
  sources: {
    base: {
      xsdDir: 'schemas',
      outputDir: 'src/generated',
      schemas: ['base'],
    },
    orders: {
      xsdDir: 'schemas',
      outputDir: 'src/generated',
      schemas: ['orders'],
      autoLink: true,
    },
  },
  generators: [rawSchema(), interfaces({ flatten: true })],
});
```

## Schema 结构

这个 `Schema` 类型是 W3C XSD 的 1:1 类型脚本代表。 非W3C扩展属性前缀为 `$`数字 :

```typescript
interface Schema {
  targetNamespace?: string;
  elementFormDefault?: 'qualified' | 'unqualified';

  // Composition
  import?: Import[];
  include?: Include[];

  // Declarations
  element?: TopLevelElement[];
  complexType?: TopLevelComplexType[];
  simpleType?: TopLevelSimpleType[];
  group?: NamedGroup[];
  attributeGroup?: NamedAttributeGroup[];

  // Extensions (non-W3C, prefixed with $)
  $xmlns?: { [prefix: string]: string }; // Namespace prefix mappings
  $imports?: Schema[]; // Linked imported schemas
  $filename?: string; // Source filename (for round-trip)
}
```

### 跨计划类型分辨率

链接计划通过 `$imports` 解决跨越计划边界的类别:

```typescript
const base = { ...parseXsd(baseXsd), $filename: 'base.xsd' };
const orders = { ...parseXsd(ordersXsd), $filename: 'orders.xsd' };

const linked = resolveImports(orders, [base]);

// InferSchema can now resolve types from `base`
type OrderData = InferSchema<typeof linked>;
```

## 设计原则

1.  **纯 W3C XSD 1.1** - 类型与官员匹配 [XML 计划](https://www.w3.org/TR/xmlschema11-1/XMLSchema.xsd) 准确; 没有发明属性 .
2.  **类型安全** ——全TypeScript支持以编译-时间推论.
3.  **最小依赖性** —— 说 `@xmldom/xmldom` 为DOM解析, `ts-morph` 财务报告和审定财务报表 `zod` 代码源.
4.  **树能震动** - 进口你需要的东西.
5.  **经核实的往返旅行** ——针对官方W3C XMLSchema.xsd进行测试.

## 参考资料

-   [W3C XML Schema 1.1 第1部分:结构](https://www.w3.org/TR/xmlschema11-1/)
-   [XML 计划](https://www.w3.org/TR/xmlschema11-1/XMLSchema.xsd)
-   [代码指南](https://github.com/abapify/adt-cli/tree/main/packages/ts-xsd/docs/codegen.md)

## 许可证

[麻省理工学院](https://github.com/abapify/adt-cli/blob/main/LICENSE)

## 常见问题

### @abapify/ts-xsd 是什么？

W3C XSD 1\. 1 解析器, 构建器, 和 TypeScript 类型推论

### 如何安装 @abapify/ts-xsd？

在项目目录运行 npm install @abapify/ts-xsd，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ts-xsd，可以用 npx ts-xsd 直接运行。

### @abapify/ts-xsd 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @abapify/ts-xsd 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @abapify/ts-xsd 可以商用吗？

@abapify/ts-xsd 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @abapify/ts-xsd 的下载量有多少？

根据 npm 官方下载统计，@abapify/ts-xsd 在 2026/10/05 – 2026/11/03 这 30 天内被下载 13,560 次，日均约 452 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @abapify/ts-xsd 还在维护吗？

最新版本 0\.4\.34 发布于 2026/11/03（3 天前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/04/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。