编写包页面

本页指南可帮助您在 pub.dev 上创建优秀的包页面。具体来说，本页提供了撰写更佳包自述文件的技巧，该文件提供了以下屏幕截图中标有 自述文件 (本文档) 的内容：

有关包页面其他部分的详细信息，请访问以下链接：

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

在 pub.dev 上找到您的包的人员，在决定是否尝试使用您的包时，很可能会快速浏览自述文件。优秀的自述文件能够吸引读者的注意力，并表明您的包值得一试。

虽然本页以 in_app_purchase 包的自述文件为例，但您的自述文件可能不需要这么大或这么详细。如果您的包很简单且没有关联的 UI，则其自述文件可能更类似于 yaml 包的自述文件。

以下是一些关于在 pub.dev 上创建有效自述文件的建议：

1. 在顶部添加简短说明
2. 包含视觉内容
3. 使用列表呈现重要信息
4. 包含使用示例
5. 使用 Dart 代码格式
6. 提及相关术语
7. 告诉用户下一步该做什么

根据我们的用户研究，包用户仅花费几秒钟时间阅读包说明并决定是否阅读自述文件的其余部分。因此，您应该简洁地描述包的功能或目标，一目了然。花一些时间来撰写简短而精辟的说明，并帮助用户做出决策。

以下是一些优秀的说明示例：

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

重要信息（例如项目状态或约束）也应位于顶部附近。例如：

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

以下是 in_app_purchase 包页面的屏幕截图，该页面以对包的简要解释和警告开头：

徽章 通常位于自述文件的顶部附近，位于简短说明的上方或下方。

如果您的包页面是一堵没有视觉内容的文字墙，用户可能会觉得它令人生畏而停止阅读。如果您的包支持 UI，则图像尤其重要，但它们也可用于解释重要概念。无论哪种方式，视觉内容都可以帮助用户对使用该包充满信心。

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

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

列表可以将自述文件上的重要信息提请注意。您可以将列表用于以下用途：

• 包的关键特性
• 参数、属性或特性
• 特殊要求
• 包范围之外的功能
• 页面或页面内部分内容的摘要（如本列表）

通常，列表是项目符号列表，如上面的列表。另一种选择是使用表格，例如下一节中平台支持的表格。

首先，清楚地列出您的包可以做什么。一些用户可能正在寻找非常具体的特性。帮助这些用户了解您的包是否支持他们的需求。

以下屏幕截图显示了 in_app_purchase 自述文件如何呈现包的特性：

下一个屏幕截图显示了 just_audio 自述文件中的一个表格，该表格列出了包的特性和平台支持：

考虑列出参数、属性或特性以供快速参考。（请记住，包自述文件的内容会出现在 API 参考文档中，以及包页面中。）

例如， url_launcher 包有一个支持的 URL 方案表：

链接到 API 参考文档中的特定函数或类也很有用。请参阅 async 包以了解示例。

如果您的包需要特定的设置，而不仅仅是所有包都需要的内容，请在自述文件中列出设置说明。

例如， google_maps_flutter 包的以下屏幕截图显示了开始使用 Google Maps Platform 的说明：

为了帮助用户了解您的包是否可以帮助他们，请列出用户可能期望但您的包 不支持 的特性。

以下是一些您可能需要列出范围之外的功能的示例：

• 如果您的按钮包只关注文本按钮，而不关注图标按钮，请在自述文件中明确说明。
• 如果您的包只支持特定版本的 Android，请在自述文件中说明。

当页面或部分具有目录时，用户会更容易浏览。如果自述文件中的某个部分很长，请考虑在该部分开头清楚地列出子部分。

例如， in_app_purchase 自述文件的“用法”部分有很多示例。以下目录有助于用户了解存在哪些示例，以及转到他们感兴趣的代码：

如果您的包看起来很有前景，用户可能希望测试您的包。包含“入门”或“用法”部分，其中至少包含一个用户易于理解的代码示例——理想情况下，他们可以将其复制并粘贴到他们的项目中。如果您能提供更多更详细的示例来帮助用户了解您的包，那就更好了。

请记住，并非所有用户都说法语，但他们都会说 Dart！好的代码示例可以起到很大的作用。考虑在您的包的 example 目录下添加更完整的示例，pub.dev 可以使用这些示例填充 示例 选项卡。有关详细信息，请参阅 示例 中的 包布局约定 。

以下屏幕截图显示了 in_app_purchase 包自述文件中的一些示例之一：

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

final like = 'this';

final like = 'this';

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

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

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

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

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

帮助您的用户了解有关该包的更多信息。以下是一些关于告诉潜在用户的建议：

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

以下屏幕截图显示了 in_app_purchase 自述文件的一部分，其中包含供潜在贡献者使用信息：

<img src="/assets/img/libraries/package-page-contribute.png"

本文档中我们建议了七个编写优秀自述文件的技巧。您可以从 Google 开发者文档样式指南 中了解有关开发者文档常见建议的更多信息。一些额外的技巧包括：

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

要了解有关优秀自述文件实践的更多信息，请参阅以下资源：

自述文件清单 ：一个编写自述文件的清单，可帮助读者对您的项目充满信心。

优秀的自述文件 ：一份精心策划的、带注释的优秀自述文件列表。

创建自述文件 ：对自述文件的介绍，其中包含模板和编写优秀自述文件的建议。

如何为您的 GitHub 项目编写优秀的自述文件 ：优秀自述文件的关键要素和模板。

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

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。 查看源代码 或 报告问题.