block-types > 块类型指南介绍
块类型指南介绍
Notionpresso 支持多种 Notion 块类型,并为每种块类型提供与 Notion 风格尽可能相似的组件。本指南将介绍当前支持的块类型、每种块类型的 Props、自定义方法以及内部工作原理。
支持的块类型
以下是 Notionpresso 当前支持的块类型和计划支持的块类型列表:
Block Type | 支持状态 | Block Type Enum |
---|---|---|
Paragraph | ✅ 是 | paragraph |
Heading 1 | ✅ 是 | heading_1 |
Heading 2 | ✅ 是 | heading_2 |
Heading 3 | ✅ 是 | heading_3 |
Bulleted List Item | ✅ 是 | bulleted_list_item |
Numbered List Item | ✅ 是 | numbered_list_item |
To-do | ❌ 否 | to_do |
Toggle | ✅ 是 | toggle |
Quote | ✅ 是 | quote |
Callout | ✅ 是 | callout |
Equation | ❌ 否 | equation |
Code | ❌ 否 | code |
Image | ❌ 否 | image |
Video | ❌ 否 | video |
Bookmark | ❌ 否 | bookmark |
Divider | ✅ 是 | divider |
Table | ❌ 否 | table |
Table Row | ❌ 否 | table_row |
Column | ❌ 否 | column |
Column List | ❌ 否 | column_list |
Audio | ❌ 否 | audio |
Synced Block | ❌ 否 | synced_block |
Table Of Contents | ❌ 否 | table_of_contents |
Embed | ❌ 否 | embed |
Figma | ❌ 否 | figma |
Google Maps | ❌ 否 | maps |
Google Drive | ❌ 否 | drive |
Tweet | ❌ 否 | tweet |
❌ 否 | pdf | |
File | ❌ 否 | file |
Link | ❌ 否 | text (inline) |
Page Link | ❌ 否 | page |
External Page Link | ❌ 否 | text (inline) |
Collections | ❌ 否 | - |
Collection View | ❌ 否 | collection_view |
Collection View Table | ❌ 否 | collection_view |
Collection View Gallery | ❌ 否 | collection_view |
Collection View Board | ❌ 否 | collection_view |
Collection View List | ❌ 否 | collection_view |
Collection View Calendar | ❌ 否 | collection_view |
Collection View Page | ❌ 否 | collection_view_page |
此列表将持续更新,未来计划支持更多块类型。
Props 使用方法
Notionpresso 为每种块类型提供 Props 类型。这些 Props 类型可以直接从库中导入使用。
例如,Paragraph 组件的 Props 可以这样导入和使用:
import { ParagraphProps } from "@notionpresso/react";
// ParagraphProps的结构
interface ParagraphProps {
type: "paragraph";
paragraph: {
rich_text: Array<RichTextItemResponse>;
color: string;
};
id: string;
has_children?: boolean;
}
// 使用示例
const MyParagraph: React.FC<ParagraphProps> = (props) => {
// 自定义实现
};
每种块类型的 Props 的详细结构可以在相应块类型的文档中查看。
自定义组件应用
Notionpresso 的一大优点是,可以完全替换每种块类型。自定义组件的应用方法如下:
import { Notion } from "@notionpresso/react";
import CustomParagraph from "./CustomParagraph";
import CustomHeading from "./CustomHeading";
const customComponents = {
paragraph: CustomParagraph,
heading_1: CustomHeading,
heading_2: CustomHeading,
heading_3: CustomHeading,
// ... 其他块类型对应的定制组件
};
function MyNotionPage({ blocks }) {
return (
<Notion custom={customComponents}>
<Notion.Blocks blocks={blocks} />
</Notion>
);
}
Notion
组件中注入的 components
的类型如下:
type NotionComponents = Record<string, React.ComponentType<any>>;
这里,key
是 Notion 块的类型(例如 'paragraph', 'heading_1' 等),value
是用于渲染该类型的 React 组件。
数据预处理过程
Notionpresso 将 Notion API 获取的块数据转换为适合 UI 渲染的格式。在此过程中,定义了一个新的类型 ContextedBlock
来使用。
+----------------------+
| Notion API |
| Block Data |
| +------------------+ |
| | Block | |
| | - id | |
| | - type | |
| | - has_children | |
| | - [type_specific]| |
| +------------------+ |
+----------------------+
|
| (Input)
v
+---------------------------+
| resolveToContextedBlocks |
| +-------------------------+
| | For each block: |
| | +---------------------+ |
| | |resolveToContextedBlo| |
| | |ck (recursive) | |
| | +---------------------+ |
| | | |
| | v |
| | Map parent-child |
| | relationships |
| +-------------------------+
| |
| v
| Map sibling relationships |
+---------------------------+
|
| (Output)
v
+---------------------------+
| ContextedBlocks |
| +-------------------------+
| | ContextedBlock |
| | - ...Block properties |
| | - context: |
| | - previous (sibling) |
| | - next (sibling) |
| | - parent |
| | - blocks (children) |
| +-------------------------+
+---------------------------+
|
| (Used by)
v
+----------------+
| Notion.Blocks |
| Component |
+----------------+
ContextedBlock
扩展了原有的 Block
类型,包含以下额外信息:
- 前一个块(兄弟关系)
- 下一个块(兄弟关系)
- 父块
这些额外信息在某些块组件中非常有用。
渲染过程
Notionpresso 的渲染过程如下:
+-------------------+ +------------------+
| Custom | | Default |
| Components | | Components |
+-------------------+ +------------------+
| |
| +-----------------+ |
+-->| Notion |<--+
| Component |
|(React.Provider) |
+-----------------+
| |
+----------+ +------------+
| |
+----------------+ +----------------+
| Notion.Cover | | Notion.Body |
+----------------+ +----------------+
|
+----------------+
| Notion.Title |
+----------------+
|
+----------------+
| Notion.Blocks |
+----------------+
|
v
+----------------+
| Rendered |
| Notion Page |
+----------------+
通过此过程,定制组件和默认组件可以协同工作,渲染 Notion 页面。
样式
当前提供的 Notion 组件尽可能地模仿 Notion 的样式。每个组件都使用 notion-
前缀的 CSS 类进行样式化。
未来计划
- 支持更多块类型
- 开发带有主题的组件集
- 扩展高级自定义选项
后续页面将详细介绍每种块类型、其 Props 结构、使用示例以及自定义选项。