---
title: 定义并提供偏好设置
description: 声明应用偏好类型，并使用 SSR 安全快照挂载 Provider。
order: 10
toc:
  - id: declare-preferences
    title: 声明偏好设置
  - id: define-defaults
    title: 定义默认值
  - id: mount-the-provider
    title: 挂载 Provider
---

## 声明偏好设置 {#declare-preferences}

在应用拥有的 TypeScript 模块中使用模块扩充：

```ts
import "@workspace/preferences"

declare module "@workspace/preferences" {
  interface PreferencesCustom {
    "navigation-density": "comfortable" | "compact"
    "theme-mode": "light" | "dark" | "system"
  }
}
```

该声明会同时更新 `Preferences`、`PreferenceKey`、`PreferenceValue`、`PreferenceUpdate` 和两个偏好 Hooks 的类型。

## 定义默认值 {#define-defaults}

Definition 将解析、序列化、默认值和运行时校验放在一起：

```ts
const definitions = {
  "navigation-density": {
    cookie: "navigation-density",
    defaultValue: "comfortable",
    is: (value) => value === "comfortable" || value === "compact",
    parse: (value) => (value === "compact" ? "compact" : "comfortable"),
    serialize: (value) => value,
  },
  "theme-mode": {
    cookie: "theme-mode",
    defaultValue: "system",
    is: (value) => value === "light" || value === "dark" || value === "system",
    parse: (value) =>
      value === "light" || value === "dark" ? value : "system",
    serialize: (value) => value,
  },
} satisfies PreferenceDefinitions<Preferences>

const defaultPreferences = createDefaultPreferences(definitions)
```

## 挂载 Provider {#mount-the-provider}

将服务端得到的完整快照传给 Provider：

```tsx
<PreferencesProvider
  initialPreferences={preferences}
  onPreferenceChange={(update) => savePreference(update)}
>
  <App />
</PreferencesProvider>
```

通过类似 `useState` 的 API 读取单个偏好：

```tsx
const [themeMode, setThemeMode] = usePreference("theme-mode")
```