最佳实践

本页汇总 YH-UI 在真实业务项目中的推荐使用方式。它不是 API 列表，而是团队协作和长期维护的约定。

组件使用

• 优先使用组件公开 API，不直接依赖内部 DOM 结构。
• 业务差异优先通过 props、事件、插槽、themeOverrides 处理。
• 多页面复用的组合应沉淀为业务组件，不在每个页面复制模板。
• 避免把全局状态写进基础组件，让组件保持可复用和可测试。

表单

• 表单字段应有明确标签、校验规则和错误信息。
• 长表单按业务语义分组，避免一次性展示所有字段。
• 提交按钮在异步提交期间进入 loading 或 disabled 状态。
• 后端错误应映射到字段或页面级反馈，不只打印到控制台。

弹层与反馈

• Message 用于轻量即时反馈，不承载复杂操作。
• Notification 用于系统级、可延迟阅读的信息。
• Dialog 用于需要用户决策的任务，不要堆叠多层弹窗。
• 删除、覆盖、发布等高风险操作需要确认或撤销机制。

主题与样式

• 主题差异通过 Token 管理，避免全局 class 覆盖组件内部样式。
• 页面级样式只负责布局，不重写组件行为状态。
• 暗色模式、移动端和高对比场景应作为主题变更的必测项。

性能

• 大列表使用分页、虚拟滚动或懒加载。
• 表格列渲染函数保持纯净，避免在每个单元格创建重型对象。
• 图标、图表、编辑器等重资源按需加载。
• 文档 Demo 和 playground 需要定期跑构建和 smoke。

SSR 与 Nuxt

• SSR 页面避免在组件初始化阶段直接访问 window、document、localStorage。
• 与浏览器 API 相关的逻辑放到 onMounted 或客户端插件中。
• Nuxt 项目优先使用官方模块和自动导入能力。

测试

• 基础组件覆盖默认态、边界态、事件、插槽、可访问性和 SSR。
• 业务组件覆盖用户路径，而不是只断言 DOM 片段。
• 文档 Demo 应通过 playground 或 sandbox 验证，防止示例失效。
• 发布前至少运行类型检查、lint、单测、构建和 consumer smoke。

开源协作

• Issue 必须包含复现、期望行为、实际行为和环境信息。
• PR 应聚焦一个问题，避免把格式化、重构、功能变更混在一起。
• Breaking change 必须写迁移说明，并进入版本策略评审。