达-斯克-斯德克
与您合作的无头 SDK DA 结构化内容 ——有计划约束的JSON文档被序列化为定义的HTML线条格式. 它揭露了一个小型的,有重点的API,覆盖了今天支持的行动.
SDK是纯粹的无害环境管理,没有DOM依赖性和I/O. UI的渲染、运输和持久性被故意留给消耗性应用.
作为交换,在SDK上所建的每一个工具都共享相同的DA结构内容行为——在这里定义一次并被所有消费者所使用,而不是在每个工具中被重新执行(并不可避免地被漂移).
状态
0.x ——公众API可以提前变更 1.0.0。 。 。 .
安装
npm install @adobe/da-sc-sdk
import {
createEngine,
convertJsonToHtml,
} from "@adobe/da-sc-sdk";
快开始
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.
可运行的脚本 实例/。 。 。 .
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),创建新引擎.
使用量
校验
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)
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数字 :
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
文件/无头消费者 拥有~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/* 需要安装 .
import type {
Engine,
EditorState,
Document,
JsonPointer,
SchemaIssue,
ErrorsByPointer,
ValidationError,
} from "@adobe/da-sc-sdk";
运行时间支持
- ES2022+无害环境管理。 节点内置 没有DOM.
- 节点QQ18和现代浏览器.
- 一次性依赖: 即时使用从-html。 。 。 .
设计
- 无头. 没有UI,没有DOM,没有渲染。 UIs 订阅为
onChange。 。 。 . - 没有I/O. 没有获取,没有文件系统,也没有DA端点. 来电者自系接送.
- 五种名出出口. 这个
package.jsonexports深层导入。 这5个出口是整个公共API和预定的分界. - 严格的计划子集. JSON Schema 2020-12的严格子集——参见 文档/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的人——布局、生命周期、计划/模型建造者,以及无头消费者模式——请参看 文档/。 。 。 .
许可证
阿帕奇-2.0' Adobe Inc.