Библиотеки

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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
* Это означает, что библиотека не имеет собственного экземпляра функции/ресурса, а использует тот, который был создан скриптом, вызвавшим его. **Это означает, что библиотека имеет собственный экземпляр ресурса/функции, и все скрипты, использующие библиотеку, совместно используют этот же экземпляр и имеют к нему доступ.**

Протестируйте библиотеку

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

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

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

Для отладки кода библиотеки откройте проект скрипта библиотеки в редакторе Apps Script и запускайте функции в режиме отладки оттуда.