Material Components for iOS 组件文档编写规范指南

Material Components for iOS 组件文档编写规范指南

material-components-ios material-components/material-components-ios: Material Components for iOS (MDC-iOS) 同样由Google开发，为iOS平台提供了实现Material Design风格的原生组件库，包含多种符合Material Design规范的界面元素。 项目地址: https://gitcode.com/gh_mirrors/ma/material-components-ios

文档体系概述

Material Components for iOS 项目采用了一套标准化的组件文档体系，确保每个组件都能提供完整且一致的开发文档。这套体系不仅规范了文档内容结构，还提供了自动化生成工具，大大提高了文档编写效率。

核心文档要求

每个组件必须包含以下完整的文档内容：

1. 组件说明：清晰描述该组件如何实现 Material Design 规范
2. 动态演示：以GIF动画形式展示组件的实际效果
3. 设计规范：指向相关设计指南的链接
4. API文档：完整的API参考文档
5. 关联组件：列出功能相关的其他组件
6. API概览：核心API的简要说明
7. 安装指南：详细的组件集成步骤
8. 使用教程：至少包含一个典型使用场景的示例
9. 扩展功能：如有额外功能模块，需单独说明

文档目录结构

项目采用标准化的目录结构组织组件文档：

组件目录/
  .vars         <- 模板变量定义文件
  README.md     <- 自动生成的主文档（勿直接编辑）
  docs/         <- 文档源文件目录
    README.md   <- 组件文档入口文件
    article.md  <- 相关技术文章
    assets/     <- 图片/GIF资源存放处

文档模板系统

项目提供了强大的模板系统来简化文档编写：

1. 初始化模板：使用命令行工具创建基础文档结构

   ./scripts/apply_template 组件名 模板路径 输出路径
   

2. 变量定义文件(.vars)：包含组件元数据的键值对配置，支持以下变量：

   • 组件标识符(component)
   • 组件名称(component_name)
   • 简短描述(short_description)
   • 主题化API(color_themer_api/typography_themer_api)
   • 设计指南链接(guidelines_short_link)

3. 自动化插入标记：文档中可使用特殊注释标记自动插入内容：

   • <!-- badges -->：自动生成组件状态徽章
   • <!-- design-and-api -->：插入设计与API文档链接
   • <!-- toc -->：生成目录结构

文档生成流程

1. 准备阶段：

   • 创建.vars文件定义组件元数据
   • 准备演示素材（GIF/PNG）

2. 编写阶段：

   • 使用模板初始化文档结构
   • 编写核心文档内容
   • 添加使用示例和教程

3. 生成阶段：

   ./scripts/generate_readme 组件名
   

   该命令会自动整合所有文档资源，生成最终的README文件。

最佳实践建议

1. 保持一致性：所有组件文档遵循相同结构和风格
2. 图文并茂：关键功能需配合视觉演示
3. 示例驱动：每个主要API都应提供使用示例
4. 渐进式披露：从简单用例开始，逐步展示高级功能
5. 版本标注：明确标注API的兼容性要求

通过这套文档体系，开发者可以快速了解组件的功能特性，掌握使用方法，并在项目中高效集成Material Design组件。

material-components-ios material-components/material-components-ios: Material Components for iOS (MDC-iOS) 同样由Google开发，为iOS平台提供了实现Material Design风格的原生组件库，包含多种符合Material Design规范的界面元素。 项目地址: https://gitcode.com/gh_mirrors/ma/material-components-ios