Apps 脚本中的 JSDoc

Google 表格界面中的文档和脚本级注释。

Google Apps 脚本使用 JSDoc 为您的脚本生成文档和自动补全功能。JSDoc 是一种使用注释记录 JavaScript 代码的标准。

在 Apps 脚本中，JSDoc 主要用于以下用途：

  1. 编辑器中的自动补全功能：在您输入内容时提供形参提示和函数说明。
  2. Google 表格中的自定义函数：记录自定义函数，以便它们显示在 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 脚本编辑器会显示文档提示。例如，当您在编辑器中输入 double( 时，您会看到：

double(input)

将输入值乘以 2。

input：number - 要相乘的值。

常见标记

标记 说明
@param {type} name description 记录函数参数。开发环境使用 {type} 和 description 进行自动补全。
@return {type} description 记录函数的返回值。
@example 提供了一个有关如何使用该函数的示例。

重载和多种类型

虽然 JavaScript 不支持经典函数重载（定义多个同名函数），但您可以编写一个能够处理不同类型输入的函数。您可以在 JSDoc 中记录这些“重载”行为。

联合类型

如果形参或返回值可以是多种类型之一，请使用竖线 (|) 创建联合类型。在 Apps 脚本中，对于可以接受单个值或一系列值（以二维数组表示）的函数，这很常见。

/**
 * 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 脚本编辑器会使用这些信息，根据您调用的函数版本提供具体提示。

/**
 * @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 标记，以便该函数显示在电子表格的自动补全和公式帮助程序中。

JSDoc 是用户在 Google 表格中使用自定义函数时看到的帮助文本的来源。如果没有 JSDoc，用户只能看到函数名称，很难知道函数的作用或需要哪些参数。

支持的代码和界面限制

虽然 Apps 脚本会解析大多数标准 JSDoc 标记，但自定义函数的 Google 表格界面具有一些特定行为和限制：

  • @customfunction：必需，用于在 Google 表格公式列表中显示该函数。
  • @param：名称和说明会显示在 Google 表格公式帮助程序中。
  • @return：@return 标记中提供的说明不会显示在 Google 表格的公式助手中。
  • 可选参数：Google 表格界面无法识别用于表示可选参数的标准 JSDoc 语法（例如 [name] 或 name=）。所有参数在公式帮助程序中都会显示为必需参数。
  • 默认值：Google 表格界面不支持默认参数值（例如 [name=Value]）。
  • 格式：说明中不支持 HTML 标记和纯文本换行符。Google 表格界面会将说明显示为单个文本块，并剥离大部分 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 脚本使用独特的 JSDoc 标记来控制脚本范围的设置。这些声明通常放置在脚本文件的顶部。

授权标记

标记 说明
@OnlyCurrentDoc 告知 Apps 脚本仅请求当前文档的授权，而不是该类型的所有文件的授权。如需了解详情，请参阅 [授权指南](/apps-script/guides/services/authorization)。
@NotOnlyCurrentDoc 用于库中以替换继承的 @OnlyCurrentDoc 注释。