Библиотеки

Библиотека — это проект сценария, функции которого можно повторно использовать в других сценариях.

Получить доступ к библиотеке

Чтобы включить библиотеку в свой проект, вам необходим доступ к ней как минимум на уровне просмотра. Если вы не являетесь автором библиотеки, которую хотите включить, свяжитесь с автором и запросите доступ.

Вам понадобится идентификатор скрипта библиотеки, которую вы хотите включить. Если у вас есть доступ к библиотеке, идентификатор скрипта можно найти на странице settings проекта .

Добавьте библиотеку в свой проект скрипта

1. В левой части редактора Apps Script, рядом с пунктом «Библиотеки», нажмите add библиотеку.
2. В поле «ID скрипта» вставьте идентификатор скрипта библиотеки.
3. Нажмите «Поиск» .
4. Нажмите раскрывающийся список Версия и выберите версию библиотеки, которую хотите использовать.
5. Проверьте, соответствует ли имя «Идентификатор» по умолчанию тому, которое вы хотите использовать с этой библиотекой. Это имя, которое ваш скрипт использует для обращения к библиотеке. Например, если указать Test , то вы можете вызвать метод этой библиотеки следующим образом: Test.libraryMethod() .
6. Нажмите «Добавить» .

Использовать библиотеку

Используйте вашу включенную библиотеку так же, как и службу по умолчанию. Например, если Test — идентификатор вашей библиотеки, введите Test сразу после точки, чтобы увидеть список методов в библиотеке.

Справочную документацию по включенной библиотеке можно открыть, выполнив следующие действия:

Слева от редактора скриптов, рядом с именем библиотеки, нажмите Подробнее more_vert > Открыть в новой вкладке .

Удалить библиотеку

Слева от редактора скриптов, рядом с именем библиотеки, нажмите Дополнительно more_vert > Удалить > Удалить библиотеку .

Обновить библиотеку

Вы можете изменить версию библиотеки или обновить ее идентификатор.

1. В левой части редактора, в разделе «Библиотеки», щелкните название библиотеки.
2. Внесите изменения и нажмите «Сохранить» .

Создайте и поделитесь библиотекой

Чтобы использовать и поделиться своим проектом сценария как библиотекой, выполните следующие действия.

1. Создайте версионное развертывание вашего скрипта.
2. Предоставьте всем потенциальным пользователям библиотеки доступ хотя бы на уровень просмотра.
3. Предоставьте этим пользователям идентификатор скрипта, который можно найти на странице settings проекта .

Лучшие практики

Вот несколько рекомендаций, которым следует следовать при написании библиотеки:

1. Выберите осмысленное имя для вашего проекта, поскольку оно будет использоваться в качестве идентификатора по умолчанию при включении вашей библиотеки другими.
2. Если вы хотите, чтобы один или несколько методов вашего скрипта не были видны (или не могли быть использованы) пользователям вашей библиотеки, вы можете завершить имя метода символом подчёркивания. Например, myPrivateMethod_() .
3. Пользователям библиотеки видны только перечислимые глобальные свойства. Это включает в себя объявления функций, переменные, созданные вне функции с помощью var , и свойства, явно заданные для глобального объекта. Например, Object.defineProperty() с enumerable , установленным в false создаёт символ, который можно использовать в вашей библиотеке, но этот символ недоступен вашим пользователям.

4. Если вы хотите, чтобы пользователи вашей библиотеки могли использовать функцию автодополнения редактора скриптов и автоматически сгенерированную документацию, вам необходимо иметь документацию в стиле JSDoc для всех ваших функций. Вот пример:

   /**  * Raises a number to the given power, and returns the result.  *  * @param {number} base the number we're raising to a power  * @param {number} exp the exponent we're raising the base to  * @return {number} the result of the exponential calculation  */ function power(base, exp) { ... } 

Определение объема ресурсов

При работе с библиотеками существует два типа ресурсов: общие и необщие. Общий ресурс означает, что и библиотека, и включающий скрипт имеют встроенный доступ к одному и тому же экземпляру ресурса. На следующей диаграмме общий ресурс показан на примере свойств пользователя:

Необщий ресурс означает, что и библиотека, и включающий её скрипт имеют встроенный доступ только к своему экземпляру ресурса. Однако библиотека может предоставить доступ к своим необщим ресурсам, используя явные функции для работы с ними. Вот пример функции, которую можно включить в библиотеку для доступа к свойствам скрипта:

  function getLibraryProperty(key) {     const scriptProperties = PropertiesService.getScriptProperties();     return scriptProperties.getProperty(key);   } 

На следующей диаграмме показан необщий ресурс на примере свойств скрипта:

В этой таблице для справки перечислены общие и необщие ресурсы:

Ресурс	Общий*	Не общий**	Примечания
Замок			Один и тот же экземпляр виден всем, включая скрипты, созданные в библиотеке.
Свойства скрипта			Один и тот же экземпляр виден всем, включая скрипты, созданные в библиотеке.
Кэш			Один и тот же экземпляр виден всем, включая скрипты, созданные в библиотеке.
Триггеры			Простые триггеры, созданные в библиотеке, не активируются включающим скриптом.
ScriptApp
UiApp
Свойства пользователя
Регистратор и стенограмма выполнения
Сайты, листы и другие контейнеры			Вызов getActive() возвращает контейнер включаемого скрипта.
MailApp и GmailApp
* Это означает, что библиотека не имеет собственного экземпляра функции/ресурса и вместо этого использует тот, который создан скриптом, вызвавшим его. ** Это означает, что библиотека имеет свой собственный экземпляр ресурса/функции и что все скрипты, использующие библиотеку, совместно используют и имеют доступ к этому же экземпляру.

Тестирование библиотеки

Для тестирования вашей библиотеки используйте развёртывание head. Развёртывание head может использовать любой, у кого есть доступ к скрипту на уровне редактора.

Отладка библиотеки

При использовании отладчика в проекте, включающем библиотеку, вы можете войти в функцию этой библиотеки. Код отображается в отладчике в режиме «только просмотр» и в нужной версии.