主题与状态

主题和状态决定组件在不同交互场景下的视觉表现。DirectSurface UI 通过语义主题和组件内部样式配方保持整体视觉一致。

更具体的业务页面视觉与交互规则见 组件设计系统。其中 Design Tokens 标准、颜色使用模式、组件状态标准和组件交互模式用于统一业务页面的主题、密度和反馈行为。

ThemeDefinition 与 ResolvedTheme

主题作者使用可局部覆盖的 ThemeDefinition 描述品牌、密度和业务视觉，通过 compileTheme() 或 createTheme() 编译为完整、深冻结的 ResolvedTheme。runtime 和组件只消费 ResolvedTheme，不会在绘制期间补默认值。

常见主题内容：

• Canvas、内容、面板、数据和浮层 surface。
• 文本色。
• 强调色。
• 边框色。
• 焦点框。
• hover / pressed 覆盖色和 selected / disabled 状态色。
• 字体的 size、lineHeight 和 weight。
• 动效、高程、编辑器、图表和语法层。

ThemeData 和 ThemeOverrides 已删除；旧代码分别迁移到 ResolvedTheme 和 ThemeDefinition。完整契约和示例见 Theme API 参考。

组件状态

常见状态包括：

• normal。
• hovered。
• pressed。
• focused。
• selected。
• disabled。
• readonly。
• loading。
• error / warning / success。

组件应清晰区分这些状态，尤其是 hover、selected、focused 和 disabled，避免用户无法判断当前控件是否可操作。

组件公开状态的业务契约见 组件基础状态契约。其中 visible 用于是否参与渲染树，disabled 用于整体不可交互，readonly 用于值可看但不可改。

状态颜色原则

• hover 颜色必须和背景有足够对比度。
• selected 状态必须比 hover 更明确。
• disabled 状态应弱化，但仍可读。
• placeholder 颜色必须明显弱于真实值。
• 深色背景下 hover 应更亮，浅色背景下 hover 应更深。

统一交互行为

通用状态行为应沉到组件层，而不是每个页面重复处理。组件内部样式配方负责把 ResolvedTheme 和 hovered、pressed、selected、focused 等组合状态转换为绘制值；这些配方不是业务代码的公共依赖。

例如：

• TreeView 文本省略时 tooltip 展示完整文本。
• Dropdown 候选项 hover 颜色和分割线风格统一。
• GridView、TreeView、ScrollViewer 滚动条风格一致。
• IconButton hover 时显示 tooltip。

自定义样式边界

页面可以组合组件，但不应该复制组件内部状态绘制逻辑。若多个页面都需要相同行为，应提取到组件公开参数或语义主题。

业务个性化可以通过：

• 组件参数。
• ThemeDefinition。
• row / cell style resolver。
• 命令状态。

性能原则

主题变化会影响大量组件绘制。切换主题时可以触发整树刷新，但普通 hover、focus、selected 不应重算整页布局。