# 自訂字型列表

- Human documentation: [https://docs.univer.ai/zh-TW/guides/pdfs/ui/fonts](https://docs.univer.ai/zh-TW/guides/pdfs/ui/fonts)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/pdfs/ui/fonts.md](https://docs.univer.ai/zh-TW/guides/pdfs/ui/fonts.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [pdfs/ui/fonts.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/pdfs/ui/fonts.zh-TW.mdx)

---

PDF 文字與編輯器的字型選單使用兩個相關但不同的資料來源。

| 資料來源                                    | 控制內容                        |
| --------------------------------------- | --------------------------- |
| `document.assets.fonts` 與文字片段的 `fontId` | 用來還原原生內容的已匯入 PDF 字型中繼資料與資源。 |
| 可編輯文字片段的 `fontFamily`                   | 可編輯文字配置與繪製時使用的 CSS 字型家族。    |
| Univer 共用字型清單                           | PDF 屬性面板字型下拉選單顯示的選項。        |

在共用清單加入選項，不會在 `document.assets.fonts` 新增資源，也不會下載或嵌入字型檔案。

## 設定編輯器字型清單

當 `editor.enabled` 為 `true` 時，PDF 屬性面板使用共用的 `FontFamilyDropdown`。請在瀏覽器設定的 `UniverUIPlugin` 中設定清單：

```ts
import { UniverUIPlugin } from '@univerjs/ui'

univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
  customFontFamily: {
    list: [
      {
        value: 'Inter',
        label: 'Inter',
        category: 'sans-serif',
      },
      {
        value: 'Noto Serif',
        label: 'Noto Serif',
        category: 'serif',
      },
    ],
    override: false,
  },
})
```

請透過 `@font-face` 或樣式表自行載入瀏覽器字型，否則 Canvas 會使用瀏覽器的替代字型。

## 在執行階段新增選項

載入 UI Facade 後，可以用 `addFonts` 向同一個共用清單追加選項：

```ts
univerAPI.addFonts([
  {
    value: 'Inter',
    label: 'Inter',
    category: 'sans-serif',
  },
])
```

此方法只會更新應用程式字型清單，不會載入字型二進位資料，也不會改寫既有 PDF 文字片段。

## 為可編輯 PDF 文字設定字型

插入文字時傳入 `fontFamily`，或透過 PDF Facade 更新可編輯文字方塊：

```ts
const page = univerAPI.getActivePdf()?.getPageByIndex(0)
const textBox = page?.insertTextBox({
  text: 'Hello PDF',
  fontFamily: 'Inter',
  fontSize: 14,
  left: 36,
  top: 36,
})

textBox?.setTextStyle({ fontFamily: 'Noto Serif' })
```

`page.getTextSpans()` 傳回的原生匯入文字是快照，不能直接修改樣式。請先呼叫 `replaceText(...)` 將其提升為可編輯文字方塊，再呼叫 `setTextStyle`。