撰寫套件頁面
此頁面的指南可以幫助您在 pub.dev 上建立良好的套件頁面。具體來說，此頁面提供撰寫更好的套件 README 的技巧，該檔案提供以下螢幕截圖中標示為 README (此文件) 的內容
如需套件頁面其他部分的詳細資訊，請按一下下列連結
撰寫良好的 README 很重要
#在 pub.dev 上找到您套件的人，在決定是否嘗試您的套件時，可能會快速掃描 README。一個良好的 README 會吸引讀者的注意力，並表明您的套件值得一試。
雖然此頁面以 in_app_purchase 套件的 README 為例，但您的套件可能不需要這麼大或這麼詳細。如果您的套件很簡單，並且沒有相關的 UI，則其 README 可能會更像 yaml 套件的 README。
撰寫良好 README 的七個技巧
#以下是一些在 pub.dev 上運作良好的 README 建立建議
1. 在頂部放置簡短描述
#根據我們的使用者研究，套件使用者只花幾秒鐘閱讀套件描述，然後決定是否閱讀 README 的其餘部分。因此，您應該簡明扼要地描述套件的功能或達成的目標。花一些時間撰寫簡短而精確的描述，幫助使用者做出決定。
以下是一些良好描述的範例
用於顯示彩虹的 Flutter 外掛程式。使用機器學習來分類鳥叫聲。
專案狀態或限制等重要資訊也應靠近頂部。例如
在 10.3 以下的 iOS 版本上無法運作。
這是 in_app_purchase 套件頁面的螢幕截圖，其中以簡短的套件說明和警告開始
徽章通常位於 README 的頂部附近，在簡短描述的上方或下方。
2. 包含視覺內容
#如果您的套件頁面是一大段文字而沒有視覺內容，使用者可能會覺得它令人望而生畏並停止閱讀。如果您的套件支援 UI，則圖片尤其重要，但它們對於解釋重要概念也很有用。無論如何，視覺內容可以幫助使用者對使用該套件感到有信心。
將靜態圖片、動畫 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 套件的螢幕截圖顯示了有關開始使用 Google Maps Platform 的說明
超出您套件範圍的功能
#為了協助使用者了解您的套件是否可以幫助他們，請列出使用者可能會預期，但您的套件不支援的功能。
以下是一些您可能想要列出範圍外功能的範例
- 如果您的按鈕套件僅專注於文字按鈕，而不是圖示按鈕，請在 README 中明確說明。
- 如果您的套件僅支援特定版本的 Android，請在 README 中說明。
內容
#當頁面或區段具有目錄時，使用者更容易瀏覽。如果您的 README 中的區段很長，請考慮在區段的開頭清楚列出小節。
例如，in_app_purchase README 的「用法」區段有很多範例。以下目錄有助於使用者了解存在哪些範例，並前往他們感興趣的程式碼
4. 包含使用範例
#如果您的套件看起來很有希望，使用者可能會想要測試您的套件。請包含「開始使用」或「用法」區段，其中至少有一個使用者可以輕鬆理解的程式碼範例 — 理想情況下，他們可以複製並貼到自己的專案中。如果您可以提供更多更詳細的範例，以幫助使用者了解您的套件，那就更好了。
請記住，並非所有使用者都說英語，但他們都說 Dart！良好的程式碼範例可以產生很大的作用。請考慮在套件的 example 目錄下新增更完整的範例，pub.dev 可以使用該目錄來填入 範例 標籤。如需詳細資訊，請參閱範例，網址：套件佈局慣例。
以下螢幕截圖顯示 in_app_purchase 套件 README 中的幾個範例之一
5. 使用 Dart 程式碼格式
#當加入程式碼範例時，請使用三個反引號加上 dart (```dart) 而不是只有三個反引號 (```)。如下列範例所示，加入 dart 會告知 pub.dev 使用 Dart 語法高亮顯示。
僅使用 ``` 格式化 | 使用 ```dart 格式化 |
|---|---|
| dart |
6. 提及相關術語
#最近一項 UX 研究發現，許多使用者會使用頁面內的搜尋功能（Control+F 或 Command+F）來搜尋他們需要的功能。因此，請務必在 README 中提及重要的術語，以便使用者能夠找到它們。
例如，使用者可能想知道 in_app_purchase 套件是否支援應用程式內訂閱。如果頁面沒有使用「訂閱」這個術語，搜尋「訂閱」關鍵字的使用者可能會放棄瀏覽該頁面。
在提及所有使用者可能會搜尋的術語之後，請保持使用術語的一致性。如有需要，請清楚地定義這些術語。
例如，in_app_purchase 套件在開頭定義了「底層商店」(underlying store)。
頁面的其餘部分都一致地使用該術語。
7. 告訴使用者下一步該去哪裡
#幫助您的使用者了解更多關於該套件的資訊。以下是一些關於可以告訴潛在使用者的建議：
- 在哪裡可以了解更多關於該套件的資訊。您可以連結到 Medium 上的一篇文章，或 YouTube 上的一段影片。
- 在哪裡可以獲得關於使用該套件的幫助。可能的選項包括問題追蹤器、聊天室或電子郵件地址。
- 您計劃如何處理該套件。一份路線圖（無論是在 README 中還是外部頁面中）可以幫助使用者了解他們需要的功能是否即將推出。
- 如何為該套件貢獻程式碼。
以下螢幕截圖顯示了 in_app_purchase README 中為潛在貢獻者提供資訊的部分。
深入瞭解如何撰寫良好的 README
#我們在本文件中提出了七個關於撰寫良好 README 的技巧。您可以從 Google 開發人員文件樣式指南 中了解更多關於開發人員文件的常見建議。一些額外的技巧包括：
- 為圖片提供替代文字 (alt text)。
- 簡潔扼要。不要使用「請」之類的字詞。
- 保持行長 <= 80 個字元。
- 正確格式化程式碼（如同
dart format會做的那樣）。
要了解更多關於良好的 README 實務，請參閱以下資源：
- README 清單
- 一份用於撰寫 README 的清單，可幫助讀者對您的專案感到有信心。
- 超讚的 README
- 一份精選的、附有註釋的優秀 README 清單。
- 建立 README
- 一篇關於 README 的介紹，包含一個範本和關於撰寫良好 README 的建議。
- 如何為您的 GitHub 專案撰寫一個出色的 README
- 良好 README 的關鍵要素以及範本。
此頁面和其他頁面中的建議可能不適用於所有套件。發揮創意！設身處地為使用者著想，想像讀者可能想閱讀和了解什麼。您是唯一可以提供讀者所需資訊的人。
除非另有說明，本網站上的文件反映了 Dart 3.6.0。頁面最後更新於 2024-05-06。 檢視原始碼 或 回報問題。