# @adobe/da-sc-sdk 中文文档

规范地址：https://npmcn.com/package/%40adobe/da-sc-sdk/

版本：0\.5\.0
npm 元数据更新时间：2026-10-01T01:33:09.109Z
中文译文更新时间：2026-11-06T09:07:28.072Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40adobe/da-sc-sdk
原文对照：https://npmcn.com/package/%40adobe/da-sc-sdk/?lang=original
项目主页：https://github.com/adobe/da-sc-sdk#readme
源码仓库：https://github.com/adobe/da-sc-sdk

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

- 包体积（解压后）：537 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-05-29T15:10:41.369Z
- 最新版本发布：2026-09-04T14:44:27.090Z
- 近 30 天下载量：3654（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

DA结构化内容的无头 SDK:由chema驱动的JSON文档编辑,验证和HTML序列化.

## 安装

```sh
npm install @adobe/da-sc-sdk
```

也可以使用：`pnpm add @adobe/da-sc-sdk`、`yarn add @adobe/da-sc-sdk`、`bun add @adobe/da-sc-sdk`

## README

# 达-斯克-斯德克

与您合作的无头 SDK **DA 结构化内容** ——有计划约束的JSON文档被序列化为定义的HTML线条格式. 它揭露了一个小型的,有重点的API,覆盖了今天支持的行动.

SDK是纯粹的无害环境管理,没有DOM依赖性和I/O. UI的渲染、运输和持久性被故意留给消耗性应用.

作为交换,在SDK上所建的每一个工具都共享相同的DA结构内容行为——在这里定义一次并被所有消费者所使用,而不是在每个工具中被重新执行(并不可避免地被漂移).

## 状态

`0.x` ——公众API可以提前变更 `1.0.0`。 。 。 .

## 安装

```bash
npm install @adobe/da-sc-sdk
```

```js
import {
  createEngine,
  convertJsonToHtml,
} from "@adobe/da-sc-sdk";
```

## 快开始

```js
import { createEngine, convertJsonToHtml } from "@adobe/da-sc-sdk";

const schema = {
  type: "object",
  title: "Project",
  required: ["name"],
  properties: {
    name: { type: "string", title: "Name" },
    tags: {
      type: "array",
      title: "Tags",
      items: { type: "string", title: "Tag" },
    },
  },
};

const engine = createEngine({
  schema,
  document: { metadata: { schemaName: "project" }, data: {} },
  onChange: () => {
    /* state changed — read engine.getState() */
  },
});

engine.setField("/data/name", "Alice");
engine.addItem("/data/tags");
engine.setField("/data/tags/0", "demo");

const { html } = convertJsonToHtml({ json: engine.getState().document });
// `html` is ready to POST. Persistence is your job.
```

可运行的脚本 [实例/](https://npmcn.com/package/%40adobe/da-sc-sdk/examples/)。 。 。 .

## API 密码

5个顶级功能:

| 函数 | 目的 | 回返 |
| --- | --- | --- |
| `createEngine` | 国有编辑(UI编辑,代理持有状态). | `Engine` |
| `validateSchema` | 在捆绑之前先订个计划. | `{ valid, schemaIssues }` |
| `validateData` | 对照计划检查数据. | `{ valid, errors, schemaIssues }` |
| `convertJsonToHtml` | 转换 JSON → DA 有线格式 HTML . | `{ html } | { error }` |
| `convertHtmlToJson` | 转换 DA HTML ~ JSON. | `{ json } | { error }` |

`createEngine` 将 schema + 初始文档编译为状态可变的手柄.

**它所提供的:**

-   指向的突变`setField`, (中文(简体) ), `addItem`, (中文(简体) ), `insertItem`, (中文(简体) ), `removeItem`, (中文(简体) ), `moveItem`),在解剖学上不断更新和重新验证.
-   Schema 默认实现为初始文档 .
-   `onChange` 每一次真正的突变,就发射一次 设置一个字段为当前值是不可打开的,不会起火 `onChange`。 。 。 .

**用它当** 您会编辑一个随时间推移的文档 —— 交互式编辑器, 代理服务器持有状态交叉, 任何文档在操作之间存活的地方 .

手柄会暴露出六种方法. 所有同步,全部由 RFC 6901 JSON 指针地址:

| 方法 | 目的 |
| --- | --- |
| `getState()` | 读取当前状态快照 . |
| `setField(pointer, value)` | 设置原始值 : `pointer`。 。 。 . |
| `addItem(pointer)` | 附加到数组 `pointer`。 。 。 . |
| `insertItem(pointer)` | 在项目之前插入 `pointer`。 。 。 . |
| `removeItem(pointer)` | 删除项目 : `pointer`。 。 。 . |
| `moveItem(pointer, from, to)` | 重排数组项 . |

每一个真正的突变触发器 `onChange`;返回值为调用后的引擎当前状态. `onChange` 已经 **没有** - 读取初始状态 `getState()`。从不同的开始 `(schema, document)`,创建新引擎.

## 使用量

### 校验

```js
import { validateSchema, validateData } from "@adobe/da-sc-sdk";

validateSchema({ schema });
// → { valid, schemaIssues }

validateData({ schema, data });
// → { valid, errors, schemaIssues }
```

