75 lines
1.9 KiB
Plaintext
75 lines
1.9 KiB
Plaintext
|
---
|
||
|
|
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")
|
||
|
|
```
|