编写软件包页面

本页面的指南可以帮助你在 pub.dev 上创建优秀的软件包页面。具体来说，本页面提供了编写更优秀的软件包 README 的技巧，它提供了在以下屏幕截图中标记为 README（本文档） 的内容

有关软件包页面其他部分的详细信息，请点击以下链接

1. 软件包布局
2. Flutter 收藏
3. 软件包评分
4. 已验证的发布者
5. Pubspec 文件

在 pub.dev 上找到你的软件包的用户，很可能会快速浏览 README，以决定是否尝试你的软件包。优秀的 README 能够吸引读者的注意力，并表明你的软件包值得一试。

尽管此页面以 in_app_purchase 软件包的 README 为例，但你的 README 可能不需要如此庞大或详细。如果你的软件包很简单，并且没有关联的 UI，那么其 README 可能更像 yaml 软件包的 README。

以下是一些在 pub.dev 上创建效果良好的 README 的建议

1. 在顶部放置简短描述
2. 包含视觉内容
3. 使用列表呈现重要信息
4. 包含使用示例
5. 使用 Dart 代码格式化
6. 提及相关术语
7. 告诉用户接下来去哪里

根据我们的用户研究，软件包用户只花费几秒钟阅读软件包描述，并决定是否继续阅读 README 的其余部分。因此，你应该简洁地描述软件包的功能或用途，一目了然。花一些时间精心制作一个简短而精炼的描述，帮助用户做出决定。

以下是一些优秀描述的示例

• 一个用于显示彩虹的 Flutter 插件。
• 使用机器学习对鸟鸣声进行分类。

项目状态或约束等重要信息也应靠近顶部。例如

• 在低于 10.3 的 iOS 版本上不起作用。

这是 in_app_purchase 软件包页面的屏幕截图，该页面以软件包的简要说明和警告开头

徽章通常位于 README 的顶部附近，在简短描述的上方或下方。

如果你的软件包页面是文字墙，没有视觉内容，用户可能会感到望而却步并停止阅读。如果你的软件包支持 UI，那么图像尤其重要，但它们对于解释重要概念也很有用。无论如何，视觉内容都可以帮助用户对使用该软件包充满信心。

将静态图像、动画 GIF 和视频（如 MOV 或 MP4 文件）等视觉内容放在 README 的开头附近，用户很可能会看到它们。

下面的屏幕截图显示了添加视觉内容如何使 in_app_purchase 软件包页面在第一眼看起来就信息丰富。（之前的图片在左侧；之后的图片在右侧。）

列表可以吸引对 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 的“用法”部分有很多示例。以下目录帮助用户了解存在哪些示例，并转到他们感兴趣的代码

如果你的软件包看起来很有前景，用户可能想测试你的软件包。包含一个“开始”或“用法”部分，其中至少有一个代码示例，用户可以轻松理解，并且理想情况下，他们可以复制并粘贴到他们的项目中。如果可以提供更多更详细的示例来帮助用户理解你的软件包，那就更好了。

请记住，并非所有用户都说英语，但他们都说 Dart！好的代码示例可以大有帮助。考虑在软件包的 example 目录下添加更完整的示例，pub.dev 可以使用这些示例来填充“示例”选项卡。有关详细信息，请参见 软件包布局约定中的示例。

以下屏幕截图显示了 in_app_purchase 软件包 README 中的几个示例之一

添加代码示例时，请使用三个反引号加 dart (```dart) 而不是三个反引号 (```)。如下例所示，添加 dart 会告诉 pub.dev 使用 Dart 语法高亮显示

final like = 'this';

final like = 'this';

最近的一项 UX 研究发现，许多用户使用页面内搜索功能（Control+F 或 Command+F）来搜索他们正在寻找的功能。因此，请务必在 README 中提及重要术语，以便用户可以找到它们。

例如，用户可能想知道 in_app_purchase 软件包是否支持应用内订阅。搜索关键字 subscription 的用户可能会放弃该页面，如果该页面没有使用该术语。

在提及人们可能搜索的所有术语后，请保持你使用的术语的一致性。如果需要，请清楚地定义术语。

例如，in_app_purchase 软件包在开头定义了 underlying store

页面的其余部分始终如一地使用该术语

帮助你的用户了解更多关于软件包的信息。以下是一些关于应该告诉潜在用户的建议

• 在哪里了解更多关于软件包的信息。你可以链接到 Medium 上的文章，或者 YouTube 上的视频。
• 在哪里获得关于使用软件包的帮助。可能性包括问题跟踪器、聊天室或电子邮件地址。
• 你计划对软件包做什么。路线图（无论是在 README 中还是在外部页面中）可以帮助用户了解他们需要的功能是否即将推出。
• 如何为软件包贡献代码。

以下屏幕截图显示了 in_app_purchase README 中包含潜在贡献者信息的部分

我们在本文档中提出了编写优秀 README 的七个技巧。你可以从《Google 开发者文档风格指南》中了解更多关于开发者文档的常见建议。一些其他提示包括

• 为图像提供 alt 文本。
• 简洁明了。不要说“请”。
• 保持行长 <= 80 个字符。
• 正确格式化代码（如同 dart format 的格式）。

要了解更多关于优秀 README 实践的信息，请参阅以下资源

README 检查清单

一个用于编写 README 的检查清单，帮助读者对你的项目充满信心。

Awesome README

一个精选的、带有注释的优秀 README 列表。

创建 README

README 介绍，包含模板和优秀 README 的建议。

如何为你的 GitHub 项目编写优秀的 README

优秀 README 的关键要素和一个模板。

此页面和其他页面中的建议可能不适用于所有软件包。要有创意！站在用户的角度思考，想象读者可能想阅读和了解什么。你是唯一可以提供读者所需信息的人。

除非另有说明，否则本网站上的文档反映的是 Dart 3.7.1 版本。页面上次更新于 2024-05-06。 查看源代码 或 报告问题。