# 自定义字体列表

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

## 字体结构定义

在 Univer 中，字体使用 `IFontConfig` 接口进行定义：

| 属性         | 类型                                                                     | 说明                                           |
| ---------- | ---------------------------------------------------------------------- | -------------------------------------------- |
| `value`    | `string`                                                               | 字体的唯一标识符，通常也是 CSS font-family 的首选值。          |
| `label`    | `string`                                                               | 用于国际化的翻译键，如果在 Univer 实例创建时没有指定该键值时，则直接显示传入值。 |
| `category` | `'sans-serif' \| 'serif' \| 'monospace' \| 'display' \| 'handwriting'` | 字体类别，用于 UI 分组（可选）。                           |

> [!NOTE]
> Univer 不会阻止用户选择未安装的字体，如果客户端没有安装某个字体，浏览器会直接使用默认字体进行替代显示。

## 使用自定义字体

你可以通过配置 `UniverUIPlugin` 的 `customFontFamily` 参数来定义字体下拉菜单中的选项。

```typescript
univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
  customFontFamily: {
    list: [
      {
        value: 'PingFang SC',
        label: '苹方（简）',
        category: 'sans-serif',
      },
      {
        value: 'Helvetica Neue',
        label: 'Helvetica Neue',
        category: 'sans-serif',
      },
    ],
    // 是否覆盖默认字体列表，默认为 false
    override: true,
  },
})
```

### Facade API

除了在初始化时配置，你还可以通过 Facade API 在运行时动态注册新的字体。这在需要异步加载字体资源的场景下非常有用。

```typescript
univerAPI.addFonts([{
  value: 'PingFang SC',
  label: '苹方（简）',
  category: 'sans-serif',
}, {
  value: 'Helvetica Neue',
  label: 'Helvetica Neue',
  category: 'sans-serif',
}])
```