代码质量改进方案与计划

创建日期: 2026-01-13
状态: 📋 待实施

一、目标

消除硬编码：让所有设计（组件、布局等）原生支持已实现的主题相关功能：
- ✅ 主题色（Primary Color）
- ✅ 布局密度（Layout Density）
- ✅ 字体缩放（Font Scale）
- ✅ 主题模式（Light/Dark）
- ✅ 语言支持（i18n）
修复质量问题：
- 可能的 Bug
- 编译警告（可能预示 Bug）
- 代码规范问题

二、问题分析

2.1 硬编码问题统计

颜色硬编码（约 30+ 处）

严重程度: 🔴 高

问题位置:

组件 CSS 文件（约 20+ 处）:
- SxButton.razor.css: #ffffff (3处)
- SxTag.razor.css: #ffffff, #dff6dd, #107c10, #fde7e9, #d13438, #fff4ce, #9d5d00, #ffb900
- SxBadge.razor.css: #ffffff, #107c10, #ffb900, #d13438
- SxCodeSnippet.razor.css: #1e1e1e, #d4d4d4, #252526, #333, #858585, #fff
- SxMarkdownViewer.razor.css: #1e1e1e, #d4d4d4
- SxTabs.razor.css: #ffffff
- SxSwitch.razor.css: #ffffff (2处)
- SxBrowser.razor.css: #ffffff
- SxComponentDetail.razor.css: #1e1e1e
- SxCheckbox.razor.css: #ffffff
- SxRating.razor.css: #ffb400

影响:

❌ 不支持主题色切换
❌ 不支持暗色模式
❌ 无法响应主题变化

间距硬编码（约 30+ 处）

严重程度: 🟡 中

问题位置:

像素值硬编码:
- SxAppShell.razor.css: 4px, -2px (滚动条、分隔线)
- SxNavBar.razor.css: 4px (间距)
- SxTabs.razor.css: 2px (指示器)
- 其他组件中的 1px, 2px 边框

影响:

❌ 不支持布局密度调整
❌ 无法响应密度变化

字体大小硬编码（约 20+ 处）

严重程度: 🟡 中

问题位置:

固定 rem/em 值:
- SxTypography.razor.css: 所有字体大小都是固定值（1.75rem, 1.5rem, 1.25rem 等）
- SxNavBar.razor.css: 1rem, 0.9rem
- SxMenuItem.razor.css: 1rem, 0.75rem
- SxButton.razor.css: 1.1rem, 1.2rem, 1.5rem (图标)
- SxMarkdownViewer.razor.css: 2rem, 1.5rem, 1.25rem, 1.1rem, 0.9em, 0.875rem
- SxTabs.razor.css: 1rem
- SxPropertyInspector.razor.css: 0.7rem (2处)
- SxCodeSnippet.razor.css: 0.85rem, 0.7rem
- SxInput.razor.css: 0.7rem
- SxImage.razor.css: 2rem

影响:

❌ 不支持字体缩放
❌ 无法响应字体缩放变化

rgba/box-shadow 硬编码（约 15+ 处）

严重程度: 🟡 中

问题位置:

SxMenu.razor.css: rgba(0,0,0,0.15)
SxDialog.razor.css: rgba(0,0,0,0.4), rgba(0,0,0,0.25)
SxCard.razor.css: rgba(0, 0, 0, 0.05), rgba(0, 0, 0, 0.12)
SxDrawer.razor.css: rgba(0,0,0,0.4), rgba(0,0,0,0.2)
其他组件的阴影效果

影响:

❌ 暗色模式下阴影可能不协调
❌ 无法根据主题模式调整

2.2 编译警告检查

状态: ⏳ 待检查

需要运行完整构建来检查：

dotnet build --verbosity normal 2>&1 | grep -i "warning\|error"

2.3 代码质量问题

状态: ⏳ 待深入分析

三、改进方案

3.1 颜色硬编码消除方案

策略 1: 使用语义化 CSS 变量

原则:

所有颜色必须使用 CSS 变量
变量名应反映语义（如 --sx-colorNeutralForeground1），而非具体颜色值
支持主题色、暗色模式自动切换

实施步骤:

扩展设计变量（sx-tokens.css）:

/* 状态颜色（Success, Warning, Danger）*/
--sx-colorStatusSuccess: #107c10;
--sx-colorStatusSuccessBackground: #dff6dd;
--sx-colorStatusWarning: #ffb900;
--sx-colorStatusWarningBackground: #fff4ce;
--sx-colorStatusDanger: #d13438;
--sx-colorStatusDangerBackground: #fde7e9;

/* 代码编辑器颜色（支持暗色模式）*/
--sx-colorCodeBackground: var(--sx-colorNeutralBackground1);
--sx-colorCodeForeground: var(--sx-colorNeutralForeground1);
--sx-colorCodeHeaderBackground: var(--sx-colorNeutralBackground2);
--sx-colorCodeBorder: var(--sx-colorNeutralStroke1);
--sx-colorCodeTextSecondary: var(--sx-colorNeutralForeground3);

