# Fumadocs Core (the core library of Fumadocs): 頁面樹
URL: /zh-TW/docs/headless/page-tree
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/page-tree.zh-TW.mdx

頁面樹的結構。

頁面樹是一種樹狀結構，用來描述所有導覽連結，以及分隔符、資料夾等其他項目。

頁面樹會傳送到用戶端，供側邊欄和 Breadcrumb 等導覽元素引用。
因此，請勿在頁面樹中存放任何敏感或大型的資料。

<Callout title="注意">
頁面樹在設計上只會包含所有頁面與資料夾的必要資訊。

無法序列化的資料 (例如函式) 無法傳入頁面樹。
</Callout>

## 慣例 [#conventions]

您可以匯入頁面樹的型別定義，若您想以寫死的方式定義或自動產生頁面樹，這會相當實用。

```ts
import type * as PageTree from 'fumadocs-core/page-tree';

const tree: PageTree.Root = {
  // props
};
```

部分節點包含 `$ref` 屬性，這類屬性僅供內部使用，以寫死 (hardcode) 方式定義時不需要用到。

### 根節點 [#root]

頁面樹的初始根節點。

### PageTreeRoot

| Prop           | Type                         | Description                                                               |
| -------------- | ---------------------------- | ------------------------------------------------------------------------- |
| `type?`        | `"root" \| undefined`        |                                                                           |
| `name`         | `React.ReactNode`            |                                                                           |
| `description?` | `React.ReactNode`            |                                                                           |
| `children`     | `PageTree.Node[]`            |                                                                           |
| `fallback?`    | `PageTree.Root \| undefined` | Another page tree that won't be displayed unless being opened.            |
| `$id?`         | `string \| undefined`        | ID for the node, unique in all page trees (even across different locales) |

### Page [#page]

代表連結的節點。

```json
{
  "type": "page",
  "name": "Quick Start",
  "url": "/docs"
}
```

> 也支援外部 URL

### PageTreeItem

| Prop           | Type                   | Description                                                                                                                 |
| -------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `type`         | `"page"`               |                                                                                                                             |
| `name`         | `React.ReactNode`      |                                                                                                                             |
| `url`          | `string`               |                                                                                                                             |
| `external?`    | `boolean \| undefined` | Whether the link should be treated as external (e.g. use HTML <a> tag). When unspecified, it depends on the value of `url`. |
| `description?` | `React.ReactNode`      |                                                                                                                             |
| `icon?`        | `React.ReactNode`      |                                                                                                                             |
| `$id?`         | `string \| undefined`  | ID for the node, unique in all page trees (even across different locales)                                                   |

### 資料夾 [#folder]

包含多個子節點的節點。

```json
{
    "type": "folder",
    "name": "Guide",
    "index": {
        "type": "page",
        ...
    }
    "children": [
        ...
    ]
}
```

### PageTreeFolder

| Prop           | Type                             | Description                                                                                                                                                                                                                                                      |
| -------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`         | `"folder"`                       |                                                                                                                                                                                                                                                                  |
| `name`         | `React.ReactNode`                |                                                                                                                                                                                                                                                                  |
| `description?` | `React.ReactNode`                |                                                                                                                                                                                                                                                                  |
| `root?`        | `string \| boolean \| undefined` | Mark as a root folder, `true` for the default type. A string value specifies its **root type**: root folders of the same type under the same parent scope are interchangeable (e.g. versions), and pages can map to their structural projection in another root. |
| `defaultOpen?` | `boolean \| undefined`           |                                                                                                                                                                                                                                                                  |
| `collapsible?` | `boolean \| undefined`           |                                                                                                                                                                                                                                                                  |
| `index?`       | `PageTree.Item \| undefined`     |                                                                                                                                                                                                                                                                  |
| `icon?`        | `React.ReactNode`                |                                                                                                                                                                                                                                                                  |
| `children`     | `PageTree.Node[]`                |                                                                                                                                                                                                                                                                  |
| `$id?`         | `string \| undefined`            | ID for the node, unique in all page trees (even across different locales)                                                                                                                                                                                        |

### 分隔項目 [#separator]

位於項目之間的標籤。

```json
{
  "type": "separator",
  "name": "Components"
}
```

### PageTreeSeparator

| Prop    | Type                  | Description                                                               |
| ------- | --------------------- | ------------------------------------------------------------------------- |
| `type`  | `"separator"`         |                                                                           |
| `name?` | `React.ReactNode`     |                                                                           |
| `icon?` | `React.ReactNode`     |                                                                           |
| `$id?`  | `string \| undefined` | ID for the node, unique in all page trees (even across different locales) |

## 圖示 [#icons]

圖示的型別為 `ReactElement`，頁面與資料夾皆可設定。