---
title: 原子化组合
description: 不依赖预设弹窗，使用受控组件构建自己的外观界面。
order: 1
toc:
  - id: controlled-atoms
    title: 受控原子组件
  - id: compose-card
    title: 组合主题卡片
  - id: connected-layer
    title: 状态连接层
  - id: live-preview
    title: 在线预览
---

## 受控原子组件 {#controlled-atoms}

`ThemeModeField`、`ThemeModeOptionList`、`ColorVisionModeField`、`TextScaleField`、`TextScaleOptionList`、`MotionModeField`、`BrightnessField`、`ThemeColorPicker` 和 `ThemeToggle` 都由 `value` 与回调驱动。它们不要求使用偏好上下文，因此可以接入表单、预览工具或其他状态库。

```tsx
<ThemeModeField value={mode} onValueChange={setMode} />
<ThemeModeOptionList value={mode} onValueChange={setMode} />
<ColorVisionModeField value={colorVisionMode} onValueChange={setColorVisionMode} />
<TextScaleField value={textScale} onValueChange={setTextScale} />
<MotionModeField value={motionMode} onValueChange={setMotionMode} />
<BrightnessField value={brightness} onValueChange={setBrightness} />
<TextScaleOptionList value={textScale} onValueChange={setTextScale} />
```

`AppearanceOptionList` 提供 `TextScaleOptionList` 使用的通用单选列表。向 `items` 传入 `value`、`label`、可选 `icon` 与 `description`，即可用相同风格实现主题、动态效果、色彩辨识和亮度选择器。组件使用原生 radio，自动支持键盘导航与表单语义。

## 组合主题卡片 {#compose-card}

`ThemeConfigCard` 把基础色和强调色选择组合在一起，但仍由调用方持有配置。

```tsx
<ThemeConfigCard
  config={{ baseColor, accentColor }}
  onConfigChange={setThemeColors}
  scheme={resolvedTheme}
/>
```

需要更细粒度的布局时，可以分别使用 `baseColorSwatches`、`accentColorSwatches` 和 `ThemeColorSwatchButton`。

`ThemeColorPicker` 默认使用带文字的 `pill` 样式；空间紧凑时可切换为仅显示颜色和选中标记的 `swatch` 样式：

```tsx
<ThemeColorPicker
  title="强调色"
  swatches={accentColorSwatches}
  value={accentColor}
  variant="swatch"
  onValueChange={setAccentColor}
/>
```

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

`AppearanceSettings` 是原子组件与共享 `PreferencesProvider` 之间的默认连接层。自定义界面可以使用 Appearance 提供的 `useThemeMode`、`useThemeConfig`、`useResolvedTheme` 等 hooks，而不必知道共享偏好的字符串键，也不必复用默认布局。

```tsx
const [themeConfig, setThemeConfig] = useThemeConfig()
const resolvedTheme = useResolvedTheme()

<ThemeConfigCard
  config={themeConfig}
  onConfigChange={setThemeConfig}
  scheme={resolvedTheme}
/>
```

## 在线预览 {#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} />
```