Библиотека — это скриптовый проект, функции которого можно повторно использовать в других скриптах.
Скрипт, использующий библиотеку, работает не так быстро , как если бы весь код был сосредоточен в одном проекте. Хотя библиотеки могут упростить разработку и сопровождение, используйте их экономно в проектах, где скорость имеет решающее значение. Из-за этой проблемы использование библиотек в дополнениях Google Workspace следует ограничить.
Получите доступ к библиотеке
Для включения библиотеки в ваш проект вам необходим как минимум доступ на уровне просмотра. Если вы не являетесь автором библиотеки, которую хотите включить, свяжитесь с автором и запросите доступ.
Вам потребуется идентификатор скрипта библиотеки, которую вы хотите включить. Когда у вас появится доступ к библиотеке, найдите идентификатор скрипта на странице проекта .
Добавьте библиотеку в свой скриптовый проект.
- В левой части редактора Apps Script, рядом с пунктом «Библиотеки», нажмите « библиотеку».
- В поле "Идентификатор скрипта" вставьте идентификатор скрипта библиотеки.
- Нажмите «Поиск» .
- Щелкните раскрывающийся список «Версия» и выберите версию библиотеки, которую хотите использовать.
- Проверьте, совпадает ли имя идентификатора по умолчанию с тем, которое вы хотите использовать для этой библиотеки. Это имя, которое ваш скрипт будет использовать для ссылки на библиотеку. Например, если вы установите его как
Test, то вызовите метод этой библиотеки следующим образом:Test.libraryMethod. - Нажмите «Добавить» .
Используйте библиотеку
Используйте включенную в библиотеку так же, как и стандартную службу. Например, если Test — идентификатор вашей библиотеки, введите Test сразу после точки, чтобы увидеть список методов в библиотеке.
Чтобы открыть справочную документацию для включенной библиотеки, выполните следующие действия:
В левой части редактора скриптов, рядом с названием библиотеки, нажмите « > «Открыть в новой вкладке» .
Удалить библиотеку
В левой части редактора скриптов, рядом с названием библиотеки, нажмите More > Remove > Remove library .
Если библиотека удалена автором, вам все равно необходимо удалить ее из списка включенных библиотек.
Обновить библиотеку
Измените версию библиотеки или обновите её идентификатор.
- В левой части редактора, в разделе «Библиотеки», щелкните название библиотеки.
- Внесите изменения и нажмите «Сохранить» .
Создайте и поделитесь библиотекой
Чтобы использовать и делиться своим скриптовым проектом в качестве библиотеки, выполните следующие шаги:
- Создайте версионированное развертывание вашего скрипта.
- Предоставьте всем потенциальным пользователям библиотеки как минимум доступ на уровне просмотра.
- Присвойте этим пользователям идентификатор скрипта, который можно найти на странице проекта .
Передовые методы
Вот несколько рекомендаций, которым следует следовать при создании библиотеки:
- Выберите осмысленное название для своего проекта, поскольку оно будет использоваться в качестве идентификатора по умолчанию, когда ваша библиотека будет включена другими проектами.
- Чтобы один или несколько методов вашего скрипта были невидимы (и недоступны) для пользователей вашей библиотеки, завершите имя метода подчеркиванием. Например,
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) {
const scriptProperties = PropertiesService.getScriptProperties();
return scriptProperties.getProperty(key);
}
На следующей диаграмме на примере свойств скрипта показан неразделяемый ресурс:
В этой таблице для вашего удобства перечислены общие и необщие ресурсы:
| Ресурс | Совместно* | Не для общего пользования** | Примечания |
|---|---|---|---|
| Замок |  | Один и тот же экземпляр виден всем, включая скрипты, созданные в библиотеке. | |
| Свойства скрипта | | Один и тот же экземпляр виден всем, включая скрипты, созданные в библиотеке. | |
| Кэш | | Один и тот же экземпляр виден всем, включая скрипты, созданные в библиотеке. | |
| Триггеры | | Простые триггеры, созданные в библиотеке, не срабатывают при включении скрипта. | |
| ScriptApp | | ||
| UiApp | | ||
| Свойства пользователя | | ||
| Журнал событий и стенограмма выполнения | | ||
| Сайты, листы и другие контейнеры | | Вызов функции getActive возвращает контейнер включаемого скрипта. | |
| MailApp и GmailApp | | ||
| * Это означает, что библиотека не имеет собственного экземпляра функции/ресурса, а использует тот, который был создан скриптом, вызвавшим его. **Это означает, что библиотека имеет собственный экземпляр ресурса/функции, и все скрипты, использующие библиотеку, совместно используют этот же экземпляр и имеют к нему доступ.** | |||
Протестируйте библиотеку
Для тестирования вашей библиотеки используйте основную ветку развертывания. Любой, кто имеет доступ к скрипту на уровне редактора, может использовать основную ветку развертывания.
Вам по-прежнему необходимо сохранить хотя бы одну версию библиотеки.
Отладка библиотеки
При отладке скрипта, включающего библиотеку, вы не можете пошагово выполнять код библиотеки или устанавливать в нем точки останова. Если вы попытаетесь пошагово выполнить код функции библиотеки в режиме отладки, отладчик пропустит эту функцию и перейдет к следующей строке вызывающего скрипта.
Использование HEAD (режим разработки) для версии библиотеки не позволяет пошагово просматривать содержимое библиотеки или устанавливать точки останова внутри неё.
Для отладки кода библиотеки используйте один из следующих методов:
- Отладка из проекта библиотеки : Откройте проект скрипта библиотеки в редакторе Apps Script. Чтобы протестировать функции библиотеки с определенными аргументами, создайте временную «тестовую» функцию в проекте библиотеки, которая вызывает функции вашей библиотеки, а затем запустите эту тестовую функцию в режиме отладки.
- Ведение журналов : Используйте
console.log()внутри функций вашей библиотеки для вывода информации в журналы выполнения. Когда библиотека вызывается другим скриптом, эти записи отображаются в журналах выполнения вызывающего скрипта.