# XCoder macOS 全局浅色主题与控件交互规范 修复版本：0.2.2；2026-10-18。 ## 问题与根因 XCoder 主界面和工具面板明确使用固定浅色背景，但 Avalonia FluentTheme 原来跟随 macOS 系统外观。系统为深色模式时，ComboBox、TextBox、ListBoxItem 及按钮内层模板可能继承暗色背景、白色文字，出现未选中列表不可见、下拉框灰黑底、鼠标悬停文字不清晰等问题。 ## 全局处理 - 在 `MacApp.axaml` 显式设置 `RequestedThemeVariant="Light"`，避免同一窗口混合深色控件与浅色页面。 - 在 `XCoderMac/Styles/LightControls.axaml` 集中定义浅色控件规范，应用级使用 `StyleInclude` 引入。 - 所有窗口（主窗口、工具标签内容、独立连接管理窗口、确认弹窗）默认共享这套主题；不用给每个业务窗口重复贴样式。 - 覆盖 Button、TextBox、ComboBox、ComboBoxItem、ListBoxItem、TabItem、MenuItem 以及 TextBlock，明确配置普通、pointerover、selected、pressed、disabled 等状态。 - 业务动作按照语义使用 `Button.primary`、`Button.secondary`、`Button.danger`： - primary：蓝底白字，悬停深蓝底白字； - secondary：浅蓝底深蓝字，悬停仍保持对比度； - danger：淡红底深红字，悬停深红文字。 - 独立连接管理窗口的「保存连接」「测试连接」「删除」等已使用语义类别；原业务命令、绑定及数据库配置规则均未改动。 ## 回归验证 从当前工程目录运行： ```bash dotnet build XCoderMac/XCoderMac.csproj -c Debug --no-restore dotnet run --project XCoderMac/XCoderMac.csproj -c Debug --no-build -- --smoke-connection-ui dotnet run --project XCoderMac/XCoderMac.csproj -c Debug --no-build -- --smoke-modeling-layout dotnet run --project XCoderMac/XCoderMac.csproj -c Debug --no-build -- --smoke-tabs dotnet run --project XCoderMac/XCoderMac.csproj -c Debug --no-build -- --smoke-home-layout ``` 连接窗口的 `--smoke-connection-ui` 会自动检查： 1. 全局实际主题为 Light。 2. ComboBox 和 TextBox 背景为浅色，文字为深色。 3. ListBoxItem 未选中和选中项都具有深色文字，选中项背景为浅蓝。 4. **真实模拟 pointerover 伪类**，验证两个下拉框、未选中和已选中列表项、测试连接按钮仍是浅底深字。 5. 验证「保存连接」悬停仍是蓝底白字，「删除」仍是淡红底深色文字。 6. 同时回归连接字符串双向解析，并更新 `Docs/软件界面/` 的截图。 本规范目前明确固定浅色主题。后续如果需要随 macOS 切换深色模式，应为全部工具页面设计完整的暗色变量主题，**不能单独移除 Light 设置**，否则旧问题会重现。