Библиотеки

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

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

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

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

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

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

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

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

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

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

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

Удаление библиотеки

Слева от редактора скриптов рядом с именем библиотеки нажмите «Еще > «Удалить» > «Удалить библиотеку» .

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

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

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

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

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

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

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

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

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

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.

Вам все равно потребуется сохранить хотя бы одну версию библиотеки.

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

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