跳到主要内容

指南

嵌入

块参考

Clepit 内置 12 种区块类型。每个区块都有一个 JSON 结构、一个渲染器，以及通过 editor.blocks.insert 实现的编程插入路径。

所有区块在序列化时共享相同的封装结构：id、type、data，以及一个可选的 tunes 记录。

区块结构

每个区块都序列化为相同的 JSON 封装。id 由编辑器分配，以编程方式构建数据时可以省略。

JSON
{
  "id": "abc123",
  "type": "paragraph",
  "data": { "html": "Hello <b>world</b>" },
  "tunes": {}
}

alert

具有 4 种变体的高亮提示框。

字段类型必填描述
htmlstring是提示消息的 HTML 内容。支持行内工具标记。
variant'error' | 'info' | 'success' | 'warning'是提示的视觉样式。可选值之一：error、info、success、warning。
JSON
{
  "type": "alert",
  "data": { "html": "Your session will expire in 5 minutes.", "variant": "warning" }
}

audio

音频块。通过 Editor.create 上的 audioUploader 回调进行处理。

字段类型必填描述
urlstring是要嵌入的音频文件的 URL。
captionstring否显示在播放器下方的纯文本标题。
altstring否音频元素的无障碍标签。
alignment'center' | 'left' | 'right'否播放器的水平对齐方式。可选值之一：center、left、right。
JSON
{
  "type": "audio",
  "data": { "url": "/media/podcast.mp3", "caption": "Episode 12", "alignment": "center" }
}

checklist

带有每项选中状态的交互式复选框列表。

字段类型必填描述
itemsChecklistItem[]是清单项的数组，每项包含 text 和 checked 状态。
items[].textstring是项目标签的 HTML 内容。
items[].checkedboolean是复选框是否已选中。
JSON
{
  "type": "checklist",
  "data": {
    "items": [
      { "text": "Install the package", "checked": true },
      { "text": "Mount the editor", "checked": false }
    ]
  }
}

code

带语法高亮的代码块。支持 50 种语言，包括 typescript、python、rust、go、ruby、swift 和 kotlin。

字段类型必填描述
codestring是要显示的原始代码字符串。
languageCodeLanguage否语法高亮语言。默认为 typescript。
themeCodeTheme否编辑器颜色主题。默认为 github-dark。
showCopyboolean否在渲染输出中显示复制按钮。
JSON
{
  "type": "code",
  "data": { "code": "const x = 42;", "language": "typescript", "theme": "github-dark", "showCopy": true }
}

delimiter

章节之间的视觉分隔符。

字段类型必填描述
variant'line' | 'stars'是分隔符的视觉样式。可选值之一：line、stars。
JSON
{
  "type": "delimiter",
  "data": { "variant": "line" }
}

顶级标题和章节标题（h1 到 h6）。行内工具可在 html 负载中使用。

字段类型必填描述
htmlstring是标题的 HTML 内容。支持行内工具标记。
level'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'否标题级别。可选值之一：h1、h2、h3、h4、h5、h6。默认为 h1。
JSON
{
  "type": "header",
  "data": { "html": "Getting started", "level": "h2" }
}

image

带有标题和 alt 文本的图像块。通过 Editor.create 上的 imageUploader 回调进行处理。

字段类型必填描述
urlstring是要嵌入的图像的 URL。
captionstring否显示在图像下方的纯文本标题。
altstring否图像元素的 alt 文本。
alignment'center' | 'left' | 'right'否图像的水平对齐方式。可选值之一：center、left、right。
JSON
{
  "type": "image",
  "data": { "url": "/img/hero.jpg", "caption": "Hero image", "alt": "A hero", "alignment": "center" }
}

list

有序或无序列表。每一项都是 html。

字段类型必填描述
type'ordered' | 'unordered'是列表类型。可选值之一：ordered、unordered。
itemsstring[]是HTML 字符串的数组，每个列表项一个。
JSON
{
  "type": "list",
  "data": { "type": "unordered", "items": ["First item", "Second item"] }
}

paragraph

富文本段落。接受诸如 bold、italic、code、link、marker 和 tooltip 之类的行内工具标记。

字段类型必填描述
htmlstring是段落的 HTML 内容。支持行内工具标记。
JSON
{
  "type": "paragraph",
  "data": { "html": "This is a <b>paragraph</b> with inline markup." }
}

quote

带有可选作者署名的引用块。

字段类型必填描述
htmlstring是引用正文的 HTML 内容。支持行内工具标记。
authorstring否显示在引用下方的纯文本或 HTML 署名。
JSON
{
  "type": "quote",
  "data": { "html": "The best way to predict the future is to invent it.", "author": "Alan Kay" }
}

table

数据网格。第一行可用作表头；每个单元格都是 html。

字段类型必填描述
datastring[][]是HTML 单元格字符串的二维数组。第一行是表头行。
captionstring否显示在表格下方的纯文本或 HTML 标题。
showDownloadboolean否在渲染输出中显示下载按钮。
JSON
{
  "type": "table",
  "data": {
    "data": [["Name", "Type"], ["html", "string"], ["variant", "AlertVariant"]],
    "caption": "AlertData fields",
    "showDownload": false
  }
}

video

视频块。通过 Editor.create 上的 videoUploader 回调进行处理。

字段类型必填描述
urlstring是视频文件的 URL 或 YouTube/Vimeo 嵌入链接。
captionstring否显示在播放器下方的纯文本标题。
altstring否视频元素的无障碍标签。
alignment'center' | 'left' | 'right'否播放器的水平对齐方式。可选值之一：center、left、right。
JSON
{
  "type": "video",
  "data": { "url": "/media/demo.mp4", "caption": "Product demo", "alignment": "center" }
}