Apps Script 中的 JSDoc

Google 試算表使用者介面中的文件，以及指令碼層級的註解。

Google Apps Script 會使用 JSDoc 為指令碼產生說明文件和自動完成功能。JSDoc 是一種標準，可使用註解記錄 JavaScript 程式碼。

在 Apps Script 中，JSDoc 的主要用途如下：

  1. 編輯器中的自動完成功能：在您輸入內容時提供參數提示和函式說明。
  2. Google 試算表的自訂函式：記錄自訂函式，讓函式顯示在試算表公式輔助工具中。
  3. 指令碼層級的註解：使用特殊標記控管指令碼的整體行為，例如授權。

文件功能

如要記錄函式，請在函式宣告的正上方放置 JSDoc 註解區塊。JSDoc 註解以 /** 開頭，並以 */ 結尾。

/**
 * Multiplies an input value by 2.
 *
 * @param {number} input The value to multiply.
 * @return {number} The input multiplied by 2.
 */
function double(input) {
  return input * 2;
}

以這種方式記錄函式時，當您參照函式時，Apps Script 編輯器會顯示說明工具提示。舉例來說，在編輯器中輸入 double( 時，您會看到：

double(input)

將輸入值乘以 2。

input：數字 - 要相乘的值。

通用代碼

標記 說明
@param {type} name description 記錄函式參數。開發環境會使用 {type} 和 description 進行自動完成。
@return {type} description 記錄函式的傳回值。
@example 提供函式的使用範例。

多載和多種型別

雖然 JavaScript 不支援傳統函式多載 (定義多個同名函式)，但您可以編寫單一函式來處理不同類型的輸入內容。您可以在 JSDoc 中記錄這些「過載」行為。

聯集型別

如果參數或回傳值可以是多種型別，請使用管道 (|) 建立聯集型別。在 Apps Script 中，如果函式可接受單一值或值範圍 (以 2D 陣列表示)，通常會使用這個方法。

/**
 * Multiplies an input value (or a range of values) by 2.
 *
 * @param {number|number[][]} input The value or 2D array to multiply.
 * @return {number|number[][]} The result.
 */
function double(input) {
  return Array.isArray(input) ?
      input.map(row => row.map(cell => cell * 2)) :
      input * 2;
}

使用 @overload 建立多個簽名

如果函式的簽章複雜，且允許的參數互有關聯，您可以使用 @overload 標記定義每個不同的簽章。Apps Script 編輯器會根據您呼叫的函式版本，使用這些資訊提供特定提示。

/**
 * @overload
 * @param {string} name The name of the property to get.
 * @return {string} The property value.
 */
/**
 * @overload
 * @param {number} index The index of the item to get.
 * @return {object} The item object.
 */
function get(arg) {
  // Implementation that handles both cases
}

Google 試算表的自訂函式

為 Google 試算表撰寫自訂函式時，必須使用 @customfunction 標記，函式才會顯示在試算表的自動完成和公式輔助功能中。

使用者在 Google 試算表中使用自訂函式時，看到的輔助文字就是來自 JSDoc。如果沒有 JSDoc，使用者只會看到函式名稱，因此很難瞭解函式用途或所需參數。

支援的代碼和 UI 限制

雖然 Apps Script 會剖析大部分標準 JSDoc 標記，但自訂函式的 Google 試算表使用者介面有一些特定行為和限制：

  • @customfunction：函式必須有這個註解，才會顯示在 Google 試算表的公式清單中。
  • @param：名稱和說明會顯示在 Google 試算表公式輔助工具中。
  • @return：@return 標記中提供的說明不會顯示在試算表公式輔助工具中。
  • 選用參數：試算表 UI 無法辨識選用參數的標準 JSDoc 語法 (例如 [name] 或 name=)。公式輔助工具會將所有參數顯示為必要參數。
  • 預設值：Google 試算表使用者介面不支援預設參數值 (例如 [name=Value])。
  • 格式：系統不支援說明中的 HTML 標記和純文字換行符。Google 試算表 UI 會將說明顯示為單一文字區塊，並移除大部分的 HTML。

Google 試算表範例

/**
 * Calculates a discount.
 *
 * @param {number} price The original price.
 * @param {number} percent The discount percentage (e.g., 0.1 for 10%).
 * @return {number} The price after discount.
 * @customfunction
 */
function calculateDiscount(price, percent) {
  return price * (1 - percent);
}

使用者在 Google 試算表看到的內容

使用者在儲存格中輸入 =CALCULATEDISCOUNT( 時，Google 試算表會顯示下列輔助方塊：

CALCULATEDISCOUNT

計算折扣。

price：原價。

percent：折扣百分比 (例如 0.1 代表 10%)。

請注意，參數的說明直接來自 JSDoc @param 標記。

指令碼層級註解

Apps Script 會使用專屬的 JSDoc 標記來控管指令碼的整體設定。這些通常會放在指令碼檔案的頂端。

授權標記

標記 說明
@OnlyCurrentDoc 指示 Apps Script 只要求目前文件的授權，而非該類型的所有檔案。詳情請參閱 [授權指南](/apps-script/guides/services/authorization)。
@NotOnlyCurrentDoc 用於程式庫中，可覆寫已繼承的 @OnlyCurrentDoc 註解。