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