# json-schema-content-mapper 中文文档

规范地址：https://npmcn.com/package/json-schema-content-mapper/

版本：0\.1\.0
npm 元数据更新时间：2026-11-03T20:27:42.436Z
中文译文更新时间：2026-11-03T23:49:33.428Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/json-schema-content-mapper
原文对照：https://npmcn.com/package/json-schema-content-mapper/?lang=original

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

- 包体积（解压后）：24.4 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.14\.0
- 运行依赖：6 个
- 首次发布：2026-11-03T20:26:05.254Z
- 最新版本发布：2026-11-03T20:27:42.206Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

TypeScript 9.1的JSONSchema内容映射器。

## 安装

```sh
npm install json-schema-content-mapper
```

也可以使用：`pnpm add json-schema-content-mapper`、`yarn add json-schema-content-mapper`、`bun add json-schema-content-mapper`

## README

# json-schema-content-mapper

> TypeScript 9.1的JSONSchema内容映射器。

一个本地 **TypeScript 7.1+内容映射器** 动态编译的插件 `*.jsonschema` 将文件动态地转换为全类型TypeScript源 `schema2dts`。

不需要构建步骤生成器或通用通配符环境声明。你的 JSON模式被视为一等类型模块。

## 特性

-   **Zero-Disk开销:** 生成内存中的虚拟 `.ts` 定义文件 直接由 `tsc`。
-   **json - rpc多路复用:** 建在…之上 `vscode-jsonrpc` 要处理得快， 并发的、非阻塞的多项目编译上下文。
-   **无缝的引用:** 支持使用标准JSON的多文件架构 模式 `$ref` 指针。

* * *

## 安装

将内容映射器作为开发依赖项安装到项目中：

```bash
npm install -D json-schema-content-mapper
```

_注意：确保您的工作空间使用 **打字稿7.1** （或以后）支持 内容映射器。_

* * *

## 配置(`tsconfig.json`）

在new下注册包 `contentMappers` 编译器属性。我们 强烈建议使用 `.jsonschema` 模式定义的扩展 文件。

```json
{
  "compilerOptions": {
    "module": "preserve",
    "moduleResolution": "bundler",
    "strict": true
  },
  "contentMappers": [
    {
      "package": "json-schema-content-mapper",
      "extensions": [".jsonschema"],
      "options": {
        "exportNamespaces": true
      }
    }
  ],
  "include": ["src"]
}
```

* * *

## 多文件架构引用(`$ref`）

这个内容映射器的主要优点之一是它的处理能力 本地多文件结构。而不是将所有内容捆绑到一个 巨大的模式，您可以将定义拆分为多个 `.jsonschema` 文件 并使用JSON指针引用它们。

当一个模式通过 `$ref`，内容映射器 动态地将这个链接转换成标准的JavaScript/TypeScript `import` 语句 `.d.ts` 输出。然后TypeScript的编译器会处理 自动绘制跨文件依赖关系图。

### 示例设置

#### 1\. 定义共享基模式(`src/phone.jsonschema`）

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Phone",
  "type": "string",
  "pattern": "+[0-9]+.[0-9]+"
}
```

#### 2\. 在主架构中引用它(`src/user.jsonschema`）

中使用相对文件路径 `$ref` 属性:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string" },
    "phone": { "$ref": "./common.jsonschema" }
  },
  "required": ["name"]
}
```

#### 3\. 在TypeScript代码中自然地使用(`src/index.ts`）

TypeScript解析整个链。的生成类型 `User` 将 自动继承字段(`phone`) `phone.jsonschema` 通过TypeScript的交集类型：

```typescript
import { User } from './user.jsonschema';

const user: User = {
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+33.16561655616',
};

console.log(user.id); // Available & Typed (string)
console.log(user.name); // Available & Typed (string)
console.log(user.phone); // Available & Typed (string)
```

* * *

## 运行类型检查

由于内容映射器调用外部代码包来计算模块形状， TypeScript编译器需要一个 **明确的安全选择加入标志** 运行 从CLI进行类型检查：

```bash
npx tsc --runExternalCode --noEmit
```

没有 `--runExternalCode` 国旗, `tsc` 会忽略内容映射器吗 处理，并抛出导入解析错误。

* * *

## 技术架构

这个插件建立了一个异步JSON-RPC 2.0通信进程 管道与 `tsc` 通过标准输入/输出流(`stdin`/`stdout`）.

1.  **`initialize`**：协商结构格式参数(例如： `utf-16` 字符定位)。
2.  **`openProject`**：缓存传入 `tsconfig.json` 插件配置 一个孤立的 `projectRegistry` 链接到不透明工作区的映射 `projectHandle`。
3.  **`transform`**：提取参数，解析项目上下文选项， 运行 `generateJSONSchemaTypes()`，并交付编译后的虚拟代码 层立即返回到go编译 `tsc` 核心引擎。
4.  **`closeProject`**：清除操作缓存映射到的引用 防止在手表模式期间内存泄漏。

# 作者

-   [尼古拉斯Froidure](https://insertafter.com/en/index.html)

# 许可证

[ISC](https://github.com/nfroidure/json-schema-content-mapper/blob/main/LICENSE)

## 常见问题

### json-schema-content-mapper 是什么？

TypeScript 9\.1的JSONSchema内容映射器。

### 如何安装 json-schema-content-mapper？

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

### json-schema-content-mapper 支持 TypeScript 吗？

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

### json-schema-content-mapper 支持 ESM 还是 CommonJS？

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

### json-schema-content-mapper 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.14\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### json-schema-content-mapper 可以商用吗？

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

### json-schema-content-mapper 还在维护吗？

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