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

软件包页面包含的部分有：软件包布局、flutter收藏夹、软件包评分、经过验证的发布者、pubspec文件

关于软件包页面的其他部分的细节，请关注这些链接。

1. 软件包的布局
2. Flutter 最爱
3. 软件包的评分
4. 经过验证的出版商
5. Pubspec文件

编写一个好的README很重要

在pub.dev上找到你的软件包的人，在决定是否尝试你的软件包时，很可能会快速扫描README。一个好的README能吸引读者的注意力，并表明你的软件包值得一试。

虽然这个页面以in_app_purchase包的README为特色，但你的包可能不需要那么大或那么详细。如果你的包很简单，没有相关的用户界面，它的README可能看起来更像yaml包的那个。

好的README的七个提示

这里有一些关于创建在pub.dev上运行良好的README的建议。

1. 在顶部放一个简短的描述
2. 包括视觉内容
3. 使用列表来展示重要信息
4. 包括使用实例
5. 使用Dart代码格式化
6. 提及相关术语
7. 告诉用户下一步该怎么走

1. 在顶部放一个简短的描述

根据我们的用户研究，软件包的用户只花几秒钟的时间来阅读软件包的描述，并决定是否阅读README的其他内容。因此，你应该简明扼要地描述软件包所做的或所实现的，一目了然。花点时间精心制作一个简短而温馨的描述，帮助用户做出决定。

这里有一些好的描述的例子。

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

重要的信息，如项目状态或约束条件，也应该放在靠近顶部的位置。比如说。

• 不适用于10.3以下的iOS版本。

下面是in_app_purchase软件包页面的截图，它的开头是对软件包的简要解释和注意事项。

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

2. 包括视觉内容

如果你的软件包页面是一堵没有视觉内容的文字墙，用户可能会觉得它很吓人而停止阅读。如果你的软件包支持用户界面，图片就特别重要，但它们对解释重要的概念也很有用。无论怎样，视觉内容可以帮助用户对使用软件包有信心。

把静态图片、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包的截图，显示了关于开始使用谷歌地图平台的说明。

不属于你的包的范围的功能

为了帮助用户了解你的软件包是否能帮助他们，请列出用户可能期望的、但你的软件包不支持的功能。

下面是一些例子，说明你可能想列出超出范围的功能。

• 如果你的按钮包只专注于文本按钮，而不支持图标按钮，请在README中明确说明。
• 如果你的包只支持某些版本的Android，在README中说明。

内容

当一个页面或章节有一个目录时，用户会发现它更容易导航。如果你的README中的某一节非常长，可以考虑在该节的开头清楚地列出各分节。

例如，in_app_purchase README 的 "用法 "部分有很多例子。下面的目录可以帮助用户了解存在哪些例子，并转到他们感兴趣的代码。

4. 包括使用范例

如果你的包看起来很有前途，用户可能想测试你的包。包括一个 "开始 "或 "使用 "部分，其中至少有一个用户可以轻松理解的代码样本--而且，最好是他们可以复制和粘贴到他们的项目中。如果你能提供更多的例子和更多的细节来帮助用户理解你的软件包，那就更好了。

请记住，不是所有的用户都会说英语，但他们都会说Dart! 好的代码样本可以发挥很大的作用。考虑在你的软件包的例子目录下添加更完整的例子，pub.dev可以用它来填充例子标签。详情请见软件包布局惯例中的例子。

下面的截图显示了 in_app_purchase 包的 README 中的几个例子之一。

5. 使用Dart代码格式化

在添加代码示例时，使用三个背号加dart（```dart）而不是三个背号（```）。正如下面的例子所示，添加dart告诉pub.dev使用Dart语法高亮。

• 只使用```格式化

final like = 'this';

• 使用```dart格式化

final like = 'this';

6. 提及相关术语

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

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

在提到人们可能搜索的所有术语后，对你使用的术语要保持一致。如果需要，明确定义这些术语。

例如，in_app_purchase包在开头就定义了底层商店。

页面的其余部分一致地使用该术语。

7. 告诉用户下一步该去哪里

帮助你的用户找到更多关于软件包的信息。这里有一些关于告诉潜在用户的建议。

• 在哪里可以了解更多关于这个包的信息。你可以链接到Medium上的一篇文章，或YouTube上的一段视频。
• 在哪里可以得到关于使用该软件包的帮助。可能包括一个问题跟踪器、一个聊天室或一个电子邮件地址。
• 你打算用这个包做什么。路线图--在README或外部页面中--可以帮助用户知道他们需要的功能是否即将到来。
• 如何为软件包贡献代码。

下面的截图显示了in_app_purchase README中为潜在贡献者提供信息的部分。

了解更多关于好的README编写的信息

我们在这篇文档中提出了好的README的七个提示。你可以从《谷歌开发者文档风格指南》中了解更多关于开发者文档的常见建议。一些额外的提示包括。

• 为图片提供alt文本。
• 言简意赅。不要说请。
• 保持行长<=80个字符。
• 正确格式化代码（如dartfmt或flutter format）。

要了解更多关于README的良好做法，请参阅这些资源。

README检查表 写README的检查表，帮助读者对你的项目有信心。

优秀的README 一个精心策划的、有注释的优秀 README 列表。

制作README 一个关于README的介绍，包括一个好的README的模板和建议。

如何为你的GitHub项目写一个好的README 一个好的README的关键元素，以及一个模板。

本页中的建议和其他建议可能不适合所有软件包。要有创意! 设身处地为用户着想，想象读者可能想要阅读和了解什么。你是唯一能提供读者所需信息的人。

www.deepl.com 翻译