`errors` a. 为指向图; `errors[pointer]?.message` 是 O(1) 。 每个条目都会曝光 `keyword`, (中文(简体) ), `instancePath`, (中文(简体) ), `params`,以及 `message` 字段. `valid` 实值 `true` 仅在两者兼有的情况下 `schemaIssues` 财务报告和审定财务报表 `errors` 空的 —— 你不能声称一个文件对一个被破坏的计划有效.

### 转换( JSON QQ HTML)

```js
import { convertJsonToHtml, convertHtmlToJson } from "@adobe/da-sc-sdk";

const { html } = convertJsonToHtml({
  json: { metadata: { schemaName: "project" }, data: { name: "Alice" } },
});

const { json } = convertHtmlToJson({ html });
```

`convertHtmlToJson` 返回时 `{ error: "<reason>" }` 输入为空或格式错误.

### 编辑( 有持久性)

发动机没有运输,也没有保存状态. 将自己的毅力接通 `onChange`数字 :

```js
let engine;
let lastValues;
engine = createEngine({
  schema,
  document,
  onChange: () => {
    const next = engine.getState().document;
    if (next === lastValues) return; // skip non-mutation transitions
    lastValues = next;
    // convert via convertJsonToHtml, POST, IndexedDB-cache — whatever fits
  },
});
lastValues = engine.getState().document; // onChange does NOT fire at init
```

[文件/无头消费者](https://npmcn.com/package/%40adobe/da-sc-sdk/docs/headless-consumer.md) 拥有~40行单机保存模式并有状态跟踪.

## 处理错误

SDK通过返回值而不是例外报告验证、转换和突变失败。 真正无效的参数(错误类型、错误的指针)仍可能作为运行时间出错而浮出水面.

-   **验证器** (单位:千美元)`validateSchema`, (中文(简体) ), `validateData`——检查 `result.valid`时 `false`检查 `result.schemaIssues` 计划层面的问题 `result.errors` 数据级问题(后者为 `{ [pointer]: ValidationError }` 地图).
-   **转换器** (单位:千美元)`convertJsonToHtml`, (中文(简体) ), `convertHtmlToJson`) 结构倒置: `const { html, error } = convertJsonToHtml(...)`编辑 `error` 字段设置在空或格式错误的输入上;否则成功字段(`html` 或者说 `json`)已设定.
-   **发动机** 如果计划有问题, `createEngine` 仍然返回一个手柄,但是 `getState().schemaIssues` 将是非空和变异 不 -op。 检查 `schemaIssues.length === 0` 在依赖引擎之前.

## 类型脚本

申报类别 `index.d.ts` - 没有单独的 `@types/*` 需要安装 .

```ts
import type {
  Engine,
  EditorState,
  Document,
  JsonPointer,
  SchemaIssue,
  ErrorsByPointer,
  ValidationError,
} from "@adobe/da-sc-sdk";
```

## 运行时间支持

-   ES2022+无害环境管理。 节点内置 没有DOM.
-   节点QQ18和现代浏览器.
-   一次性依赖: [即时使用从-html](https://www.npmjs.com/package/hast-util-from-html)。 。 。 .

## 设计

-   **无头.** 没有UI,没有DOM,没有渲染。 UIs 订阅为 `onChange`。 。 。 .
-   **没有I/O.** 没有获取,没有文件系统,也没有DA端点. 来电者自系接送.
-   **五种名出出口.** 这个 `package.json` `exports` 深层导入。 这5个出口是整个公共API和预定的分界.
-   **严格的计划子集.** JSON Schema 2020-12的严格子集——参见 [文档/schema-spec.md](https://npmcn.com/package/%40adobe/da-sc-sdk/docs/schema-spec.md)合同外的任何东西都浮出水面 `schemaIssues`。 。 。 .
-   **没有** jSON Schema将军的验证.

## 发展

内部的Repo:

-   `npm install` ——安装非依赖性
-   `npm test` ——运行测试套件(Web Test Runner)
-   `npm run lint` 编号 : `npm run lint:fix` - 线上
-   `npm run build` - 产品 `dist/index.js`

## 内部

对于贡献者和超过公共API的人——布局、生命周期、计划/模型建造者,以及无头消费者模式——请参看 [文档/](https://npmcn.com/package/%40adobe/da-sc-sdk/docs/)。 。 。 .

## 许可证

阿帕奇-2.0' Adobe Inc.

## 常见问题

### @adobe/da-sc-sdk 是什么？

DA结构化内容的无头 SDK:由chema驱动的JSON文档编辑,验证和HTML序列化\.

### 如何安装 @adobe/da-sc-sdk？

在项目目录运行 npm install @adobe/da-sc-sdk，或使用 pnpm add / yarn add / bun add。

### @adobe/da-sc-sdk 支持 TypeScript 吗？

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

### @adobe/da-sc-sdk 支持 ESM 还是 CommonJS？

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

### @adobe/da-sc-sdk 需要什么版本的 Node\.js？

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

### @adobe/da-sc-sdk 可以商用吗？

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

### @adobe/da-sc-sdk 的下载量有多少？

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

### @adobe/da-sc-sdk 还在维护吗？

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