документация в пользовательском интерфейсе Google Таблиц и аннотации на уровне скриптов.
Google Apps Script использует JSDoc для генерации документации и автозаполнения для ваших скриптов. JSDoc — это стандарт для документирования кода JavaScript с помощью комментариев.
В Apps Script JSDoc выполняет следующие основные функции:
- Автозаполнение в редакторе : предоставление подсказок по параметрам и описаний функций по мере ввода текста.
- Пользовательские функции в Google Sheets : документирование пользовательских функций для их отображения во вспомогательной функции формул Sheets.
- Аннотации на уровне скрипта : использование специальных тегов для управления поведением скрипта в целом, например, авторизацией.
Функции документа
Для документирования функции разместите блок комментариев 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.
Входные данные : число — значение для умножения.
Общие теги
| Ярлык | Описание |
|---|---|
@param {type} name description | Документирует параметр функции. {type} и description используются средой разработки для автозаполнения. |
@return {type} description | Документирует возвращаемое значение функции. |
@example | Приводится пример использования функции. |
Перегрузки и различные типы
Хотя JavaScript не поддерживает классическую перегрузку функций (определение нескольких функций с одним и тем же именем), вы можете написать одну функцию, которая обрабатывает разные типы входных данных. Эти «перегруженные» функции можно задокументировать в JSDoc.
Типы объединения
Если параметр или возвращаемое значение может быть одного из нескольких типов, используйте символ вертикальной черты ( | ) для создания объединяющего типа. Это распространенная практика в Apps Script для функций, которые могут принимать либо одно значение, либо диапазон значений (представленный в виде двумерного массива).
/**
* 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 , чтобы она отображалась в автозаполнении и подсказках формул электронной таблицы.
JSDoc — это источник вспомогательного текста, который пользователи видят при использовании вашей пользовательской функции в Google Таблицах. Без JSDoc пользователи видели бы только название функции, что затрудняло бы понимание того, что делает функция или какие параметры она принимает.
Поддерживаемые теги и ограничения пользовательского интерфейса
Хотя Apps Script обрабатывает большинство стандартных тегов JSDoc, пользовательский интерфейс Google Sheets для пользовательских функций имеет некоторые специфические особенности и ограничения:
-
@customfunction: Необходимо для отображения функции в списке формул в Google Sheets. -
@param: Название и описание отображаются во вспомогательной функции формул в Google Sheets. -
@return: Описание, указанное в теге@return, не отображается во вспомогательной функции формул в Google Sheets. - Необязательные параметры : стандартный синтаксис JSDoc для необязательных параметров (например,
[name]илиname=) не распознается пользовательским интерфейсом Google Sheets. Все параметры будут отображаться как обязательные во вспомогательной функции формул. - Значения по умолчанию : Значения параметров по умолчанию (например,
[name=Value]) не поддерживаются в пользовательском интерфейсе Google Sheets. - Форматирование : HTML-теги и переносы строк в обычном тексте в описании не поддерживаются. Интерфейс Google Sheets отображает описание как единый блок текста и удаляет большую часть 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 Sheets отображает следующее вспомогательное окно:
РАССЧИТАННАЯ СКИДКА
Рассчитывает скидку.
Цена : Первоначальная цена.
Процент : Процент скидки (например, 0,1% означает 10%).
Обратите внимание, что описания параметров берутся непосредственно из ваших тегов JSDoc @param .
Аннотации на уровне скрипта
Apps Script использует уникальные теги JSDoc для управления настройками, применяемыми ко всему скрипту. Обычно они размещаются в верхней части файла скрипта.
Метки авторизации
| Ярлык | Описание |
|---|---|
@OnlyCurrentDoc | Указывает Apps Script запрашивать авторизацию только для текущего документа, а не для всех файлов этого типа. Дополнительные сведения см. в [Руководстве по авторизации](/apps-script/guides/services/authorization). |
@NotOnlyCurrentDoc | Используется в библиотеках для переопределения унаследованной аннотации @OnlyCurrentDoc . |