Библиотеки

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

Скрипт, использующий библиотеку, работает не так быстро , как если бы весь код был сосредоточен в одном проекте. Хотя библиотеки могут упростить разработку и сопровождение, используйте их экономно в проектах, где скорость имеет решающее значение. Из-за этой проблемы использование библиотек в дополнениях Google Workspace следует ограничить.

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

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

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

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

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

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

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

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

В левой части редактора скриптов, рядом с названием библиотеки, нажмите « > «Открыть в новой вкладке» .

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

В левой части редактора скриптов, рядом с названием библиотеки, нажмите More > Remove > Remove library .

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

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

Измените версию библиотеки или обновите её идентификатор.

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

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

Чтобы использовать и делиться своим скриптовым проектом в качестве библиотеки, выполните следующие шаги:

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

Передовые методы

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

  1. Выберите осмысленное название для своего проекта, поскольку оно будет использоваться в качестве идентификатора по умолчанию, когда ваша библиотека будет включена другими проектами.
  2. Чтобы один или несколько методов вашего скрипта были невидимы (и недоступны) для пользователей вашей библиотеки, завершите имя метода подчеркиванием. Например, myPrivateMethod_ .
  3. Only enumerable global properties are visible to library users. This includes function declarations, variables created outside a function with var , and properties explicitly set on the global object. For example, Object.defineProperty() with enumerable set to false creates a symbol you can use in your library, but this symbol isn't accessible by your users.

  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 (режим разработки) для версии библиотеки не позволяет пошагово просматривать содержимое библиотеки или устанавливать точки останова внутри неё.

Для отладки кода библиотеки используйте один из следующих методов:

  • Debug from the library project : Open the library script project in the Apps Script editor. To test library functions with specific arguments, create a temporary "test" function within the library project that calls your library functions, then run that test function in debug mode.
  • Ведение журналов : Используйте console.log() внутри функций вашей библиотеки для вывода информации в журналы выполнения. Когда библиотека вызывается другим скриптом, эти записи отображаются в журналах выполнения вызывающего скрипта.