# @datocms/cma-schema-types-generator 中文文档

规范地址：https://npmcn.com/package/%40datocms/cma-schema-types-generator/

版本：6\.7\.0
npm 元数据更新时间：2026-09-24T07:00:03.590Z
中文译文更新时间：2026-11-11T15:34:02.254Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40datocms/cma-schema-types-generator
原文对照：https://npmcn.com/package/%40datocms/cma-schema-types-generator/?lang=original
项目主页：https://github.com/datocms/js-rest-api-clients/tree/main/packages/cma-schema-types-generator#readme
源码仓库：https://github.com/datocms/js-rest-api-clients

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

- 包体积（解压后）：138 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@datocms/cma-client ^6\.7\.0
- 首次发布：2026-04-29T03:48:05.011Z
- 最新版本发布：2026-09-24T07:00:03.420Z
- 近 30 天下载量：94842（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

从 DatoCMS 项目计划生成类型Script 类型定义

## 安装

```sh
npm install @datocms/cma-schema-types-generator
```

也可以使用：`pnpm add @datocms/cma-schema-types-generator`、`yarn add @datocms/cma-schema-types-generator`、`bun add @datocms/cma-schema-types-generator`

## README

# `@datocms/cma-schema-types-generator`

由 DatoCMS 项目 schema 生成 TypeScript 类型定义 .

生产 `ItemTypeDefinition`\- 基于类型(每个模型/块一个)加 `AnyBlock` 编号 : `AnyModel` 编号 : `AnyBlockOrModel` 工会类型,准备 用过的 `@datocms/cma-client` 用于类型安全的内容管理 迁移脚本.

## 安装

```bash
npm install @datocms/cma-schema-types-generator
```

`@datocms/cma-client` 是同级依赖.

## 使用量

```ts
import { buildClient } from '@datocms/cma-client';
import { generateSchemaTypes } from '@datocms/cma-schema-types-generator';

const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN! });
const code = await generateSchemaTypes(client);
```

`code` 是一个包含更美格式类型脚本的字符串,准备 写入磁盘 :

```ts
import { writeFile } from 'node:fs/promises';

await writeFile('src/generated/schema.ts', code);
```

### 示例输出

```ts
import type { ItemTypeDefinition } from '@datocms/cma-client';

type EnvironmentSettings = {
  locales: 'en' | 'it';
};

export type BlogPost = ItemTypeDefinition<
  EnvironmentSettings,
  '12345',
  {
    title: { type: 'string'; localized: true };
    content: { type: 'rich_text'; blocks: Hero };
  }
>;
export const BlogPost = {
  ID: '12345',
  REF: { type: 'item_type', id: '12345' },
} as const;

export type Hero = ItemTypeDefinition<EnvironmentSettings, '67890', { /* … */ }>;
export const Hero = {
  ID: '67890',
  REF: { type: 'item_type', id: '67890' },
} as const;

export type AnyBlock = Hero;
export type AnyModel = BlogPost;
export type AnyBlockOrModel = AnyBlock | AnyModel;
```

### 类型和价值声明合并

每个项目类型都会被排放 **两次**: 一次作为类型脚本 `type` (单位:千美元) `ItemTypeDefinition<…>` (别名)和一次作为 `export const` 携带 它的运行时间元数据。 TypeScript 合并了两者 —— `Schema.BlogPost` 以类型和值解决,取决于其位置 用于.

运行时会显示两个字段:

-   **`ID`** ——赤项型号为id(如. `'12345'`,键入为字符串 字面上可以用来缩小.
-   **`REF`** —— JSON: API 资源标识对象 `{ type: 'item_type', id: '<sameId>' }`,准备通过任何地方 aPI 需要一个项目类型的引用.

这样可以调用站点保持没有硬码字符串 ID :

```ts
import { buildClient } from '@datocms/cma-client';
import * as Schema from './generated/schema';

const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN! });

await client.items.create<Schema.LandingPage>({
  item_type: Schema.LandingPage.REF,
  title: 'Hello world',
});

if (block.__itemTypeId === Schema.HeroBlock.ID) {
  // narrowed to Schema.HeroBlock
}
```

### 选项

两个切入点都接受可选 `SchemaTypesGeneratorOptions` 对象 :

-   **`itemTypesFilter`** —— 逗号分隔的模型 api 密钥列表 内容包括: 保留模型(通过 `rich_text`, (中文(简体) ), `structured_text`, (中文(简体) ), `single_block`) 被拖入时 自动。 未知的 api 密钥被忽略 .
-   **`format`** ——以 Pretier 为输出格式。 默认为 `true`。 。 。 . Pretier 运行在工人的线程中,其记忆不会回到 主要过程:在一个有上千个字段的项目上,这增加了数百个字段 到顶峰内存使用量的兆字节。 准备吧 `false` 当代码 转到编译器,而不是一个人。 类型脚本打印机已经 输出缩进多行代码; 只有引号样式和行 休息时间不同.

### 移徙变式

`generateSchemaTypesForMigration` 作出同样的声明 **无** 页:1 `import type { ItemTypeDefinition }` ——原意为 直接插入已访问的迁移脚本 类型.

```ts
import { generateSchemaTypesForMigration } from '@datocms/cma-schema-types-generator';

const inline = await generateSchemaTypesForMigration(client, {
  itemTypesFilter: 'blog_post,author',
});
```

## 常见问题

### @datocms/cma-schema-types-generator 是什么？

从 DatoCMS 项目计划生成类型Script 类型定义

### 如何安装 @datocms/cma-schema-types-generator？

在项目目录运行 npm install @datocms/cma-schema-types-generator，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@datocms/cma-client（^6\.7\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @datocms/cma-schema-types-generator 支持 TypeScript 吗？

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

### @datocms/cma-schema-types-generator 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @datocms/cma-schema-types-generator 可以商用吗？

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

### @datocms/cma-schema-types-generator 的下载量有多少？

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

### @datocms/cma-schema-types-generator 还在维护吗？

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