Библиотека — это проект сценария, функции которого можно повторно использовать в других сценариях.
Получите доступ к библиотеке
Чтобы включить библиотеку в свой проект, вы должны иметь к ней доступ как минимум на уровне представления. Если вы не являетесь автором библиотеки, которую хотите включить, свяжитесь с автором и запросите доступ.
Вам понадобится идентификатор сценария библиотеки, которую вы хотите включить. Если у вас есть доступ к библиотеке, вы можете найти идентификатор сценария на странице
настроек проекта .Добавьте библиотеку в свой проект скрипта
- В левой части редактора Apps Script рядом с пунктом «Библиотеки» нажмите « библиотеку».
- В поле «Идентификатор сценария» вставьте идентификатор сценария библиотеки.
- Нажмите «Искать» .
- Щелкните раскрывающийся список «Версия» и выберите версию библиотеки, которую вы хотите использовать.
- Проверьте, является ли имя «Идентификатора» по умолчанию тем, которое вы хотите использовать с этой библиотекой. Это имя, которое ваш скрипт использует для обращения к библиотеке. Например, если вы установите для него значение
Test
, вы сможете вызвать метод этой библиотеки следующим образом:Test.libraryMethod()
. - Нажмите Добавить .
Используйте библиотеку
Используйте включенную библиотеку так же, как и службу по умолчанию. Например, если Test
является идентификатором вашей библиотеки, сразу введите Test
и поставьте точку, чтобы просмотреть список методов в библиотеке.
Справочную документацию по включенной библиотеке можно открыть, выполнив следующие действия:
Слева от редактора скриптов рядом с названием библиотеки нажмите «Еще
> «Открыть в новой вкладке» .Удаление библиотеки
Слева от редактора скриптов рядом с именем библиотеки нажмите «Еще
> «Удалить» > «Удалить библиотеку» .Обновить библиотеку
Вы можете изменить версию библиотеки или обновить ее идентификатор.
- В левой части редактора в разделе «Библиотеки» щелкните название библиотеки.
- Внесите изменения и нажмите «Сохранить» .
Создайте и поделитесь библиотекой
Чтобы использовать и публиковать проект сценария в качестве библиотеки, выполните следующие действия.
- Создайте версионное развертывание вашего сценария.
- Предоставьте доступ хотя бы на уровне просмотра всем потенциальным пользователям библиотеки.
- Дайте этим пользователям идентификатор сценария, который можно найти на странице параметров проекта .
Лучшие практики
Вот несколько рекомендаций, которым следует следовать при написании библиотеки:
- Выберите осмысленное имя для своего проекта, поскольку оно используется в качестве идентификатора по умолчанию, когда ваша библиотека включается другими.
- Если вы хотите, чтобы один или несколько методов вашего скрипта были невидимы (и недоступны для использования) пользователями вашей библиотеки, вы можете закончить имя метода подчеркиванием. Например,
myPrivateMethod_()
. - Пользователям библиотеки видны только перечисляемые глобальные свойства. Сюда входят объявления функций, переменные, созданные вне функции с помощью
var
, и свойства, явно заданные для глобального объекта. Например,Object.defineProperty()
сenumerable
значениемfalse
создает символ, который вы можете использовать в своей библиотеке, но этот символ недоступен вашим пользователям. Если вы хотите, чтобы пользователи вашей библиотеки могли использовать автозаполнение редактора сценариев и автоматически создаваемую документацию, у вас должна быть документация в стиле 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 | |||
* Это означает, что библиотека не имеет собственного экземпляра функции/ресурса и вместо этого использует экземпляр, созданный сценарием, который ее вызвал. ** Это означает, что библиотека имеет собственный экземпляр ресурса/функции и что все сценарии, использующие библиотеку, имеют общий доступ и доступ к одному и тому же экземпляру. |
Тестирование библиотеки
Чтобы протестировать свою библиотеку, используйте развертывание head. Любой, у кого есть доступ к сценарию на уровне редактора, может использовать развертывание head.
Отладка библиотеки
Когда вы используете отладчик в проекте, включающем библиотеку, вы можете войти в функцию включенной библиотеки. Код отображается в отладчике в режиме только для просмотра и в правильной версии.