/* 白色/黑色（语义化）*/
--sx-colorOnBrand: #ffffff;  /* 品牌色上的文字 */
--sx-colorOnStatus: #ffffff;  /* 状态色上的文字 */

暗色模式支持:

[data-theme="dark"] {
    --sx-colorCodeBackground: #1e1e1e;
    --sx-colorCodeForeground: #d4d4d4;
    --sx-colorCodeHeaderBackground: #252526;
    --sx-colorCodeBorder: #333;
    --sx-colorCodeTextSecondary: #858585;
}

组件替换:
- SxButton: #ffffff → var(--sx-colorOnBrand)
- SxTag: 所有硬编码颜色 → 对应的状态颜色变量
- SxBadge: 同上
- SxCodeSnippet: 所有硬编码颜色 → 代码编辑器颜色变量
- 其他组件类似处理

策略 2: 主题色集成

原则:

品牌相关颜色应使用主题色变量
支持动态主题色切换

实施:

SxTag--brand: 已使用 var(--sx-colorBrandBackground1) ✅
SxBadge--primary: 已使用 var(--sx-colorBrandBackground1) ✅
其他品牌相关颜色检查并替换

3.2 间距硬编码消除方案

策略: 使用密度感知的间距变量

原则:

所有间距必须使用 --sx-spacing-* 变量
支持布局密度自动调整

实施步骤:

小间距（1-4px）处理:

/* 在 sx-tokens.css 中添加 */
--sx-spacing-micro: calc(0.0625rem * var(--sx-density-scale, 1)); /* 1px */
--sx-spacing-tiny: calc(0.125rem * var(--sx-density-scale, 1)); /* 2px */
--sx-spacing-mini: calc(0.25rem * var(--sx-density-scale, 1));  /* 4px */

组件替换:
- 4px → var(--sx-spacing-mini)
- 2px → var(--sx-spacing-tiny)
- 1px → var(--sx-spacing-micro) 或保持（边框通常不受密度影响）
边框处理:
- 边框宽度（1px, 2px）通常不受密度影响，但应使用变量以便统一管理
- 添加 --sx-border-width-thin: 1px, --sx-border-width-medium: 2px

3.3 字体大小硬编码消除方案

策略: 使用字体缩放变量

原则:

所有字体大小必须使用 --sx-font-size-* 变量
支持字体缩放自动调整

实施步骤:

扩展字体大小变量（sx-tokens.css）:

/* 已有变量 */
--sx-font-size-xs: calc(0.75rem * var(--sx-font-scale, 1));
--sx-font-size-sm: calc(0.875rem * var(--sx-font-scale, 1));
--sx-font-size-base: calc(1rem * var(--sx-font-scale, 1));
--sx-font-size-lg: calc(1.125rem * var(--sx-font-scale, 1));
--sx-font-size-xl: calc(1.5rem * var(--sx-font-scale, 1));

/* 需要添加的变量 */
--sx-font-size-xxl: calc(1.75rem * var(--sx-font-scale, 1)); /* H1 */
--sx-font-size-xxxl: calc(2rem * var(--sx-font-scale, 1));   /* 超大标题 */
--sx-font-size-micro: calc(0.7rem * var(--sx-font-scale, 1)); /* 极小文字 */
--sx-font-size-tiny: calc(0.85rem * var(--sx-font-scale, 1)); /* 很小文字 */

组件替换:
- SxTypography: 所有固定值 → 对应的字体大小变量
- SxNavBar: 1rem → var(--sx-font-size-base), 0.9rem → var(--sx-font-size-sm)
- SxButton: 图标大小 → 使用相对单位或变量
- 其他组件类似处理

图标大小处理:

/* 在 sx-tokens.css 中已有 */
--sx-icon-size-sm: 0.875rem;
--sx-icon-size-md: 1rem;
--sx-icon-size-lg: 1.25rem;

/* 需要支持字体缩放 */
--sx-icon-size-sm: calc(0.875rem * var(--sx-font-scale, 1));
--sx-icon-size-md: calc(1rem * var(--sx-font-scale, 1));
--sx-icon-size-lg: calc(1.25rem * var(--sx-font-scale, 1));

3.4 阴影/透明度硬编码消除方案

策略: 使用主题感知的阴影变量

原则:

阴影应支持暗色模式
使用语义化变量

实施步骤:

添加阴影变量（sx-tokens.css）:

/* 阴影（支持暗色模式）*/
--sx-shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.1);
--sx-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.1);
--sx-shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.12);
--sx-shadow-xl: 0 12px 32px rgba(0, 0, 0, 0.25);
--sx-shadow-overlay: 0 8px 24px rgba(0, 0, 0, 0.15);

/* 遮罩（支持暗色模式）*/
--sx-overlay-backdrop: rgba(0, 0, 0, 0.4);

