docs(appearance): add bilingual package guides

2026-09-21 16:05:19 +08:00
parent e2dbbcb884
commit 6711401f5f
9 changed files with 490 additions and 0 deletions
@@ -0,0 +1,41 @@
+---
+title: 原子化组合
+description: 不依赖预设弹窗，使用受控组件构建自己的外观界面。
+order: 1
+toc:
+  - id: controlled-atoms
+    title: 受控原子组件
+  - id: compose-card
+    title: 组合主题卡片
+  - id: connected-layer
+    title: 状态连接层
+---
+
+## 受控原子组件 {#controlled-atoms}
+
+`ThemeModeField`、`CompactLayoutField`、`ThemeColorPicker` 和 `ThemeToggle` 都由 `value` 与回调驱动。它们不要求使用偏好上下文，因此可以接入表单、预览工具或其他状态库。
+
+```tsx
+<ThemeModeField value={mode} onValueChange={setMode} />
+<CompactLayoutField checked={compacted} onCheckedChange={setCompacted} />
+```
+
+## 组合主题卡片 {#compose-card}
+
+`ThemeConfigCard` 把预览、基础色和强调色选择组合在一起，但仍由调用方持有配置。
+
+```tsx
+<ThemeConfigCard
+  active={resolvedTheme === "light"}
+  compacted={compacted}
+  config={lightTheme}
+  onConfigChange={setLightTheme}
+  scheme="light"
+/>
+```
+
+需要更细粒度的布局时，可以分别使用 `ThemePreview`、`baseColorSwatches`、`accentColorSwatches` 和 `ThemeColorSwatchButton`。
+
+## 状态连接层 {#connected-layer}
+
+`AppearanceSettings` 是原子组件与共享 `PreferencesProvider` 之间的默认连接层。自定义界面可以直接使用 `@workspace/preferences` 的 `usePreference` 读取单个字段，而不必复用默认布局。