核心概念

区块模型

EditorData 的核心是 blocks 数组：保存顺序的 Block 对象。每个 Block 包含其类型（type）、类型特定数据（data）以及可选的 tunes 元数据。

字段	类型	描述
id	string \| undefined	可选的唯一标识符，由编辑器在创建时分配。
type	BlockToolType	将区块与其模式、输入组件和渲染器关联的字面量键。
data	object	类型特定的数据对象：每种区块类型的结构各不相同。
tunes	BlockTunes \| undefined	可选的跨类型调整元数据字典。键是调整名称，值是自由格式数据。

JSON

{
  "time": 1745000000000,
  "version": "1.0.0",
  "blocks": [
    {
      "id": "abc123",
      "type": "header",
      "data": { "html": "Hello world", "level": "h1" }
    },
    {
      "id": "def456",
      "type": "paragraph",
      "data": { "html": "This is a <b>rich</b> paragraph." }
    }
  ]
}

区块工具与行内工具

区块工具在 EditorData 中直接创建独立的槽位。行内工具则在区块包含的 html 载荷中装饰文本。这两层完全独立，不能相互替换。

JSON 优先输出

编辑器从不持久化 HTML。当您调用 editor.data.extract() 时，得到的是纯粹的 EditorData JSON：包括媒体 URL 在内的完整数据。该 JSON 可以存入数据库、个性化处理或转换为其他格式。

TypeScript

import { Editor } from '@clepit/core';

const editor = Editor.create({ containerId: 'editor' });

const data = editor.data.extract();
// data: EditorData
// {
//   time: 1745000000000,
//   version: '1.0.0',
//   blocks: [ ... ]
// }

Editor 与 Renderer

Editor 使用浏览器 DOM 供用户编辑内容（仅限浏览器）。Renderer 获取事先保存的 EditorData 并将其渲染为 HTML（可在浏览器或 SSR 中运行）。

区块调整

Tunes 是任何区块类型的类型无关元数据槽。键是系统或插件设置的调整名称，值类型为 BlockTuneData：任意 string、number、boolean 或 null 的组合。Tunes 可以在不破坏核心数据形状的情况下添加语义。