# 自定义字体列表

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [pdfs/ui/fonts.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/pdfs/ui/fonts.zh-CN.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`。