GithubXDiscord

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❌ 否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 结构、使用示例以及自定义选项。