编写包页面

此页面上的指南可以帮助您在 pub.dev 上创建优秀的包页面。具体来说，此页面提供了有关编写更优秀的包 README 的技巧，该 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 插件。
• 使用机器学习对鸟鸣进行分类。

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

• 在 iOS 10.3 以下版本上无法使用。

这是 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';

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

例如，用户可能想知道in_app_purchase软件包是否支持应用内订阅。如果页面未使用“订阅”一词，则搜索关键字“订阅”的用户可能会放弃该页面。

在提及人们可能搜索的所有术语后，请保持使用术语的一致性。如有必要，请明确定义这些术语。

例如，in_app_purchase软件包在开头定义了“底层商店”

页面其余部分始终使用该术语

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

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

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

我们在这份文档中提出了七条关于编写良好 README 的建议。你可以从Google 开发人员文档样式指南中了解更多关于开发人员文档的常见建议。一些额外的提示包括

• 为图片提供替代文本。
• 简洁明了。不要使用“请”。
• 保持行长≤ 80 个字符。
• 正确格式化代码（如dart format所做的那样）。

要了解有关良好 README 实践的更多信息，请参阅以下资源

README 检查清单

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

优秀的 README

精心策划的、带注释的优秀 README 列表。

创建 README

关于 README 的介绍，包括模板和编写良好 README 的建议。

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

良好 README 的关键要素以及模板。

本页面和其他页面中的建议可能不适用于所有软件包。发挥你的创造力！设身处地为用户着想，想象一下读者可能想阅读和了解什么。只有你才能提供读者所需的信息。

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