Material Components for iOS 组件文档编写规范指南
项目地址: https://gitcode.com/gh_mirrors/ma/material-components-ios 概述
Material Components for iOS（MDC-iOS）是Google开发的Material Design风格iOS原生组件库。虽然项目已于2021年7月15日进入维护模式，但其完善的文档编写规范仍值得学习和借鉴。本文将详细介绍MDC-iOS的组件文档编写规范，帮助开发者创建专业、一致的组件文档。
文档结构规范
组件目录结构
每个组件都应遵循统一的目录结构：
components/
ComponentName/
.vars # 模板变量定义文件
README.md # 自动生成的主文档（勿直接修改）
docs/ # 文档源文件目录
README.md # 组件文档根索引
article.md # 相关技术文章
assets/ # 图片、GIF等资源文件
src/ # 源代码
tests/ # 测试代码
examples/ # 使用示例
核心文档文件要求
每个组件必须提供完整的API文档和顶层README.md文件，包含以下内容：
- 组件描述：与Material Design规范的关联说明
- 动态演示：循环播放的组件动画GIF
- 设计链接：指向相关设计文档的链接
- API文档：完整的API参考文档
- 相关组件：相关联的其他组件列表
- API概述：主要API的功能描述
- 安装指南：详细的安装步骤
- 使用指南：至少包含一个典型使用场景
文档内容编写规范
README.md模板结构
# 组件名称
单句组件描述。
## 设计与API文档
<ul class="icon-list">
<li class="icon-list-item icon-list-item--spec">
<a href="https://material.io/guidelines/组件规范链接">
组件规范文档
</a>
</li>
<li class="icon-list-item icon-list-item--link">
<a href="/components/组件名称/apidocs/Classes/API类名.html">
API文档
</a>
</li>
</ul>
<!--{: .article__asset.article__asset--screenshot }-->
---
## 安装
### CocoaPods安装
在Podfile中添加：
```ruby
pod 'MaterialComponents/组件名称'
然后运行：
pod install
概述
可选章节。提供组件的高级概述，包括：
- 与相关UIKit API的比较
- 组件整体结构说明
使用
必需章节。提供基本的集成步骤。
附加信息章节
推荐章节。用于讨论边缘情况行为。
### 代码片段规范
每个代码片段必须同时提供Objective-C和Swift版本：
```markdown
<!--<div class="material-code-render" markdown="1">-->
#### Objective-C
```objc
- (void)viewDidLoad {
[super viewDidLoad];
// 组件使用代码
}
Swift
override func viewDidLoad() {
super.viewDidLoad()
// 组件使用代码
}
## 模板变量系统
### .vars文件配置
`.vars`文件定义组件模板变量，格式为`变量名=值`：
```bash
component=Button
component_name=MDCButton
a_component_name=an MDCButton
root_path=components/Button
icon_id=ic_button
short_description=A Material Design button
color_themer_api=MDCButtonColorThemer
typography_themer_api=MDCButtonTypographyThemer
themer_parameter_name=button
guidelines_short_link=components-buttons
guidelines_title=Buttons
可用模板标签
| 标签 | 功能 | 示例 |
|---|---|---|
<!-- badges --> | 生成徽章 | 版本号、构建状态等 |
<!-- design-and-api --> | 生成设计和API链接 | 需要jazzy支持 |
- [文章标题](article-file.md) | 嵌入文章 | 链接到详细技术文章 |
<!-- toc --> | 生成目录 | 自动生成内容目录 |
文档生成流程
自动生成命令
# 应用模板到组件
./scripts/apply_template ComponentName scripts/templates/component/docs/README.md.template components/ComponentName/docs/README.md
# 生成组件README.md
./scripts/generate_readme ComponentName
文档质量检查清单
- ✅ 包含所有公共API的完整文档
- ✅ 提供组件与Material规范的关联说明
- ✅ 包含动态GIF演示
- ✅ 提供设计和API文档链接
- ✅ 列出相关组件
- ✅ 包含主要API概述
- ✅ 提供详细的安装指南
- ✅ 包含至少一个典型使用示例
- ✅ 同时提供Objective-C和Swift代码示例
- ✅ 资源文件存放在正确位置
最佳实践建议
内容组织策略
多语言支持规范
| 内容类型 | Objective-C规范 | Swift规范 | 注意事项 |
|---|---|---|---|
| 类名 | MDC前缀+组件名 | 去掉MDC前缀 | 保持命名一致性 |
| 方法名 | 小驼峰命名法 | 小驼峰命名法 | 参数命名一致 |
| 代码风格 | Square括号语法 | 点语法 | 体现语言特性 |
| 错误处理 | NSError**参数 | throws关键字 | 符合语言习惯 |
版本兼容性说明
在文档中明确说明组件支持的iOS版本和依赖要求：
## 兼容性要求
- **最低iOS版本**: iOS 9.0+
- **Swift版本**: 4.2+
- **依赖组件**: MaterialComponents/Core
- **编译器要求**: Xcode 10.0+
维护与更新策略
虽然MDC-iOS已进入维护模式，但文档编写规范仍具有参考价值。维护模式下的支持策略：
- 版本发布: 按需和尽力而为的基础上进行
- 功能请求: 自动关闭
- Bug修复: 尽力而为的基础上处理
- 文档维护: 不再维护GitHub上的.md文档
- 贡献接受: 可能仍被接受，但不保证合并
总结
Material Components for iOS的文档编写规范体现了Google对技术文档的高标准要求。通过统一的模板系统、严格的内容规范和自动化工具链，确保了组件文档的一致性、完整性和可维护性。这些最佳实践值得所有iOS组件库开发者学习和借鉴，即使项目进入维护模式，其文档规范仍然具有重要的参考价值。
遵循这些规范，你可以创建出专业、易用、一致的组件文档，为用户提供最佳的使用体验。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
