技术债与遗留问题 (Technical Debt & Legacy Issues)
本文件用于记录 NextUI 开发过程中为了快速交付或绕过环境限制而引入的硬编码、临时方案及待优化项。
编译警告屏蔽记录
注意：根据
.cursorrules中的"编译警告处理规范"，只有在以下情况下才允许屏蔽警告：
- 第三方库或框架的已知问题，无法通过修改代码解决
- 架构设计需要，且已获得用户明确批准
- 临时性技术债务，且已在文档中说明解决计划和时间表
每个屏蔽的警告必须记录以下信息：
- 警告的完整信息（警告代码和消息）
- 屏蔽的位置（文件路径和行号）
- 屏蔽的原因（为什么必须屏蔽）
- 计划解决的时间或版本（如适用）
- 批准人（如适用）
警告屏蔽记录模板
### [警告代码] 警告消息 (YYYY-MM-DD)
- **警告信息**：`[警告代码]` - [完整警告消息]
- **屏蔽位置**：`[文件路径]:[行号]`
- **屏蔽原因**：[详细说明为什么必须屏蔽，不能通过修改代码解决]
- **屏蔽方式**：`#pragma warning disable [警告代码]` / `[SuppressMessage(...)]`
- **计划解决**：[解决计划或版本，如"v1.2.0"或"待第三方库更新"]
- **批准人**：[批准人，如适用]
- **相关链接**：[相关 Issue 或文档链接，如适用]
其他技术债
Workbench 演示系统
1. ComponentPlayground 标题栏高度对齐 (2026-01-11)
- 问题：左侧预览栏（Blazor/HTML）与右侧属性栏（属性/配置/状态）的标题头高度无法通过纯逻辑布局（Flex/Padding）在所有情况下保持像素级对齐。
- 临时方案：在
ComponentPlayground.razor中硬编码了height: 3.5rem !important。 - 优化方向：应定义统一的
PlaygroundHeader容器组件，或通过DesignTokens中的标尺变量进行逻辑对齐。
核心组件库
1. SxNavBar 布局的双重刷新 (2026-01-11)
- 问题：浏览器在 DOM 更新后（如修改长标题文本）计算
scrollWidth存在异步延迟，导致 JS 立即测量时拿到的数据不准确，产生文字图标重叠。 - 现状：采用了
Dual-Pass刷新机制，即立即测量一次，150ms 后再次补测。 - 优化方向：探索是否能通过
requestIdleCallback或更精细的排版监听来消除这 150ms 的硬等待感。
2. SxNavBar 的 CSS 强制覆盖 (2026-01-11)
- 问题：为了保证几何对冲居中不受内部元素干扰，使用了较多的
!important锁死 Grid 列宽。 - 优化方向：重构 CSS 优先级，减少对
!important的依赖。