# @atlaskit/adf-schema-generator 中文文档

规范地址：https://npmcn.com/package/%40atlaskit/adf-schema-generator/

版本：4\.0\.4
npm 元数据更新时间：2026-09-17T11:35:42.834Z
中文译文更新时间：2026-11-07T02:28:29.505Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40atlaskit/adf-schema-generator
原文对照：https://npmcn.com/package/%40atlaskit/adf-schema-generator/?lang=original
项目主页：https://bitbucket.org/atlassian/adf-schema#readme
源码仓库：https://bitbucket.org/atlassian/adf-schema

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

- 包体积（解压后）：423 kB，264 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2024-05-08T21:13:11.242Z
- 最新版本发布：2026-09-17T11:35:42.620Z
- 近 30 天下载量：730316（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：108（近 12 个月 13 个）

## 中文简介

生成 ADF 和 PM 计划

## 安装

```sh
npm install @atlaskit/adf-schema-generator
```

也可以使用：`pnpm add @atlaskit/adf-schema-generator`、`yarn add @atlaskit/adf-schema-generator`、`bun add @atlaskit/adf-schema-generator`

## README

# ADF Schema 生成器

这个软件包提供了一个简单的DSL(域特定语言),用于定义 schema, 可转换成多种输出格式,与 ADF 合作需要这些格式(阿特拉斯文档格式):

-   民主同盟军JSON Schema
-   普罗塞米尔斯克马
-   校验光谱

## 使用量

### DSL 服务器

软件包导出一些可用于定义方案功能:

#### 节点和标记 :

-   `adfNode` – 定义一个新的 ADF 节点
-   `adfMark` - 定义一个新的 ADF 标记

#### 组 :

-   `adfNodeGroup` – 定义一个新的 ADF 节点组
-   `adfMarkGroup` — 定义一个新的 ADF 标记组

#### 内容表达式 :

-   `$or` - 创建允许任何指定内容项目的内容表达式
-   `$onePlus` - 创建允许一个或多个指定内容项目的内容表达式
-   `$zeroPlus` - 创建允许零或更多指定内容项目的内容表达式
-   `$range` - 创建允许限制儿童数量的内容表达式

#### 节点和变量:

经常需要定义一个略为不同的节点版本. 例如:

-   在节点上启用/禁用某些属性的特征旗
-   更严格地验证特定用途的大小写,比如允许在顶级节点上留下某些标记, 并且不允许它们在同一节点的嵌入变体上.

备选案文允许这种使用.

每个变体浅显地超过基点节点光谱. 然后可以通过 `node.use('variant_name')` 方法.

在节点定义中添加新的变体,默认不会影响输出计划. 该变体必须明确用于计划定义中,通过 `node.use('variant_name')`。 。 。 .

```typescript
const paragraph = adfNode('paragraph')
  .define({
    group: blockGroup,
    content: [$zeroPlus($or(text))],
  })
  // Defines a variant of the node called 'with-attrs'
  .variant('with-attrs', {
    attrs: {
      alignment: {
        type: 'enum',
        values: ['start', 'end', 'center', 'justify'],
        default: 'start',
      },
    },
  });

// paragraphWithAttrs now references a new instance of the ADFNode with the 'with-attrs' variant applied.
const paragraphWithAttrs = paragraph.use('with-attrs');
const name = paragraphWithAttrs.getName(); // paragraph_with-attrs_node (name includes node type and variant name)

// Both base and a variant can be used in the schema definition, even as children of the same node:
const doc = adfNode('doc').define({
  root: true,
  content: [$onePlus($or(paragraph, paragraphWithAttrs))],
  //                                ^ Variant is explicitly used here
});

// This is similar to a union type in TypeScript, where you can have a type that is either one type or another.
```

#### 示例

```typescript
import {
  adfNode,
  adfMark,
  adfNodeGroup,
  $or,
  $onePlus,
  $zeroPlus,
} from '@atlaskit/adf-schema-generator';

const codeMark = adfMark('code').define();

const text = adfNode('text').define({
  marks: [codeMark],
});

const paragraph = adfNode('paragraph')
  .define({
    content: [$zeroPlus($or(text))],
  })
  .variant('with-attrs', {
    attrs: {
      alignment: {
        type: 'enum',
        values: ['start', 'end', 'center', 'justify'],
        default: 'start',
      },
    },
  });

const blockGroup = adfNodeGroup('block', [paragraph]);

const doc = adfNode('doc').define({
  root: true,
  content: [$onePlus($or(blockGroup))],
});
```

### 第0阶段

阶段0 schema是一款实验性的超级集全 schema. 它被用来测试新的特征,不能保证稳定.

有两种方法可以定义一个阶段0节点.

#### 1\. 使用内线 `stage0` 节点光谱覆盖 :

内入 `stage0` spec是碱性节点光谱的浅接. 例如,这会产生两个PM节点: `paragraph` 财务报告和审定财务报表 `paragraphStage0`。 。 。 .

```typescript
const paragraph = adfNode('paragraph').define({
  content: [$zeroPlus($or(text))],
  stage0: {
    attrs: {
      alignment: {
        type: 'enum',
        values: ['start', 'end', 'center', 'justify'],
        default: 'start',
      },
    },
  },
});
```

使用内置相位 0 覆盖是修改/扩展节点光谱的首选方式 它简化了未来的晋升 全面计划.

#### 2\. 将整个节点标为第0阶段

标出节点为 `stage0: true` 将仅输出阶段 0 节点光谱。 它不会出现在完整的Json计划. 将整个节点标为舞台0是将新的节点引入ADF schema的首选方式.

```typescript
const paragraph = adfNode('paragraph').define({
  content: [$zeroPlus($or(text))],
  stage0: true,
});
```

### 轨迹

用于生成输出格式的图案:

Traverse接受 ADF DSL 树的根节点和一个访问对象. 访问器是一种常见于树向转算法的图案. 它允许将曲面逻辑与实际处理逻辑相分离.

```typescript
import { traverse } from '@atlaskit/adf-schema-generator';

traverse(doc, {
  node: (node, variant, children) => {
    return node.type;
  },
  group: (group, children) => {
    return group.name;
  },
  $or: (children) => {
    return children.join(' | ');
  },
});
```

### 术语

-   `@DSLCompatibilityException`:此注释标志着变压器在DSL转换过程中所做的特殊情况,这些变压器处理与特定目标计划的临时相容问题. 随着DSL逐渐包括这些特例,它充当追踪机制,以查明、确定并消除这些特例.

## 出版

版本突起和出版是通过变换器工作流程进行管理的.

## 常见问题

### @atlaskit/adf-schema-generator 是什么？

生成 ADF 和 PM 计划

### 如何安装 @atlaskit/adf-schema-generator？

在项目目录运行 npm install @atlaskit/adf-schema-generator，或使用 pnpm add / yarn add / bun add。

### @atlaskit/adf-schema-generator 支持 TypeScript 吗？

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

### @atlaskit/adf-schema-generator 支持 ESM 还是 CommonJS？

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

### @atlaskit/adf-schema-generator 可以商用吗？

@atlaskit/adf-schema-generator 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlaskit/adf-schema-generator 的下载量有多少？

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

### @atlaskit/adf-schema-generator 还在维护吗？

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