Расширение Документов Google

Google Apps Script позволяет программно создавать и изменять Документы Google, а также настраивать пользовательский интерфейс с помощью новых меню, диалоговых окон и боковых панелей.

Основы

Apps Script может взаимодействовать с Документами Google двумя основными способами: любой сценарий может создавать или изменять документ, если у пользователя сценария есть соответствующие разрешения для документа, а сценарий также можно привязать к документу, что дает сценарию особые возможности для изменения. пользовательский интерфейс или отвечать при открытии документа. Чтобы создать скрипт, привязанный к контейнеру, в Документах Google, нажмите «Расширения» > «Скрипт приложений» .

В любом случае взаимодействовать с документом Google Docs просто через службу документов Apps Script, как показано в следующем примере.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

Приведенный выше сценарий создает новый документ на Google Диске пользователя, затем извлекает вкладку с идентификатором t.0 (первая вкладка по умолчанию), вставляет абзац, содержащий тот же текст, что и имя документа, оформляет этот абзац как заголовок и добавляет таблицу на основе значений двумерного массива. Сценарий может так же легко внести эти изменения в существующий документ, заменив вызов DocumentApp.create() на DocumentApp.openById() или openByUrl() . Для сценариев, созданных внутри документа (привязанных к контейнеру), используйте DocumentApp.getActiveDocument() и Document.getActiveTab() .

Структура документа

С точки зрения Apps Script документ Google Docs имеет структуру, очень похожую на документ HTML, то есть документ состоит из одного или нескольких объектов Tab , каждый из которых содержит элементы (например, Paragraph или Table ), которые часто содержат другие элементы. Большинство сценариев, изменяющих документ Google Docs, начинаются с вызова getTab() и asDocumentTab() за которым следует getBody() , поскольку Body является основным элементом, который содержит все остальные элементы на вкладке, за исключением HeaderSection , FooterSection и любых других элементов. Footnotes .

Однако существуют правила относительно того, какие типы элементов могут содержать другие типы. Более того, служба документов в Apps Script может вставлять только определенные типы элементов в другие элементы. В дереве ниже показано, какие элементы могут содержаться в элементе определенного типа.

Элементы, выделенные жирным шрифтом, можно вставлять; элементами, не выделенными жирным шрифтом, можно манипулировать только на месте.

• Документ
• Вкладка
• ДокументTab
• Тело
• ListItem
• Уравнение
• УравнениеФункция
• УравнениеФункция ...
• УравнениеФункцияАргументРазделитель
• УравнениеСимвол
• Текст

Замена текста

Apps Script часто используется для замены текста в Документах Google. Допустим, у вас есть электронная таблица, полная информации о клиентах, и вы хотите создать персонализированные документы Google для каждого клиента. (Этот тип операции часто называют слиянием почты.)

Существует много способов замены текста, но самым простым является метод replaceText() показанный в примере ниже. replaceText поддерживает большинство функций регулярных выражений JavaScript. Первая функция ниже добавляет несколько строк текста-заполнителя в Документы Google; в реальном мире вы, скорее всего, введете заполнители в документ самостоятельно. Вторая функция заменяет заполнители свойствами, определенными в client объекте.

Обратите внимание, что обе эти функции используют методы getActiveDocument() и getActiveTab() , которые применяются только к сценариям, созданным внутри документа Google Docs; в автономном скрипте вместо этого используйте DocumentApp.create() , openById() или openByUrl() в сочетании с Document.getTab() .

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

Пользовательские меню и пользовательские интерфейсы

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

Узнайте, как добавить собственные меню и диалоговые окна в Документы Google. Чтобы узнать больше о создании пользовательских интерфейсов для диалогового окна или боковой панели, см. руководство по HTML Service . Если вы планируете опубликовать свой собственный интерфейс как часть надстройки , следуйте руководству по стилю, чтобы обеспечить соответствие стилю и макету редактора Документов Google.

Дополнения для Документов Google

Дополнения запускаются внутри Документов Google и могут быть установлены из магазина дополнений Документов Google. Если вы разработали сценарий для Документов Google и хотите поделиться им со всем миром, Apps Script позволяет опубликовать его как надстройку, чтобы другие пользователи могли установить его из магазина дополнений.

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

Триггеры

Скрипты, привязанные к Документу Google, могут использовать простой триггер для ответа на событие onOpen документа, которое происходит всякий раз, когда пользователь, имеющий доступ к редактированию документа, открывает его в Документах Google.

Чтобы настроить триггер, просто напишите функцию onOpen() . Пример этого триггера см. в разделе Пользовательские меню в Google Workspace . Хотя простой триггер полезен для добавления меню, он не может использовать службы Apps Script, требующие авторизации.