Maofeng
91 lines
3.7 KiB
Plaintext
91 lines
3.7 KiB
Plaintext
---
|
||
title: 概览
|
||
description: 了解 Appearance 包的原子组件、主题数据和偏好边界。
|
||
order: 1
|
||
toc:
|
||
- id: package-role
|
||
title: 包的职责
|
||
- id: atomic-components
|
||
title: 原子组件
|
||
- id: preferences
|
||
title: 偏好集成
|
||
- id: hooks
|
||
title: Hooks
|
||
---
|
||
|
||
## 包的职责 {#package-role}
|
||
|
||
`@workspace/appearance` 负责主题模式、基础色、强调色、色彩辨识、文字缩放、动态效果和界面亮度。它不创建自己的 Provider 或 store，也不要求修改 `@workspace/ui`；应用通过 `@workspace/preferences` 与其他偏好 package 统一聚合。
|
||
|
||
## 原子组件 {#atomic-components}
|
||
|
||
受控组件可以独立组合，不依赖偏好上下文：
|
||
|
||
- `ThemeModeField` 选择浅色、深色或跟随系统。
|
||
- `ColorVisionModeField` 选择标准、Protan、Deutan 或 Tritan 辅助色板。
|
||
- `TextScaleField` 将界面缩放到 100%、125%、150% 或 200%。
|
||
- `MotionModeField` 跟随系统、减少动态效果或启用完整动效。
|
||
- `BrightnessField` 选择柔暗、标准或明亮的界面表面。
|
||
- `ThemeColorPicker` 与 `ThemeColorSwatchButton` 选择主题颜色。
|
||
- `ThemeConfigCard` 组合基础色与强调色设置。
|
||
- `ThemeToggle` 在浅色和深色主题之间切换。
|
||
|
||
`AppearanceSettings`、`AppearanceDialog` 与 `AppearanceController` 是建立在这些原子组件之上的可选组合层。
|
||
|
||
## 偏好集成 {#preferences}
|
||
|
||
```tsx
|
||
import {
|
||
createDefaultPreferences,
|
||
PreferencesProvider,
|
||
} from "@workspace/preferences"
|
||
import {
|
||
AppearanceController,
|
||
appearancePreferenceDefinitions,
|
||
appearancePreferenceEffect,
|
||
} from "@workspace/appearance"
|
||
|
||
const preferenceDefinitions = {
|
||
...appearancePreferenceDefinitions,
|
||
}
|
||
const initialPreferences = createDefaultPreferences(preferenceDefinitions)
|
||
const preferenceEffects = [appearancePreferenceEffect] as const
|
||
|
||
export function App() {
|
||
return (
|
||
<PreferencesProvider
|
||
effects={preferenceEffects}
|
||
initialPreferences={initialPreferences}
|
||
>
|
||
<AppearanceController />
|
||
</PreferencesProvider>
|
||
)
|
||
}
|
||
```
|
||
|
||
把语言、快捷键等 package 的 definitions 和 effects 添加到相同对象即可。应用可以通过共享的 `onPreferenceChange` 持久化所有 `{ key, value }` 更新，并在服务端使用聚合后的 definitions 解析 Cookie。
|
||
|
||
色彩辨识辅助不会给整个页面或图片添加滤镜。它只替换 `destructive` 与 `chart-*` 等语义颜色，并在 `<html>` 上写入 `data-ui-color-vision`，供业务组件添加图标、文字、形状或纹理。关键信息不能只靠颜色表达。
|
||
|
||
文字、动态效果和亮度同样只通过根节点属性与 CSS 变量实现。导入 Appearance 样式后，现有 UI 组件、Portal 和应用内容都会继承这些设置。
|
||
|
||
## Hooks {#hooks}
|
||
|
||
应用不需要知道 Appearance 在共享 store 中使用的字符串键。Package 为每个偏好提供了语义化 hook：`useThemeMode`、`useAccentColor`、`useBaseColor`、`useColorVisionMode`、`useTextScale`、`useMotionMode` 和 `useBrightness`。
|
||
|
||
组合和解析类 hook 用于更高层的界面：
|
||
|
||
- `useThemeConfig` 将基础色和强调色作为一个配置读写。
|
||
- `useSystemTheme` 与 `useSystemMotion` 只读取操作系统设置。
|
||
- `useResolvedTheme` 与 `useResolvedMotion` 解析 `system` 后返回最终值。
|
||
- `useToggleTheme` 返回在显式浅色与深色之间切换的回调。
|
||
- `useAppearancePreference` 提供类型安全的底层入口，`useAppearancePreferences` 返回 Appearance 所有偏好的快照。
|
||
|
||
```tsx
|
||
const [themeMode, setThemeMode] = useThemeMode()
|
||
const [themeConfig, setThemeConfig] = useThemeConfig()
|
||
const resolvedTheme = useResolvedTheme()
|
||
const resolvedMotion = useResolvedMotion()
|
||
const toggleTheme = useToggleTheme()
|
||
```
|