# 自訂字型列表

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [docs/ui/fonts.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/ui/fonts.zh-TW.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: 'PingFang SC',
  category: 'sans-serif',
}, {
  value: 'Helvetica Neue',
  label: 'Helvetica Neue',
  category: 'sans-serif',
}])
```