docs(appearance): document preference hooks

2026-09-29 22:12:56 +08:00
parent 642cb71b93
commit e34675a931
4 changed files with 68 additions and 2 deletions
@@ -57,7 +57,18 @@ toc:

 ## 状态连接层 {#connected-layer}

-`AppearanceSettings` 是原子组件与共享 `PreferencesProvider` 之间的默认连接层。自定义界面可以直接使用 `@workspace/preferences` 的 `usePreference` 读取单个字段，而不必复用默认布局。
+`AppearanceSettings` 是原子组件与共享 `PreferencesProvider` 之间的默认连接层。自定义界面可以使用 Appearance 提供的 `useThemeMode`、`useThemeConfig`、`useResolvedTheme` 等 hooks，而不必知道共享偏好的字符串键，也不必复用默认布局。
+
+```tsx
+const [themeConfig, setThemeConfig] = useThemeConfig()
+const resolvedTheme = useResolvedTheme()
+
+<ThemeConfigCard
+  config={themeConfig}
+  onConfigChange={setThemeConfig}
+  scheme={resolvedTheme}
+/>
+```

 ## 在线预览 {#live-preview}

@@ -9,6 +9,8 @@ toc:
    title: 原子组件
  - id: preferences
    title: 偏好集成
+  - id: hooks
+    title: Hooks
 ---

 ## 包的职责 {#package-role}
@@ -66,3 +68,23 @@ export function App() {
 色彩辨识辅助不会给整个页面或图片添加滤镜。它只替换 `destructive` 与 `chart-*` 等语义颜色，并在 `<html>` 上写入 `data-ui-color-vision`，供业务组件添加图标、文字、形状或纹理。关键信息不能只靠颜色表达。

 文字、动态效果和亮度同样只通过根节点属性与 CSS 变量实现。导入 Appearance 样式后，现有 UI 组件、Portal 和应用内容都会继承这些设置。
+
+## Hooks {#hooks}
+
+应用不需要知道 Appearance 在共享 store 中使用的字符串键。Package 为每个偏好提供了语义化 hook：`useThemeMode`、`useAccentColor`、`useBaseColor`、`useColorVisionMode`、`useTextScale`、`useMotionMode` 和 `useBrightness`。
+
+组合和解析类 hook 用于更高层的界面：
+
+- `useThemeConfig` 将基础色和强调色作为一个配置读写。
+- `useSystemTheme` 与 `useSystemMotion` 只读取操作系统设置。
+- `useResolvedTheme` 与 `useResolvedMotion` 解析 `system` 后返回最终值。
+- `useToggleTheme` 返回在显式浅色与深色之间切换的回调。
+- `useAppearancePreference` 提供类型安全的底层入口，`useAppearancePreferences` 返回 Appearance 所有偏好的快照。
+
+```tsx
+const [themeMode, setThemeMode] = useThemeMode()
+const [themeConfig, setThemeConfig] = useThemeConfig()
+const resolvedTheme = useResolvedTheme()
+const resolvedMotion = useResolvedMotion()
+const toggleTheme = useToggleTheme()
+```