為您的擴充功能建立使用者文檔

每個擴充功能都必須有文件來指導使用者該擴充功能的用途以及如何使用它。

最低要求的文件是這組三個 Markdown 文件：

  • PREINSTALL.md
  • POSTINSTALL.md
  • CHANGELOG.md

此外，您還應該考慮生產：

  • 擴充公共儲存庫的README文件。
  • 在您自己的網站上發布並在PREINSTALL.md中連結的較長形式的教程、指南和參考。

要了解一些最佳實踐以及常見的措辭和結構，我們建議您查看官方 Firebase 擴充功能提供的文件。

創建自述文件

您的擴充目錄可以選擇包含自述文件。請注意， firebase ext:dev:init指令不會自動為您產生一個。

不過，Firebase CLI 確實支援以下便利命令來自動產生README文件，其中包含從extension.yaml文件和PREINSTALL.md文件中提取的內容：

firebase ext:info ./path/to/extension --markdown > README.md

官方 Firebase 擴充功能的所有自述文件都是使用此命令產生的。

新增安裝訊息

編寫或產生自述文件後，請向其中新增安裝資訊。您可以使用以下程式碼片段作為模板：

---

## 🧩 Install this extension

### Console

[![Install this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][install-link]

[install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name

### Firebase CLI

```bash
firebase ext:install publisher_id/extension_name --project=[your-project-id]
```

> Learn more about installing extensions in the Firebase Extensions documentation:
> [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console),
> [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli)

---

編寫PREINSTALL文件

PREINSTALL文件是您的擴充功能的概述，一種「行銷」頁面。

這個文件裡有什麼內容？

  • 擴充功能的全面描述
  • 先決條件列表，例如資料庫設定或存取非 Google 服務（範例）
  • 所有預安裝任務及其說明的簡要說明
  • 任何安裝後任務的簡要描述（範例）（詳細說明請參閱POSTINSTALL ）
  • 任何計費影響的簡要描述（從樣板文字開始）

該內容在哪裡向用戶顯示？

Firebase 控制台中預先安裝內容的映像
在 Firebase 控制台中預先安裝內容

Firebase 控制台中預先安裝內容的大圖

PREINSTALL檔案無法存取擴充的參數值，因此您不應期望參數引用以實際值呈現。

有哪些最佳實務？

  • 如果可能的話，將PREINSTALL檔案的完整內容保留在一頁以內
  • 提供最終用戶在安裝擴充功能之前絕對需要了解的詳細信息
  • 將詳細說明放在POSTINSTALL文件或其他補充文件中
  • 簡要提及您是否提供其他工具或腳本來支援擴展

寫入POSTINSTALL文件

POSTINSTALL檔案是擴充功能的詳細安裝後指導頁面。

這個文件裡有什麼內容？

  • 有關任何必要的安裝後任務的詳細說明，例如設定 Firebase 安全性規則或新增用戶端程式碼（範例）
  • 有關如何立即試用已安裝擴充功能的通用說明（例如，「前往控制台，然後執行此操作」）
  • 有關如何觸發擴展的基本信息，尤其是HTTP 請求觸發的擴展
  • 有關如何監控已安裝擴充功能的簡要說明（從樣板文字開始）

該內容在哪裡向用戶顯示？

Firebase 控制台中安裝後內容的圖片
Firebase 控制台中的安裝後內容

Firebase 控制台中安裝後內容的大圖

  • 用戶安裝您的擴充功能後在 Firebase 控制台中（在已安裝擴充功能的詳細資訊卡中）

  • 您的擴充功能的原始碼儲存庫（在擴充目錄內）

POSTINSTALL檔案可以存取擴充的參數值和幾個與函數相關的變數。當POSTINSTALL內容顯示在 Firebase 控制台中時，將顯示實際值而不是參數或變數參考。以下詳細了解如何在POSTINSTALL檔案中引用參數和變數。

有哪些最佳實務？

  • 保持POSTINSTALL文件的完整內容簡潔但具有描述性。
  • 使用標題對內容進行劃分，以分解不同的任務或概念。
  • 考慮在您的網站（範例）或擴充儲存庫中的補充 Markdown 文件（範例）中發布特定工作流程或任務的詳細說明。
  • 參考參數和功能相關變量，以便使用者在指令上下文中看到其配置值

引用參數和變數

安裝後，Firebase 控制台會顯示擴充的POSTINSTALL檔案的內容。如果您在POSTINSTALL檔案中引用參數和與函數相關的變數（請參閱下表），則控制台會使用已安裝實例的實際值填入這些參考。

使用以下語法存取POSTINSTALL檔案中配置的參數值： ${param: PARAMETER_NAME }

您也可以僅在POSTINSTALL檔案中引用以下與函數相關的變數。 Firebase 支援這些變量，以便您可以更輕鬆地在安裝後為使用者提供指導。它們只能在POSTINSTALL檔案中使用，因為這些變數的值只有在安裝後才可用。

在此表中， function-name是extension.yaml內函數資源物件中name欄位的值。

函數相關變數參考描述變數值（擴充安裝後由 Firebase 自動填入）
${function: function-name .location}
功能部署位置範例值：
us-central1
${function: function-name .name}
最終部署的函數的名稱，其中包括擴展的實例 ID

通用格式：
ext- extension-instance-id - function-name

範例值：
ext-my-awesome-extension-6m31-yourFunctionName

${function: function-name .url} （僅適用於 HTTP 函數）
最終部署函數的 URL，客戶端程式碼可以向其發出 HTTP 請求

通用格式：
https:// deployment-location - project-id .cloudfunctions.net/ name-of-final-deployed-function

範例值：
https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

記錄如何觸發擴展

在擴充功能的使用者文件中，您需要指導使用者如何觸發您的擴充功能。這些說明可以按照您認為必要的程度詳細，但請記住編寫POSTINSTALL文件的最佳實踐。有關如何提供這些說明的指導，請展開下面適用於您的擴充功能的部分。

寫入 CHANGELOG 文件

這個文件裡有什麼內容？

每個擴充功能都必須有一個CHANGELOG.md文件，用於記錄您發布的擴充功能的每個新版本中包含的變更。將每個版本放在 2 級標題下 ( ## )；否則，您可以使用任何您喜歡的 Markdown 格式。

以下範例摘自官方擴充之一：

## Version 0.1.3

feature - Support deletion of directories (issue #148).

## Version 0.1.2

feature - Add a new param for recursively deleting subcollections in Cloud
Firestore (issue #14).

fixed - Fixed "cold start" errors experienced when the extension runs after a
period of inactivity (issue #48).

## Version 0.1.1

Initial release of the _Delete User Data_ extension.

該內容在哪裡向用戶顯示？

  • 在 Firebase 控制台和 CLI 中，當使用者升級到您的擴充功能的新版本時。 Firebase 控制台和 CLI 僅顯示使用者完成升級時將生效的變更。
  • 您的擴充功能的原始碼儲存庫（在擴充目錄內）。