撰寫套件頁面

此頁面上的準則有助於你在 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';

最近的一項 UX 研究發現，許多使用者會使用頁面內搜尋功能 (Control+F 或 Command+F) 來搜尋他們正在尋找的功能。因此，請務必在 README 中提到重要的詞彙，以便使用者可以找到它們。

例如，使用者可能想知道 in_app_purchase 套件是否支援應用程式內訂閱。如果頁面沒有使用該術語，搜尋關鍵字訂閱的使用者可能會離開該頁面。

在提到人們可能搜尋的所有術語後，請確保您使用的術語一致。如有需要，請清楚定義這些術語。

例如，in_app_purchase 套件在開頭定義了基礎商店

頁面的其他部分都一致地使用該術語

協助您的使用者進一步瞭解套件。以下是一些建議，說明可以告訴潛在使用者的資訊

• 深入瞭解套件的地方。您可以連結到 Medium 上的文章或 YouTube 上的影片。
• 取得套件使用說明的地方。可能性包括問題追蹤器、聊天室或電子郵件地址。
• 您計畫如何使用套件。使用說明或外部頁面中的路線圖可以協助使用者知道他們需要的功能是否即將推出。
• 如何對套件貢獻程式碼。

以下螢幕截圖顯示 in_app_purchase 說明中提供給潛在貢獻者的部分資訊

我們在此文件建議了七個撰寫良好說明的秘訣。您可以在 Google 開發人員文件樣式指南 中瞭解更多關於開發人員文件的常見建議。其他一些秘訣包括

• 提供圖片的替代文字。
• 簡潔扼要。不要說請。
• 將行長度保持在 <= 80 個字元。
• 正確格式化程式碼（就像 dart format 會做的那樣）。

若要瞭解更多關於良好說明實務，請參閱下列資源

說明檢查清單

撰寫說明的檢查清單，協助讀者對您的專案感到有信心。

很棒的說明

經過整理和註解的出色說明清單。

建立說明

說明簡介，包括範本和撰寫良好說明的建議。

如何為您的 GitHub 專案撰寫出色的說明

良好說明的主要元素和範本。

本頁和其他頁面中的建議可能不適用於所有套件。發揮創意！設身處地為使用者著想，並想像讀者可能想要閱讀和瞭解的內容。只有您能提供讀者需要資訊。