文档约定
统一的文档规范，确保长期可维护性
建议章节
📖
1. 组件介绍
说明组件的功能、适用场景和核心价值
🎯
2. 基础用法
最简单的使用示例，让用户快速上手
💡
3. 典型场景
实际业务中的常见使用场景和最佳实践
🔧
4. API
完整的 API 文档，包含 Props、Methods 等
⚡
5. 事件
组件支持的事件列表和回调函数
🎨
6. 插槽
组件提供的插槽和自定义内容
⚠️
7. 注意事项
使用限制、平台差异和常见问题
命名约定
📁 文件命名
- 文档页面路径与组件目录名一致，如
t-button对应components/t-button.md - 页面标题优先使用组件名，副标题补充中文语义
- 示例路径尽量引用
demo目录中的真实页面
🔑 Key 命名
- 国际化 key使用"页面/模块 + 语义"的形式，例如
index.title、button.submit - 组件库 key添加前缀避免冲突，例如
tui.button.confirm、tui.popup.cancel - 主题变量使用语义化命名，例如
primaryNormal、textPrimary、radiusLarge
维护原则
✅ 内容质量
- 问题导向：优先写清楚组件解决什么问题，而不是单纯罗列功能
- 场景覆盖：示例尽量覆盖最常见场景，避免过于理论化
- API 精准：描述保持短句、明确默认值和平台差异
- 代码可运行：所有示例代码都应该可以直接运行，避免伪代码
🎨 视觉呈现
- 统一格式：使用一致的代码块格式、表格样式和标题层级
- 添加注释：为复杂示例添加详细注释，说明关键步骤
- 截图展示：重要组件添加截图或 GIF，展示实际效果
- 响应式说明：说明组件在不同屏幕尺寸下的表现
📝 文档结构
- 逻辑清晰：按照从简到繁的顺序组织内容
- 交叉引用：在相关章节间建立链接，方便用户跳转
- 版本标注：明确标注功能适用的版本号
- 更新记录：在文档末尾添加最近更新记录
文档模板
📋 推荐文档结构
markdown
# 组件名称
组件简介，说明功能和适用场景
## 基础用法
最简单的使用示例
## 典型场景
实际业务中的常见使用场景
## API
完整的 API 文档表格
| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| prop1 | 参数说明 | String | '' |
## 事件
组件支持的事件列表
| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| change | 值变化时触发 | (value: any) |
## 插槽
组件提供的插槽
| 插槽名 | 说明 |
|--------|------|
| default | 默认插槽 |
## 注意事项
使用限制、平台差异和常见问题质量检查清单
✅ 发布前检查
内容完整性
- 组件介绍清晰完整
- 示例代码可运行
- API 文档准确无误
- 注意事项充分说明
视觉呈现
- 代码格式统一规范
- 添加必要的截图展示
- 表格样式清晰美观
- 标题层级合理清晰
用户体验
- 从简到繁组织内容
- 添加相关文档链接
- 提供搜索关键词
- 标注适用版本信息
📚 遵循这些约定，让文档更加专业、易读、易维护！