# 註腳與章節附註

- Human documentation: [https://docs.univer.ai/zh-TW/guides/docs/features/footnotes](https://docs.univer.ai/zh-TW/guides/docs/features/footnotes)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/docs/features/footnotes.md](https://docs.univer.ai/zh-TW/guides/docs/features/footnotes.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [docs/features/footnotes.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/features/footnotes.zh-TW.mdx)

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-docs-advanced",
      "locale": "@univerjs/preset-docs-advanced/locales/zh-TW",
      "style": "@univerjs/preset-docs-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/docs-reference",
      "facade": "@univerjs-pro/docs-reference/facade"
    },
    {
      "client": "@univerjs-pro/docs-reference-ui",
      "locale": "@univerjs-pro/docs-reference-ui/locale/zh-TW",
      "style": "@univerjs-pro/docs-reference-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

在傳統分頁文件中插入註腳與章節附註。註腳排版於參照所在頁面，章節附註依文件設定放置。此 API 不支援現代文件。

## 安裝

將以下外掛加入已設定授權的 Docs 編輯器，並載入 UI 樣式及符合編輯器語言的資源。

`UniverDocsAdvancedPreset` 已包含這兩個外掛，使用該 preset 時不必再次註冊。

#### npm

```bash
npm install @univerjs-pro/docs-reference @univerjs-pro/docs-reference-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/docs-reference @univerjs-pro/docs-reference-ui
```

#### yarn

```bash
yarn add @univerjs-pro/docs-reference @univerjs-pro/docs-reference-ui
```

#### bun

```bash
bun add @univerjs-pro/docs-reference @univerjs-pro/docs-reference-ui
```

```ts
import { UniverDocsReferencePlugin } from '@univerjs-pro/docs-reference'
import { UniverDocsReferenceUIPlugin } from '@univerjs-pro/docs-reference-ui'
import ReferenceLocale from '@univerjs-pro/docs-reference-ui/locale/zh-TW'
import { LocaleType } from '@univerjs/core'

import '@univerjs-pro/docs-reference/facade'
import '@univerjs-pro/docs-reference-ui/lib/index.css'

univerAPI.loadLocales(LocaleType.ZH_TW, ReferenceLocale)
univer.registerPlugin(UniverDocsReferencePlugin)
univer.registerPlugin(UniverDocsReferenceUIPlugin)
```

## 插入與管理附註

```ts
const document = univerAPI.getActiveDocument()
if (document) {
  const noteId = document.insertFootnote(0)
  if (noteId) console.log(document.getParagraphs(noteId))
  console.log(document.getFootnotes(), document.getEndnotes())
}
```

位移是正文中的 UTF-16 位置，包含結構標記。位置或內容無效、缺少編輯權限，或使用現代文件時，插入會回傳 `null`；成功時回傳穩定的附註 ID。參照與附註內容使用同一次復原及協同 mutation。

以 `getFootnotes()` / `getEndnotes()` 讀取，以 `deleteFootnote(noteId)` / `deleteEndnote(noteId)` 刪除。`setFootnoteSettings()` 與 `setEndnoteSettings()` 設定編號及位置，傳入 `null` 可重設明確設定。請保存回傳的附註 ID 以定位內容；顯示編號可能因重新分頁而改變。