# @dazl/typescript-schema-extract 中文文档 规范地址：https://npmcn.com/package/%40dazl/typescript-schema-extract/ 版本：15\.5\.2 npm 元数据更新时间：2026-08-07T07:10:18.931Z 中文译文更新时间：2026-11-11T16:48:24.452Z 软件包许可：UNLICENSED 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40dazl/typescript-schema-extract 原文对照：https://npmcn.com/package/%40dazl/typescript-schema-extract/?lang=original 项目主页：https://github.com/dazl-dev/schematic#readme 源码仓库：https://github.com/dazl-dev/schematic ## 关键信息（来自 npm 元数据） - 包体积（解压后）：741 kB，111 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：3 个 - peer 依赖：typescript ^4\.0\.0 \|\| ^5\.0\.0 \|\| ^6\.0\.0 - 首次发布：2025-08-27T20:15:58.828Z - 最新版本发布：2026-07-09T09:47:28.468Z - 近 30 天下载量：10090（2026-10-12 至 2026-11-10，npm 官方下载统计） - 已发布版本数：10（近 12 个月 9 个） ## 中文简介 Schema 提取器将代码文件中的所有类型(说明或推断)转换为 [JSON- 计划](https://json-schema.org/) 计划 Schema提取是创建您代码自动化文档的必要步骤. ## 安装 ```sh npm install @dazl/typescript-schema-extract ``` 也可以使用：`pnpm add @dazl/typescript-schema-extract`、`yarn add @dazl/typescript-schema-extract`、`bun add @dazl/typescript-schema-extract` ## README # Schema 摘录 Schema 提取器将代码文件中的所有类型(说明或推断)转换为 [JSON- 计划](https://json-schema.org/) 计划 Schema提取是创建您代码自动化文档的必要步骤. 它由两个部分组成: **ts 变压器** 财务报告和审定财务报表 **链接**。 。 。 . # Schema 服务 schema服务允许观看特定的schema's,处理请求之间的缓存. 它发送一个更新事件, 具体说明文件无效后哪些类型已更新 它允许观看模块/Ast节点的策略. 获取有限的 Schema 深度 并扩展一个特定的分支 计划以后. 这允许图形用户界面只请求其读取的图案部分. #### 永远记得释放你的监视路径 ## 使用量 要使用 Schema 提取项目从文件中提取类型数据,请导入 `createLinker` 函数从 `@dazl/typescript-schema-extract`。此函数收到一系列文件路径的字符串,并返回已初始化的链接类. 创建链接器后, 引用 `linker.flatten`它收到两个参数,并将返回我们要求的实体的链接计划(在 `exportName`: | 名称 | 类型 | 说明 | | --- | --- | --- | | 文件 | `string` | 我们要转换的文件路径 | | 导出Name | `string` | 该文件中的导出实体, 我们希望链接 | ``` import {createLinker} from '@dazl/typescript-schema-extract'; const files = [ 'myProject/src/file-a.ts', 'myProject/src/file-b.ts' ]; const linker = createLinker(files); const linkedSchema = linker.flatten(files[0], 'IAnimal'); ``` **说明:** 如果您想使用不同提取器的链接器,请查看 [创建自定义链接区域](https://npmcn.com/package/%40dazl/typescript-schema-extract/#readme-creating-a-custom-linker)。 。 。 . 此外,目前还无法自动链接一个文件的所有输出。 您可以查看文件的输出并引用 `flatten` 但是这可能不是一个有效的过程. ## 结果实例 为了更好地理解变换是如何运作的,请查看以下界面: 变换: ```ts // file-a.ts export interface IAnimal { name: string; hasTail: boolean; makeNoise: (sound: ISound) => void; isTamed?: 'YES' | 'NO'; } ``` 如果我们使用TS变压器进行改造,我们可以得到以下计划: ```json { "$id": "/index.tsx", "$ref": "common/module", "properties": {}, "definitions": { "IAnimal": { "properties": { "name": { "type": "string" }, "hasTail": { "type": "boolean" }, "makeNoise": { "$ref": "common/function", "arguments": [ { "$ref": "#ISound", "name": "sound" } ], "returns": { "$ref": "common/undefined" }, "requiredArguments": ["sound"] }, "isTamed": { "type": "string", "enum": ["YES", "NO"] } }, "required": ["name", "hasTail", "makeNoise"], "$ref": "common/interface" } } } ``` ## 链接 链接器接收文件名和该文件中的导出名称,并返回该导出链接的策略 . 怎么会有区别呢 `ts transformer`当我们用 `ts transformer`,我们得到的结果将只使用 $ref 属性来引用其他类型(导入或来自同一文件). 链接器通过将它们连在一起来平分其中一些类型. #### 示例 让我们看看以下代码中的界面B: ```ts export interface InterfaceA { something: T; } export interface InterfaceB extends InterfaceA { somethingElse: number; } ``` 如果我们使用TS变压器来改变这个文件,我们将得到以下方案: ```json { "$id": "/index.tsx", "$ref": "common/module", "properties": {}, "definitions": { "InterfaceA": { "$ref": "common/interface", "properties": { "something": { "$ref": "#InterfaceA!T" } }, "required": ["something"], "genericParams": [{ "name": "T" }] }, "InterfaceB": { "$ref": "common/interface", "properties": { "somethingElse": { "type": "number" } }, "required": ["somethingElse"], "genericArguments": [{ "type": "string" }], "extends": { "$ref": "#InterfaceA" } } } } ``` 但我们缺少一些关于界面B的关键信息。 连接后, InterfaceB 的图案将变成: ```json "InterfaceB": { $ref: "common/interface", properties: { something: { inheritedFrom: '#InterfaceA', type: 'string' }, somethingElse: { type: 'number' } }, required: ['somethingElse', 'something'] }; ``` #### 连接规则 为了避免跑入无限回路,链接器并不将每个计划中的每个成员链接. 它确实链接: - `extends` - 使用扩展关键字的类和接口。 (但链接器不会链接界面成员) - 一般类型 - 交叉类型 - 我们可能需要连接的策略来交叉两种或两种以上不同的类型. 什么不会是联系? - 进口 - 如果您从不同的文件中导入一个类型, 它将作为引用 : `$ref: "myProject/src/util#myFunction"` - 提及其他类型 - 任何形式提及不同类型或界面,如 `type A = B` 或者说 `interface InterfaceA { type: InterfaceB }`。这还包括使用其他类型作为参数或返回值的函数. ## TS 变形器 将打字源文件转换为无链接的JSON-Schema. 默认情况下,链接器正在使用这个变压器,除非您想要一个非链接的变压器,否则无需使用这个变压器. #### 使用量 导入 `transform` 函数从 `@dazl/typescript-schema-extract`。该函数收到以下五个论据: | 名称 | 类型 | 说明 | | --- | --- | --- | | 检查器 | `typescript.TypeChecker` | 连接到想要的文件的打字检查器 | | 源文件 | `typescript.SourceFile` | 我们要改变的打字源 | | 模块Path | `string` | 模块基础目录的路径 | | 图像 | `string` | 文件所在的项目名称( 未来将删除) | | 路径Util | `IFileSystemPath` | 用于访问目录和文件的路径工具 。 (你可以使用 `path.posix`(中文(简体) ) | 例如,如果我们想要改变自己的代码: ```ts import path from 'path'; import compilerOptions from './utils'; const projectPath = '/Projects/MySecretProject/; const fileName = projectPath + 'secret-stuff.ts' // TS setup const program = typescript.createProgram([fileName], compilerOptions); const sourceFile = program.getSourceFile(fileName); const schema = transform(program.getTypeChecker(), sourceFile, fileName, 'MySecretProject', path.posix); ``` #### 外观结构( T) 您可以找到计划的结构 和我们所支持的不同类型 [json-schema 类型](https://npmcn.com/package/%40dazl/typescript-schema-extract/src/json-schema-types.ts) ## 创建自定义链接器 **说明**数字 : **目前我们不出口SchemaLinker级**。我们将导出它或添加一个接收提取器并返回链接器的函数 使用 `createLinker` 创建以打字为主的链接器,但链接器不仅限于打字. 在创建新的链接类时,链接器会接收一个提取对象: ``` export interface ILinkerOptions { getSchema: (path: string) => ModuleSchema; } ``` `ILinkerOptions` 接收文件的路径并返回从该文件创建的 JSON-Schema . 要使用与链接器不同的取出器,只需与取出器创建出一个新的取出器类并引用平分. ``` flatten(filePath: string, typeName: string): Schema ``` 平面函数接收文件路径以及我们想要链接的其中的类型 . ```ts import { SchemaLinker } from '@dazl/typescript-schema-extract/?????'; import { myExtractor } from './secretStuff'; function linkSchema(filePath, typeName) { const customLinker = new SchemaLinker(myExtractor); return linker.flatten(filePath, typeName); } ``` ## 常见问题 ### @dazl/typescript-schema-extract 是什么？ Schema 提取器将代码文件中的所有类型\(说明或推断\)转换为 JSON- 计划 计划 Schema提取是创建您代码自动化文档的必要步骤\. ### 如何安装 @dazl/typescript-schema-extract？ 在项目目录运行 npm install @dazl/typescript-schema-extract，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^4\.0\.0 \|\| ^5\.0\.0 \|\| ^6\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @dazl/typescript-schema-extract 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dazl\_\_typescript-schema-extract 是否存在。 ### @dazl/typescript-schema-extract 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @dazl/typescript-schema-extract 可以商用吗？ @dazl/typescript-schema-extract 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。 ### @dazl/typescript-schema-extract 的下载量有多少？ 根据 npm 官方下载统计，@dazl/typescript-schema-extract 在 2026/10/12 – 2026/11/10 这 30 天内被下载 10,090 次，日均约 336 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @dazl/typescript-schema-extract 还在维护吗？ 最新版本 15\.5\.2 发布于 2026/07/09（4 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 9 个；首次发布于 2025/08/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。