Библиотеки

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

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

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

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

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

1. В левой части редактора скриптов приложений рядом с пунктом «Библиотеки» нажмите « add библиотеку».
2. В поле «Идентификатор сценария» вставьте идентификатор сценария библиотеки.
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) {
    return ScriptProperties.getProperty(key);
  }

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

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

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

Протестировать библиотеку

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

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

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