feat(docs): add bilingual package documentation site

2026-09-20 15:53:28 +08:00
parent 60f6f1fb1a
commit dc80bd8ae0
111 changed files with 6531 additions and 0 deletions
@@ -0,0 +1,74 @@
+---
+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")
+```