块参考

本页记录编辑器附带的每一种块类型。每个块都有 JSON 形状、渲染器，以及通过 editor.blocks.insert 的编程插入路径。

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

区块结构

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

JSON

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

alert

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

字段	类型	必填	描述
html	string	是	提示消息的 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 回调进行处理。

字段	类型	必填	描述
url	string	是	要嵌入的音频文件的 URL。
caption	string	否	显示在播放器下方的纯文本标题。
alt	string	否	音频元素的无障碍标签。
alignment	'center' \| 'left' \| 'right'	否	播放器的水平对齐方式。可选值之一：center、left、right。

JSON

{
  "type": "audio",
  "data": { "url": "/media/podcast.mp3", "caption": "Episode 12", "alignment": "center" }
}

checklist

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

字段	类型	必填	描述
items	ChecklistItem[]	是	清单项的数组，每项包含 text 和 checked 状态。
items[].text	string	是	项目标签的 HTML 内容。
items[].checked	boolean	是	复选框是否已选中。

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。

字段	类型	必填	描述
code	string	是	要显示的原始代码字符串。
language	CodeLanguage	否	语法高亮语言。默认为 typescript。
theme	CodeTheme	否	编辑器颜色主题。默认为 github-dark。
showCopy	boolean	否	在渲染输出中显示复制按钮。
syncKey	string	否	共享同一 key 的块会一起切换语言。
variants	CodeVariant[]	否	非空时渲染标签页条，并作为权威来源。

JSON

{
  "type": "code",
  "data": { "code": "const x = 42;", "language": "typescript", "theme": "github-dark", "showCopy": true }
}

collapsible

带标题和嵌套子块的可折叠区块。未知的子块类型会原样保留，因此较新的文档在较旧的渲染器上也能存活。

字段	类型	必填	描述
html	string	是	区块标题，内联 HTML。
open	boolean	否	该区块是否以展开状态渲染。
children	Block[]	否	嵌套的子块。

JSON

{
  "type": "collapsible",
  "data": {
    "html": "Details",
    "open": true,
    "children": [{ "type": "paragraph", "data": { "html": "Hidden until opened." } }]
  }
}

collection

按 id 嵌入一个实时集合视图。块只存储集合的身份；形态和数据归服务器所有。

字段	类型	必填	描述
collectionId	string	是	嵌入集合的 id。唯一存储的内容。

JSON

{
  "type": "collection",
  "data": { "collectionId": "c-42" }
}

columns

2 到 4 列的多列布局，每列持有自己的子块列表。

字段	类型	必填	描述
columns	Block[][]	是	各列，每列是一组子块。二到四列。

JSON

{
  "type": "columns",
  "data": {
    "columns": [
      [{ "type": "paragraph", "data": { "html": "Left" } }],
      [{ "type": "paragraph", "data": { "html": "Right" } }]
    ]
  }
}

date

一个日历日期，存储时不带时区，因此每位协作者看到的都一致。

字段	类型	必填	描述
date	string	是	ISO 日期，yyyy-MM-dd 形式，不带时区。

JSON

{
  "type": "date",
  "data": { "date": "2026-08-31" }
}

delimiter

章节之间的视觉分隔符。

字段	类型	必填	描述
variant	'line' \| 'stars'	是	分隔符的视觉样式。可选值之一：line、stars。

JSON

{
  "type": "delimiter",
  "data": { "variant": "line" }
}

doc_card

指向另一个文档的富链接卡片。它存储被引用页面的 id 和一份显示快照，重命名时由宿主刷新。

字段	类型	必填	描述
pageId	string	是	被引用页面的 id；卡片的身份。
title	string	是	页面标题的显示快照。
icon	string	否	卡片上显示的可选图标。
description	string	否	标题下方显示的可选描述。

JSON

{
  "type": "doc_card",
  "data": { "pageId": "p-7", "title": "Release notes", "icon": "📄" }
}

embed

一个嵌入式链接。块存储 URL；提供方和嵌入标记在渲染时推导，unfurl 字段作为后备卡片。

字段	类型	必填	描述
url	string	是	嵌入的链接。提供方和嵌入标记在渲染时由它推导。
title	string	否	链接卡片的 unfurl 快照。
description	string	否	链接卡片的 unfurl 描述。
imageUrl	string	否	链接卡片的 unfurl 预览图。
display	'card'	否	"card" 表示即使有实时视图也显示链接卡片。
file	object	否	Drive 文件的名称、类型和图标，来自粘贴者的 Google 账号。
gist	object	否	粘贴时的 gist 文件，在无法加载 GitHub 自身视图的地方以代码形式绘制。
reason	string	否	为何未显示实时视图：connect_google、no_access、provider_unreachable 或 switched_off。
issue	object	否	显示为卡片的事项链接：最近一次读取的快照（tool、key、title、stateName、category、assigneeName、updatedAt、reason）。

JSON

{
  "type": "embed",
  "data": { "url": "https://www.youtube.com/watch?v=abc123" }
}

file

一个文件附件，带下载链接、名称，以及可选的大小和内容类型。

字段	类型	必填	描述
url	string	是	文件的托管地址。
name	string	是	附件上显示的文件名。
size	number	否	文件大小，以字节计。
contentType	string	否	文件的 MIME 类型。

JSON

{
  "type": "file",
  "data": { "url": "/files/notes.pdf", "name": "notes.pdf", "size": 2048, "contentType": "application/pdf" }
}

glance

标签与值的摘要面板：一眼可读的事实行，带可选的说明文字和背景变体。

