撰寫套件頁面
本頁面的指南可以協助您在 pub.dev 上建立良好的套件頁面。具體來說，本頁面提供撰寫更佳套件 README 的訣竅，README 提供以下螢幕截圖中標示為 README (本文件) 的內容
如需套件頁面其他部分的詳細資訊，請點擊以下連結
撰寫良好的 README 很重要
#在 pub.dev 上找到您的套件的使用者，在決定是否試用您的套件時，可能會快速掃描 README。良好的 README 能吸引讀者的注意力，並顯示您的套件值得一試。
雖然本頁面以 in_app_purchase 套件的 README 為例，但您的 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 套件在一開始就定義了底層商店
頁面的其餘部分一致地使用該術語
7. 告訴使用者下一步該去哪裡
#協助您的使用者瞭解更多關於套件的資訊。以下是一些關於可以告訴潛在使用者的建議
- 在哪裡可以瞭解更多關於套件的資訊。您可以連結到 Medium 上的文章，或 YouTube 上的影片。
- 在哪裡可以獲得有關使用套件的協助。可能性包括問題追蹤器、聊天室或電子郵件地址。
- 您計劃如何處理套件。路線圖 (無論是在 README 中還是外部頁面中) 可以幫助使用者瞭解他們需要的功能是否即將推出。
- 如何為套件貢獻程式碼。
以下螢幕截圖顯示 in_app_purchase README 中包含潛在貢獻者資訊的部分
深入瞭解如何撰寫良好的 README
#我們在本文件中提出了撰寫良好 README 的七個訣竅。您可以從Google 開發人員文件樣式指南中瞭解更多關於開發人員文件的常見建議。一些額外的提示包括
- 為圖片提供替代文字。
- 簡潔扼要。不要說「請」。
- 保持行長度 <= 80 個字元。
- 正確格式化程式碼 (如同
dart format的格式)。
若要深入瞭解良好的 README 實務，請參閱以下資源
- README 檢查清單
- 一份撰寫 README 的檢查清單，可協助讀者對您的專案感到有信心。
- Awesome README
- 一份精選且註解豐富的優秀 README 列表。
- 製作 README
- README 簡介，包含範本和撰寫良好 README 的建議。
- 如何為您的 GitHub 專案撰寫出色的 README
- 良好 README 的關鍵要素和範本。
本頁面和其他頁面中的建議可能不適用於所有套件。發揮創意！站在使用者的角度思考，想像讀者可能想閱讀和瞭解什麼。您是唯一可以提供讀者所需資訊的人。
除非另有說明，否則本網站上的文件反映 Dart 3.7.1 版本。頁面最後更新於 2024-05-06。 檢視原始碼 或 回報問題。