[data-theme="dark"] {
    --sx-shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.3);
    --sx-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.3);
    --sx-shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.4);
    --sx-shadow-xl: 0 12px 32px rgba(0, 0, 0, 0.5);
    --sx-shadow-overlay: 0 8px 24px rgba(0, 0, 0, 0.5);
    --sx-overlay-backdrop: rgba(0, 0, 0, 0.6);
}

组件替换:
- 所有 box-shadow 硬编码 → 对应的阴影变量
- 所有 rgba(0,0,0,...) 遮罩 → var(--sx-overlay-backdrop)

3.5 编译警告处理方案

策略: 系统化处理

原则:

根据 .cursorrules 中的"编译警告处理规范"
优先修复，必要时记录并屏蔽

实施步骤:

收集警告:

dotnet build --verbosity normal 2>&1 | tee build-warnings.log

分类处理:
- 可修复: 立即修复
- 第三方库问题: 记录到 docs/KNOWN_ISSUES.md
- 架构设计需要: 记录到 docs/TECHNICAL_DEBT.md，获得批准后屏蔽
验证:
- 修复后重新构建，确保警告消除
- 运行测试，确保功能正常

四、实施计划

阶段 1: 设计变量扩展（1-2 天）

目标: 在 sx-tokens.css 中添加所有缺失的设计变量

任务:

✅ 添加状态颜色变量（Success, Warning, Danger）
✅ 添加代码编辑器颜色变量（支持暗色模式）
✅ 添加微间距变量（micro, tiny, mini）
✅ 添加扩展字体大小变量（xxl, xxxl, micro, tiny）
✅ 添加图标大小变量（支持字体缩放）
✅ 添加阴影变量（支持暗色模式）
✅ 添加遮罩变量
✅ 添加边框宽度变量

验收标准:

所有新变量在 sx-tokens.css 中定义
暗色模式支持完整
变量命名符合规范

阶段 2: 组件硬编码消除（3-5 天）

目标: 逐个组件替换硬编码值

优先级:

高优先级（影响主题色/暗色模式）:
- SxButton.razor.css
- SxTag.razor.css
- SxBadge.razor.css
- SxCodeSnippet.razor.css
- SxMarkdownViewer.razor.css
中优先级（影响字体缩放）:
- SxTypography.razor.css
- SxNavBar.razor.css
- SxButton.razor.css (图标大小)
- SxMarkdownViewer.razor.css
低优先级（影响布局密度）:
- SxAppShell.razor.css
- SxNavBar.razor.css
- 其他组件的小间距

任务清单（按组件）:

验收标准:

每个组件替换后，在 Workbench 中测试：
- ✅ 主题色切换正常
- ✅ 暗色模式正常
- ✅ 字体缩放正常
- ✅ 布局密度正常
无视觉回归

阶段 3: 编译警告处理（1 天）

目标: 修复或记录所有编译警告

任务:

运行完整构建，收集所有警告
分类处理（修复/记录）
更新文档（如需要）

验收标准:

所有可修复的警告已修复
所有不可修复的警告已记录
构建无警告（或已记录）

阶段 4: 测试与验证（1-2 天）

目标: 确保所有改进不影响现有功能

任务:

运行所有单元测试
在 Workbench 中手动测试所有组件
测试主题切换、密度调整、字体缩放
视觉回归测试

验收标准:

✅ 所有测试通过
✅ 所有功能正常
✅ 无视觉回归

阶段 5: 文档更新（0.5 天）

目标: 更新相关文档

任务:

更新 docs/DesignTokens.md（新增变量）
更新组件文档（如需要）
更新 docs/TECHNICAL_DEBT.md（记录已解决的问题）

五、风险评估

5.1 高风险项

视觉回归风险
- 缓解: 每个组件替换后进行视觉对比
- 验证: 在 Workbench 中测试
性能影响
- 风险: CSS 变量可能略微影响性能
- 评估: 影响可忽略不计

5.2 中风险项

变量命名冲突
- 缓解: 遵循现有命名规范
- 验证: 检查所有变量名唯一性
暗色模式适配
- 缓解: 系统化测试暗色模式
- 验证: 所有组件在暗色模式下正常

六、成功标准

✅ 零硬编码: 所有颜色、间距、字体大小使用 CSS 变量
✅ 主题支持: 所有组件支持主题色、暗色模式、字体缩放、布局密度
✅ 零警告: 所有编译警告已处理（修复或记录）
✅ 测试通过: 所有测试通过，无功能回归
✅ 文档完整: 所有新变量已文档化

七、时间估算

阶段 1: 1-2 天
阶段 2: 3-5 天（63 个组件，平均每个 0.05-0.08 天）
阶段 3: 1 天
阶段 4: 1-2 天
阶段 5: 0.5 天

总计: 约 6.5-10.5 天（1.5-2 周）

八、下一步

确认方案: 请确认此方案是否符合预期
开始实施: 从阶段 1 开始
持续沟通: 每个阶段完成后汇报进度

请确认是否同意此方案，或提出需要调整的地方。