编写 package 页面
本页上的指南可以帮助您在 pub.dev 上创建优秀的 package 页面。具体来说，本页提供了编写更好的 package README 的技巧，README 提供了以下截图中标记为 README (本文档) 的内容。
有关 package 页面其他部分的详细信息，请点击以下链接
编写一个好的 README 很重要
#在 pub.dev 上找到您的 package 的用户很可能会快速扫描 README，以决定是否尝试您的 package。好的 README 能吸引读者的注意力，并表明您的 package 值得尝试。
虽然本页以 in_app_purchase package 的 README 为特色，但您的 README 可能不需要那么大或那么详细。如果您的 package 很简单且没有关联的 UI，其 README 可能更像 yaml package 的 README。
编写优秀 README 的七个技巧
#以下是一些关于创建在 pub.dev 上效果良好的 README 的建议
1. 在顶部放置简短描述
#根据我们的用户研究，package 用户只花几秒钟阅读 package 描述，并决定是否阅读 README 的其余部分。因此，您应该一目了然地简洁描述 package 的功能或作用。花些时间精心编写一个简短而恰当的描述，帮助用户做出决定。
以下是一些优秀描述的例子
一个用于显示彩虹的 Flutter 插件。使用机器学习对鸟叫声进行分类。
项目状态或限制等重要信息也应靠近顶部。例如
不支持低于 10.3 的 iOS 版本。
这是 in_app_purchase package 页面的截图，它以对 package 的简要说明和注意事项开始
徽章通常靠近 README 的顶部，可能在简短描述的上方或下方。
2. 包含视觉内容
#如果您的 package 页面是一堆没有视觉内容的文字，用户可能会觉得难以理解并停止阅读。如果您的 package 支持 UI，图像尤为重要，但它们对于解释重要概念也很有用。无论哪种情况，视觉内容都可以帮助用户对使用 package 感到自信。
将静态图像、动态 GIF 和视频（如 MOV 或 MP4 文件）等视觉内容放置在 README 的开头附近，用户很可能看到它们。
下面的截图显示了添加视觉内容如何使 in_app_purchase package 页面初看起来信息量丰富。（左边是之前的图片；右边是之后的图片。）
3. 使用列表展示重要信息
#列表可以引起对 README 中重要信息的注意。您可以将列表用于以下内容
通常，列表是项目符号列表，就像上面的列表一样。另一种选择是使用表格，例如下一节中平台支持的表格。
Package 的主要特性
#首先，清晰列出您的 package 可以做什么。一些用户可能正在寻找非常特定的功能。帮助这些用户找出您的 package 是否支持他们的需求。
以下截图显示了 in_app_purchase README 如何展示 package 的特性
下一张截图显示了 just_audio README 中的一个表格，其中列出了 package 的特性和平台支持
参数、属性或特性
#考虑列出参数、属性或特性以供快速参考。（请记住，package README 的内容会出现在 API 参考文档和 package 页面中。）
例如，url_launcher package 有一个支持的 URL 方案表格
链接到 API 参考文档中的特定函数或类也很有用。请参阅 async package 的示例。
特殊要求
#如果您的 package 需要超出所有 package 都需要的特定设置，请在 README 中列出设置说明。
例如，以下 google_maps_flutter package 的截图显示了 Google Maps Platform 的入门说明
不在您的 package 范围内的功能
#为了帮助用户了解您的 package 是否能帮助他们，列出用户可能期望但您的 package 不支持的功能。
以下是一些您可能需要列出超出范围功能的例子
- 如果您的按钮 package 仅专注于文本按钮，而不是图标按钮，请在 README 中明确说明。
- 如果您的 package 仅支持特定版本的 Android，请在 README 中说明。
目录
#当页面或章节有目录时，用户更容易导航。如果您的 README 中的某个章节很长，请考虑在该章节开头清晰列出小节。
例如，in_app_purchase README 的“用法”章节有很多示例。以下目录帮助用户了解存在哪些示例，并跳转到他们感兴趣的代码
4. 包含使用示例
#如果您的 package 看似很有希望，用户可能希望测试您的 package。包含一个“入门”或“用法”章节，其中至少有一个用户易于理解的代码示例，最好可以直接复制粘贴到他们的项目中。如果您能提供更多带有详细信息的示例，帮助用户理解您的 package，那就更好了。
记住，不是所有用户都说英语，但他们都说 Dart！好的代码示例可以发挥很大作用。考虑在您的 package 的 example 目录下添加更完整的示例，pub.dev 可以使用这些示例来填充示例标签页。有关详细信息，请参阅package 布局约定中的示例。
以下截图显示了 in_app_purchase package README 中的几个示例之一
5. 使用 Dart 代码格式化
#添加代码示例时，使用三个反引号加 dart (```dart)，而不是三个反引号 (```)。如下例所示，添加 dart 会告诉 pub.dev 使用 Dart 语法高亮
仅使用 ``` 格式化 | 使用 ```dart 格式化 |
|---|---|
| dart |
6. 提及相关术语
#最近的一项用户体验研究发现，许多用户使用页面内搜索功能（Control+F 或 Command+F）来搜索他们想要的功能。因此，请确保在 README 中提及重要术语，以便用户可以找到它们。
例如，用户可能想知道 in_app_purchase package 是否支持应用内订阅。搜索关键词 订阅 的用户如果页面没有使用该术语，可能会放弃该页面。
在提及人们可能搜索的所有术语后，请在使用术语时保持一致。如果需要，清晰定义术语。
例如，in_app_purchase package 在开头定义了底层商店
页面的其余部分始终使用该术语
7. 告诉用户下一步去哪里
#帮助您的用户了解更多关于 package 的信息。以下是一些关于告诉潜在用户的内容的建议
- 在哪里了解更多关于 package 的信息。您可以链接到 Medium 上的一篇文章，或 YouTube 上的视频。
- 在哪里获得使用 package 的帮助。可能包括问题跟踪器、聊天室或电子邮件地址。
- 您对 package 的未来计划。路线图（在 README 或外部页面中）可以帮助用户了解他们需要的功能是否即将推出。
- 如何为 package 贡献代码。
以下截图显示了 in_app_purchase README 中包含有关潜在贡献者信息的部分
了解更多关于优秀 README 创作的信息
#我们在本文档中提供了七个编写优秀 README 的技巧。您可以从谷歌开发者文档风格指南中了解更多关于开发者文档的常见建议。其他一些技巧包括
- 为图像提供 alt 文本。
- 简洁。不要说“请”。
- 保持行长 <= 80 个字符。
- 正确格式化代码（如
dart format）。
要了解更多关于优秀 README 实践的信息，请参阅这些资源
- README 清单
- 一份编写 README 的清单，帮助读者对您的项目充满信心。
- Awesome README
- 一份精选的、带有注释的优秀 README 列表。
- 制作 README
- README 的介绍，附带模板和编写优秀 README 的建议。
- 如何为你的 GitHub 项目编写一个优秀的 README
- 优秀 README 的关键要素和模板。
本页和其他页面中的建议可能并不适用于所有 package。发挥创意！设身处地为用户着想，想象读者可能想阅读和了解什么。您是唯一能提供读者所需信息的人。