編寫 package 頁面
本頁上的指南可以幫助您在 pub.dev 上建立優秀的 package 頁面。具體來說，本頁提供了編寫更好的 package README 的技巧，README 提供了以下截圖中標記為 README (本文件) 的內容。
有關 package 頁面其他部分的詳細資訊，請點選以下連結
編寫一個好的 README 很重要
#在 pub.dev 上找到您的 package 的使用者很可能會快速掃描 README，以決定是否嘗試您的 package。好的 README 能吸引讀者的注意力，並表明您的 package 值得嘗試。
雖然本頁以 in_app_purchase package 的 README 為特色，但您的 README 可能不需要那麼大或那麼詳細。如果您的 package 很簡單且沒有關聯的 UI，其 README 可能更像 yaml package 的 README。
編寫優秀 README 的七個技巧
#以下是一些關於建立在 pub.dev 上效果良好的 README 的建議
1. 在頂部放置簡短描述
#根據我們的使用者研究，package 使用者只花幾秒鐘閱讀 package 描述，並決定是否閱讀 README 的其餘部分。因此，您應該一目瞭然地簡潔描述 package 的功能或作用。花些時間精心編寫一個簡短而恰當的描述，幫助使用者做出決定。
以下是一些優秀描述的例子
一個用於顯示彩虹的 Flutter 外掛。使用機器學習對鳥叫聲進行分類。
專案狀態或限制等重要資訊也應靠近頂部。例如
不支援低於 10.3 的 iOS 版本。
這是 in_app_purchase package 頁面的截圖，它以對 package 的簡要說明和注意事項開始
徽章通常靠近 README 的頂部，可能在簡短描述的上方或下方。
2. 包含視覺內容
#如果您的 package 頁面是一堆沒有視覺內容的文字，使用者可能會覺得難以理解並停止閱讀。如果您的 package 支援 UI，影像尤為重要，但它們對於解釋重要概念也很有用。無論哪種情況，視覺內容都可以幫助使用者對使用 package 感到自信。
將靜態影像、動態 GIF 和影片（如 MOV 或 MP4 檔案）等視覺內容放置在 README 的開頭附近，使用者很可能看到它們。
下面的截圖顯示了新增視覺內容如何使 in_app_purchase package 頁面初看起來資訊量豐富。（左邊是之前的圖片；右邊是之後的圖片。）
3. 使用列表展示重要資訊
#列表可以引起對 README 中重要資訊的注意。您可以將列表用於以下內容
通常，列表是專案符號列表，就像上面的列表一樣。另一種選擇是使用表格，例如下一節中平臺支援的表格。
Package 的主要特性
#首先，清晰列出您的 package 可以做什麼。一些使用者可能正在尋找非常特定的功能。幫助這些使用者找出您的 package 是否支援他們的需求。
以下截圖顯示了 in_app_purchase README 如何展示 package 的特性
下一張截圖顯示了 just_audio README 中的一個表格，其中列出了 package 的特性和平臺支援
引數、屬性或特性
#考慮列出引數、屬性或特性以供快速參考。（請記住，package README 的內容會出現在 API 參考文件和 package 頁面中。）
例如，url_launcher package 有一個支援的 URL 方案表格
連結到 API 參考文件中的特定函式或類也很有用。請參閱 async package 的示例。
特殊要求
#如果您的 package 需要超出所有 package 都需要的特定設定，請在 README 中列出設定說明。
例如，以下 google_maps_flutter package 的截圖顯示了 Google Maps Platform 的入門說明
不在您的 package 範圍內的功能
#為了幫助使用者瞭解您的 package 是否能幫助他們，列出使用者可能期望但您的 package 不支援的功能。
以下是一些您可能需要列出超出範圍功能的例子
- 如果您的按鈕 package 僅專注於文字按鈕，而不是圖示按鈕，請在 README 中明確說明。
- 如果您的 package 僅支援特定版本的 Android，請在 README 中說明。
目錄
#當頁面或章節有目錄時，使用者更容易導航。如果您的 README 中的某個章節很長，請考慮在該章節開頭清晰列出小節。
例如，in_app_purchase README 的“用法”章節有很多示例。以下目錄幫助使用者瞭解存在哪些示例，並跳轉到他們感興趣的程式碼
4. 包含使用示例
#如果您的 package 看似很有希望，使用者可能希望測試您的 package。包含一個“入門”或“用法”章節，其中至少有一個使用者易於理解的程式碼示例，最好可以直接複製貼上到他們的專案中。如果您能提供更多帶有詳細資訊的示例，幫助使用者理解您的 package，那就更好了。
記住，不是所有使用者都說英語，但他們都說 Dart！好的程式碼示例可以發揮很大作用。考慮在您的 package 的 example 目錄下新增更完整的示例，pub.dev 可以使用這些示例來填充示例標籤頁。有關詳細資訊，請參閱package 佈局約定中的示例。
以下截圖顯示了 in_app_purchase package README 中的幾個示例之一
5. 使用 Dart 程式碼格式化
#新增程式碼示例時，使用三個反引號加 dart (```dart)，而不是三個反引號 (```)。如下例所示，新增 dart 會告訴 pub.dev 使用 Dart 語法高亮
僅使用 ``` 格式化 | 使用 ```dart 格式化 |
|---|---|
| dart |
6. 提及相關術語
#最近的一項使用者體驗研究發現，許多使用者使用頁面內搜尋功能（Control+F 或 Command+F）來搜尋他們想要的功能。因此，請確保在 README 中提及重要術語，以便使用者可以找到它們。
例如，使用者可能想知道 in_app_purchase package 是否支援應用內訂閱。搜尋關鍵詞 訂閱 的使用者如果頁面沒有使用該術語，可能會放棄該頁面。
在提及人們可能搜尋的所有術語後，請在使用術語時保持一致。如果需要，清晰定義術語。
例如，in_app_purchase package 在開頭定義了底層商店
頁面的其餘部分始終使用該術語
7. 告訴使用者下一步去哪裡
#幫助您的使用者瞭解更多關於 package 的資訊。以下是一些關於告訴潛在使用者的內容的建議
- 在哪裡瞭解更多關於 package 的資訊。您可以連結到 Medium 上的一篇文章，或 YouTube 上的影片。
- 在哪裡獲得使用 package 的幫助。可能包括問題跟蹤器、聊天室或電子郵件地址。
- 您對 package 的未來計劃。路線圖（在 README 或外部頁面中）可以幫助使用者瞭解他們需要的功能是否即將推出。
- 如何為 package 貢獻程式碼。
以下截圖顯示了 in_app_purchase README 中包含有關潛在貢獻者資訊的部分
瞭解更多關於優秀 README 創作的資訊
#我們在本文件中提供了七個編寫優秀 README 的技巧。您可以從谷歌開發者文件風格指南中瞭解更多關於開發者文件的常見建議。其他一些技巧包括
- 為影像提供 alt 文字。
- 簡潔。不要說“請”。
- 保持行長 <= 80 個字元。
- 正確格式化程式碼（如
dart format）。
要了解更多關於優秀 README 實踐的資訊，請參閱這些資源
- README 清單
- 一份編寫 README 的清單，幫助讀者對您的專案充滿信心。
- Awesome README
- 一份精選的、帶有註釋的優秀 README 列表。
- 製作 README
- README 的介紹，附帶模板和編寫優秀 README 的建議。
- 如何為你的 GitHub 專案編寫一個優秀的 README
- 優秀 README 的關鍵要素和模板。
本頁和其他頁面中的建議可能並不適用於所有 package。發揮創意！設身處地為使用者著想，想象讀者可能想閱讀和了解什麼。您是唯一能提供讀者所需資訊的人。