编写软件包页面
本页上的指南可以帮助你在 pub.dev 上创建好的软件包页面。具体来说，本页提供了有关编写更好的软件包 README 的技巧，该 README 提供了以下屏幕截图中标记为 README (本文档) 的内容
有关软件包页面其他部分的详细信息，请点击以下链接
编写一个好的 README 很重要
#在 pub.dev 上找到你的软件包的人很可能会快速浏览 README，以决定是否尝试你的软件包。一个好的 README 会吸引读者的注意，并表明你的软件包值得尝试。
尽管此页面以 in_app_purchase 软件包的 README 为例，但你的软件包可能不需要这么大或这么详细。如果你的软件包很简单并且没有相关的 UI，那么它的 README 可能更像 yaml 软件包的 README。
编写好的 README 的七个技巧
#以下是一些关于创建在 pub.dev 上效果良好的 README 的建议
1. 在顶部放置简短的描述
#根据我们的用户研究，软件包用户只花几秒钟阅读软件包描述，然后决定是否阅读 README 的其余部分。因此，你应该简洁地描述软件包的功能或作用。花一些时间来编写一个简短而精彩的描述，并帮助用户做出决定。
以下是一些好的描述的示例
一个用于显示彩虹的 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 Maps Platform 的说明
超出软件包范围的功能
#为了帮助用户了解你的软件包是否可以帮助他们，请列出用户可能期望的功能，但你的软件包不支持的功能。
以下是一些你可能需要列出超出范围的功能的示例
- 如果你的按钮软件包仅专注于文本按钮而不专注于图标按钮，请在 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. 提及相关术语
#最近的一项用户体验研究发现，许多用户使用页面内搜索功能（Control+F 或 Command+F）来搜索他们正在寻找的功能。因此，请务必在 README 中提及重要的术语，以便用户可以找到它们。
例如，用户可能想知道 in_app_purchase 包是否支持应用内订阅。如果页面没有使用 subscription 这个关键词，搜索这个关键词的用户可能会放弃这个页面。
在提及所有人们可能搜索的术语之后，请保持术语使用的一致性。如有必要，请明确定义这些术语。
例如，in_app_purchase 包在一开始就定义了 底层商店（underlying store）。
页面的其余部分始终如一地使用这个术语。
7. 告诉用户下一步去哪里
#帮助您的用户更多地了解该包。以下是一些建议，可以告诉潜在用户什么：
- 在哪里了解有关该软件包的更多信息。您可能会链接到 Medium 上的一篇文章，或 YouTube 上的视频。
- 在哪里获得有关使用该软件包的帮助。可能的途径包括问题跟踪器、聊天室或电子邮件地址。
- 您计划如何使用该软件包。路线图（无论是在 README 中还是在外部页面中）都可以帮助用户了解他们需要的功能是否即将推出。
- 如何为该软件包贡献代码。
以下屏幕截图显示了 in_app_purchase README 中包含潜在贡献者信息的部分。
了解更多关于编写优秀 README 的信息
#我们在这篇文档中提出了七个关于良好 README 的建议。您可以从Google 开发者文档样式指南中了解更多关于开发者文档的常见建议。其他一些建议包括：
- 为图像提供 alt 文本。
- 简洁明了。不要说“请”。
- 保持行长 <= 80 个字符。
- 正确格式化代码（如
dart format会做的那样）。
要了解有关良好 README 实践的更多信息，请参阅以下资源：
- README 清单
- 一个编写 README 的清单，可帮助读者对您的项目充满信心。
- 超棒的 README
- 一个经过策划的、带有注释的优秀 README 列表。
- 制作一个 README
- README 的介绍，带有模板和良好 README 的建议。
- 如何为您的 GitHub 项目编写一个很棒的 README
- 良好 README 的关键要素和一个模板。
此页面和其他页面中的建议可能不适用于所有软件包。要有创造力！将自己置于用户的角度，想象读者可能想阅读和了解什么。只有您才能提供读者需要的信息。
除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2024-05-06。 查看源代码 或 报告问题。