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

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

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

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

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

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

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

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

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

`AppearanceSettings` 是原子组件与共享 `PreferencesProvider` 之间的默认连接层。自定义界面可以直接使用 `@workspace/preferences` 的 `usePreference` 读取单个字段，而不必复用默认布局。

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