字段	类型	必填	描述
rows	GlanceRow[]	是	要展示的事实：每行是一个标签和一个内联 HTML 值。
caption	string	否	行上方的可选说明文字。
variant	'plain' \| 'error' \| 'info' \| 'success' \| 'warning'	否	背景变体；plain 为无样式，其余与警告块调色板一致。

JSON

{
  "type": "glance",
  "data": {
    "caption": "Facts",
    "rows": [{ "label": "Version", "html": "<b>1.0</b>" }],
    "variant": "plain"
  }
}

header

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

字段	类型	必填	描述
html	string	是	标题的 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 回调进行处理。

字段	类型	必填	描述
url	string	是	要嵌入的图像的 URL。
caption	string	否	显示在图像下方的纯文本标题。
alt	string	否	图像元素的 alt 文本。
alignment	'center' \| 'left' \| 'right'	否	图像的水平对齐方式。可选值之一：center、left、right。

JSON

{
  "type": "image",
  "data": { "url": "/img/hero.jpg", "caption": "Hero image", "alt": "A hero", "alignment": "center" }
}

issues

渲染时从页面中的事项标签与卡片推导出的关联事项表（事项、标题、状态、负责人）。它不存储自己的数据。

该块不存储任何字段；行在渲染时从页面中的事项标签与卡片推导。

JSON

{
  "type": "issues",
  "data": {}
}

latex

LaTeX 数学，以源码存储并在渲染时排版。将来更好的渲染器会让已有的每个文档受益。

字段	类型	必填	描述
source	string	是	LaTeX 源码。以源码存储，绝不存储渲染结果。

JSON

{
  "type": "latex",
  "data": { "source": "\\frac{a}{b}" }
}

list

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

字段	类型	必填	描述
type	'ordered' \| 'unordered'	是	列表类型。可选值之一：ordered、unordered。
items	string[]	是	HTML 字符串的数组，每个列表项一个。

JSON

{
  "type": "list",
  "data": { "type": "unordered", "items": ["First item", "Second item"] }
}

mermaid

一个 Mermaid 图表，以源码存储并在显示时绘制，绝不存储为位图。

字段	类型	必填	描述
source	string	是	Mermaid 源码。以源码存储，绝不存储绘制结果。

JSON

{
  "type": "mermaid",
  "data": { "source": "flowchart TD\n  A --> B" }
}

openapi

根据 OpenAPI 3.x 文档渲染交互式 API 参考，可内联或从 URL 获取，带服务器选择器和代码片段。

字段	类型	必填	描述
spec	object	否	内联的 OpenAPI 3.x 文档。两者都设置时优先于 url。
url	string	否	渲染时从哪里获取 OpenAPI 文档。
include	OpenApiFilter	否	筛选要渲染哪些操作。
exclude	OpenApiFilter	否	筛选要隐藏哪些操作。
defaultServer	string	否	参考默认选中的服务器。
snippetLanguages	CodeLanguage[]	否	请求代码片段提供的语言。

JSON

{
  "type": "openapi",
  "data": { "url": "/api/openapi.json", "defaultServer": "https://api.example.com" }
}

paragraph

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

字段	类型	必填	描述
html	string	是	段落的 HTML 内容。支持行内工具标记。

JSON

{
  "type": "paragraph",
  "data": { "html": "This is a <b>paragraph</b> with inline markup." }
}

quote

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

字段	类型	必填	描述
html	string	是	引用正文的 HTML 内容。支持行内工具标记。
author	string	否	显示在引用下方的纯文本或 HTML 署名。

JSON

{
  "type": "quote",
  "data": { "html": "The best way to predict the future is to invent it.", "author": "Alan Kay" }
}

sketch

以笔画存储的手绘图，绝不是位图，因此始终可编辑并能干净地缩放。

字段	类型	必填	描述
strokes	SketchStroke[]	是	以笔画表示的绘图：每个笔画是一组点，带可选的颜色和宽度。

JSON

{
  "type": "sketch",
  "data": { "strokes": [{ "points": [0, 0, 10, 10], "color": "#ff0000", "width": 3 }] }
}

table

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

字段	类型	必填	描述
data	string[][]	是	HTML 单元格字符串的二维数组。第一行是表头行。
caption	string	否	显示在表格下方的纯文本或 HTML 标题。
showDownload	boolean	否	在渲染输出中显示下载按钮。

JSON

{
  "type": "table",
  "data": {
    "data": [["Name", "Type"], ["html", "string"], ["variant", "AlertVariant"]],
    "caption": "AlertData fields",
    "showDownload": false
  }
}

updates

文档的实时动态流。它存储的是身份而非快照，因此始终显示当前活动。

字段	类型	必填	描述
pageId	string	否	显示哪个文档的活动。缺省表示块所在的文档。

JSON

{
  "type": "updates",
  "data": { "pageId": "p-7" }
}

video

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

字段	类型	必填	描述
url	string	是	视频文件的 URL 或 YouTube/Vimeo 嵌入链接。
caption	string	否	显示在播放器下方的纯文本标题。
alt	string	否	视频元素的无障碍标签。
alignment	'center' \| 'left' \| 'right'	否	播放器的水平对齐方式。可选值之一：center、left、right。

JSON

{
  "type": "video",
  "data": { "url": "/media/demo.mp4", "caption": "Product demo", "alignment": "center" }
}

参考

软件包

块参考

区块结构

alert

audio

checklist

code

collapsible

collection

columns

date

delimiter

doc_card

embed

file

glance

header

image

issues

latex

list

mermaid

openapi

paragraph

quote

sketch

table

toc

updates

video