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,49 @@
+---
+title: 外观设置弹窗
+description: 组合触发器、控制器和快捷键得到完整的外观设置流程。
+order: 1
+toc:
+  - id: controller
+    title: 挂载控制器
+  - id: trigger
+    title: 添加触发器
+  - id: custom-handle
+    title: 独立弹窗实例
+---
+
+## 挂载控制器 {#controller}
+
+在应用共享的 `PreferencesProvider` 内挂载一次 `AppearanceController`。它组合默认设置内容，并注册 `Mod+,` 打开弹窗和 `Mod+D` 切换主题。
+
+```tsx
+<PreferencesProvider
+  effects={[appearancePreferenceEffect]}
+  initialPreferences={preferences}
+>
+  <AppearanceController />
+  <App />
+</PreferencesProvider>
+```
+
+## 添加触发器 {#trigger}
+
+`AppearanceDialogTrigger` 可以放在用户菜单、设置按钮或命令面板中。默认情况下，它会连接到默认控制器使用的 handle。
+
+```tsx
+<AppearanceDialogTrigger render={<button type="button" />}>
+  界面外观
+</AppearanceDialogTrigger>
+```
+
+## 独立弹窗实例 {#custom-handle}
+
+页面中需要隔离的外观弹窗时，为控制器和触发器传入同一个新 handle。
+
+```tsx
+const handle = createAppearanceDialogHandle()
+
+<AppearanceDialogTrigger handle={handle} render={<button type="button" />}>
+  打开主题设置
+</AppearanceDialogTrigger>
+<AppearanceController handle={handle} />
+```