GithubXDiscord

customization-guide > 理解和自定义 Notionpresso 结构

理解和自定义 Notionpresso 结构

要有效地自定义 Notionpresso,首先需要理解其基本结构和数据流。在本节中,我们将探讨 Notion 数据的结构,并基于此解释如何创建自定义组件。

理解数据结构

Notionpresso 使用的 Notion 数据采用 JSON 格式,包含页面信息和每个块的详细内容。理解这个结构是进行有效自定义的第一步。

基本数据结构

{
  "object": "page",
  "id": "page-id",
  "created_time": "2024-09-20T13:54:00.000Z",
  "last_edited_time": "2024-09-21T04:28:00.000Z",
  "cover": null,
  "icon": null,
  "parent": {
    "type": "page_id",
    "page_id": "parent-page-id"
  },
  "properties": {
    "title": {
      "id": "title",
      "type": "title",
      "title": [
        {
          "type": "text",
          "text": {
            "content": "页面标题",
            "link": null
          },
          "annotations": {
            "bold": false,
            "italic": false,
            "color": "default"
          },
          "plain_text": "页面标题"
        }
      ]
    }
  },
  "blocks": [
    {
      "object": "block",
      "id": "block-id-1",
      "type": "toggle",
      "toggle": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "折叠内容",
              "link": null
            },
            "annotations": {
              "bold": false,
              "italic": false,
              "color": "default"
            },
            "plain_text": "折叠内容"
          }
        ],
        "color": "default"
      },
      "blocks": [
        {
          "object": "block",
          "id": "block-id-2",
          "type": "paragraph",
          "paragraph": {
            "rich_text": [
              {
                "type": "text",
                "text": {
                  "content": "折叠内部段落",
                  "link": null
                },
                "annotations": {
                  "bold": false,
                  "italic": false,
                  "color": "default"
                },
                "plain_text": "折叠内部段落"
              }
            ],
            "color": "default"
          }
        }
      ]
    }
  ]
}

主要结构元素

  1. 页面元数据:包括页面的基本信息,如 idcreated_timelast_edited_timeparent 等。

  2. 封面和图标:页面的封面图片和图标信息。自定义设计时可以利用这些信息。

  3. 属性(properties):页面的属性信息,主要是页面标题(title)。创建自定义头部时可使用此信息。

  4. 块(blocks):构成页面内容的块数组。每个块具有以下结构:

  • object:始终为 "block"
  • id:块的唯一标识符
  • type:块的类型(例如:"toggle"、"paragraph"、"heading_1" 等)
  • [type]:与块类型对应的键,包含该块的具体内容
  • blocks:子块的数组,通过它形成递归结构
  1. 递归结构blocks 数组中的每个块可以再次包含 blocks 数组,用于表示嵌套结构。这在自定义折叠、列表等嵌套内容时非常重要。

  2. 富文本(rich_text):大部分文本内容以 rich_text 数组表示,包含文本的样式信息(annotations)。可通过它精细地自定义文本样式。

用于定制的组件结构

Notionpresso 的基本组件结构如下:

┌────────────────────────────────────────────────────────────────┐
│                           <Notion>                             │
│  ┌────────────────────────────────────────────────────────┐    │
│  │                        <Cover />                       │    │
│  │                  // Page cover image                   │    │
│  └────────────────────────────────────────────────────────┘    │
│                                                                │
│               ┌────────────────────────────┐                   │
│               │           <Body>           │                   │
│               │  ┌──────────────────────┐  │                   │
│               │  │      <Title />       │  │                   │
│               │  │    // Page title     │  │                   │
│               │  └──────────────────────┘  │                   │
│               │  ┌──────────────────────┐  │                   │
│               │  │      <Blocks>        │  │                   │
│               │  │ ┌──────────────────┐ │  │                   │
│               │  │ │<Block type="...">│ │  │                   │
│               │  │ │  // e.g. Heading │ │  │                   │
│               │  │ └──────────────────┘ │  │                   │
│               │  │ ┌──────────────────┐ │  │                   │
│               │  │ │<Block type="...">│ │  │                   │
│               │  │ │   // e.g. Para   │ │  │                   │
│               │  │ └──────────────────┘ │  │                   │
│               │  │         ...          │  │                   │
│               │  │  // More blocks      │  │                   │
│               │  └──────────────────────┘  │                   │
│               └────────────────────────────┘                   │
│                                                                │
└────────────────────────────────────────────────────────────────┘

在此结构中,&lt;Body&gt; 组件占据整体宽度的约 60%,并居中对齐。您可以基于此布局自定义各个组件。

定制策略

  1. 针对每个块类型的自定义组件:为每个块类型(paragraphheading_1toggle 等)创建自定义组件,以覆盖默认的样式和行为。

  2. 样式定制:利用 CSS 变量和类,调整整体设计。

  3. 布局修改:调整 <Body> 组件的宽度或对齐方式,以改变整体布局。

  4. 利用递归渲染:利用嵌套的块结构,实现复杂的布局或交互。

  5. 元数据利用:使用页面的元数据、封面图片、图标等,构建丰富的 UI。

理解这些结构和策略后,您可以基于 Notionpresso 创建高度定制化的 Notion 驱动网站。在接下来的章节中,我们将探讨每个元素的具体定制方法。