2026-09-21 16:05:19 +08:00
|
|
|
---
|
|
|
|
|
title: 原子化组合
|
|
|
|
|
description: 不依赖预设弹窗，使用受控组件构建自己的外观界面。
|
|
|
|
|
order: 1
|
|
|
|
|
toc:
|
|
|
|
|
- id: controlled-atoms
|
|
|
|
|
title: 受控原子组件
|
|
|
|
|
- id: compose-card
|
|
|
|
|
title: 组合主题卡片
|
|
|
|
|
- id: connected-layer
|
|
|
|
|
title: 状态连接层
|
2026-09-21 17:09:54 +08:00
|
|
|
- id: live-preview
|
|
|
|
|
title: 在线预览
|
2026-09-21 16:05:19 +08:00
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## 受控原子组件 {#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` 读取单个字段，而不必复用默认布局。
|
2026-09-21 17:09:54 +08:00
|
|
|
|
|
|
|
|
## 在线预览 {#live-preview}
|
|
|
|
|
|
|
|
|
|
文档 Sandbox 可以加载通过类型检查的多文件示例，而不需要把实现细节内联到 MDX：
|
|
|
|
|
|
|
|
|
|
<Sandbox example="appearance/theme-colors" title="主题颜色控件" />
|
|
|
|
|
|
|
|
|
|
单文件示例不需要创建 Manifest，直接导入组件和原始源码即可：
|
|
|
|
|
|
|
|
|
|
```mdx
|
|
|
|
|
import Demo from "./Demo"
|
|
|
|
|
import source from "./Demo.tsx?raw"
|
|
|
|
|
|
|
|
|
|
<SingleFileSandbox component={Demo} filename="Demo.tsx" source={source} />
|
|
|
|
|
```
|
