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

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

Основы

Apps Script может взаимодействовать с Docs двумя основными способами: любой скрипт может создавать или изменять документ, если у пользователя, создавшего скрипт, есть соответствующие разрешения для этого документа, а также скрипт может быть привязан к документу, что дает скрипту особые возможности для изменения пользовательского интерфейса или реагирования на открытие документа. Чтобы создать скрипт, привязанный к контейнеру, из Docs, щелкните Расширения > Apps Script .

В любом случае, вы можете взаимодействовать с документом 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 Диске пользователя, затем извлекает вкладку с ID t.0 (первая вкладка по умолчанию), вставляет абзац, содержащий тот же текст, что и имя документа, оформляет этот абзац как заголовок и добавляет таблицу на основе значений двумерного массива. Скрипт также может вносить эти изменения в существующий документ, заменив вызов DocumentApp.create на DocumentApp.openById или openByUrl . Для скриптов, созданных внутри документа (привязанных к контейнеру), используйте DocumentApp.getActiveDocument и Document.getActiveTab .

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

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

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

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

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

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

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

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

Обе эти функции используют методы getActiveDocument и getActiveTab , которые применяются только к скриптам, созданным внутри документа 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);
}

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

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

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

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

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

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

Триггеры

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

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