Maofeng
87 lines
3.1 KiB
Plaintext
87 lines
3.1 KiB
Plaintext
---
|
|
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} />
|
|
```
|