V2
Block 类型
查看 V2 API 支持的 block 类型全集和可写 block 类型范围。
Block 类型
适用范围
本页只列出 V2 API 支持的 block 类型全集，以及哪些类型可以通过 API 写入。block 的统一对象字段和分页规则不在这里展开。
核心定义
V2 API 会区分“可读取的 block 类型”和“可写入的 block 类型”。可写入类型是可读取类型中的一个子集。
字段说明或规则
可读取 block 类型全集
| 类型 | 说明 | 是否可写 |
|---|---|---|
paragraph | 普通段落。 | 是 |
heading_1 | 一级标题。 | 是 |
heading_2 | 二级标题。 | 是 |
heading_3 | 三级标题。 | 是 |
bulleted_list_item | 无序列表项。 | 是 |
numbered_list_item | 有序列表项。 | 是 |
to_do | 待办项。 | 是 |
quote | 引用块。 | 是 |
code | 代码块。 | 是 |
callout | 提示块。 | 是 |
divider | 分割线。 | 是 |
bookmark | 书签块。 | 是 |
embed | 嵌入块。 | 是 |
image | 图片块。 | 是 |
file | 文件块。 | 是 |
table | 表格块。 | 是 |
table_row | 表格行。 | 是 |
toggle | 折叠块。 | 是 |
equation | 公式块。 | 是 |
link_to_page | 页面或数据库链接块。 | 是 |
child_page | 子页面占位块。 | 否 |
child_database | 子数据库占位块。 | 否 |
template | 模板块。 | 否 |
synced_block | 同步块。 | 否 |
column_list | 栏目容器。 | 否 |
column | 单个栏目。 | 否 |
可写 block 类型
可写 block 类型只包含以下 20 种：
paragraphheading_1heading_2heading_3bulleted_list_itemnumbered_list_itemto_doquotecodecalloutdividerbookmarkembedimagefiletabletable_rowtoggleequationlink_to_page
类型使用规则
table_row只应该作为table的子内容使用。child_page、child_database、template、synced_block、column_list、column是系统侧布局或派生类型，不作为普通写入目标。children是否可见，取决于 block 类型和has_children。image、file、bookmark、embed等富媒体块的字段结构与普通文本块不同，按类型分别填写。
常见注意事项
- 写入时只接受可写 block 类型，不要把只读类型当成普通 block 创建。
link_to_page同时支持页面和数据库链接，具体字段由其内容结构决定。- 代码块、表格和媒体块的内容字段较强类型化，构造请求体时不要用纯文本代替。