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

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

Основы

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

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

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var body = doc.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 Диске пользователя, затем вставляет абзац, содержащий тот же текст, что и имя документа, оформляет этот абзац как заголовок и добавляет таблицу на основе значений в двумерном массиве. Сценарий может так же легко внести эти изменения в существующий документ, заменив вызов DocumentApp.create() на DocumentApp.openById() или openByUrl() . Для сценариев, созданных внутри документа (привязанных к контейнеру), используйте DocumentApp.getActiveDocument() .

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

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

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

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

  • УравнениеСимвол
  • Текст
  • Сноска
  • ГоризонтальноеПравило
  • Встроенное рисование
  • InlineImage
  • Разрыв страницы
  • Текст
  • Параграф
  • Уравнение
  • УравнениеФункция
  • УравнениеФункция ...
  • УравнениеФункцияАргументРазделитель
  • УравнениеСимвол
  • Текст
  • УравнениеСимвол
  • Текст
  • Сноска
  • ГоризонтальноеПравило
  • Встроенное рисование
  • InlineImage
  • Разрыв страницы
  • Текст
  • Стол
  • ТаблицаРоу
  • Таблеселл
  • Параграф ...
  • Пункт списка ...
  • Стол ...
  • Оглавление
  • Параграф ...
  • Пункт списка ...
  • Стол ...
  • Раздел заголовка
  • Пункт списка
  • ГоризонтальноеПравило
  • Встроенное рисование
  • InlineImage
  • Текст
  • UnsupportedElement (номер страницы и т. д.)
  • Параграф
  • ГоризонтальноеПравило
  • Встроенное рисование
  • InlineImage
  • Текст
  • UnsupportedElement (номер страницы и т. д.)
  • Стол
  • ТаблицаРоу
  • Таблеселл
  • Параграф ...
  • Пункт списка ...
  • Стол ...
  • Нижний колонтитул
  • Пункт списка
  • ГоризонтальноеПравило
  • Встроенное рисование
  • InlineImage
  • Текст
  • UnsupportedElement (номер страницы и т. д.)
  • Параграф
  • ГоризонтальноеПравило
  • Встроенное рисование
  • InlineImage
  • Текст
  • UnsupportedElement (номер страницы и т. д.)
  • Стол
  • ТаблицаРоу
  • Таблеселл
  • Параграф ...
  • Пункт списка ...
  • Стол ...
  • СноскаРаздел
  • Пункт списка
  • ГоризонтальноеПравило
  • Текст
  • Параграф
  • ГоризонтальноеПравило
  • Текст
  • Замена текста

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

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

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

    Добавьте несколько заполнителей

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

    Замените заполнители

    function searchAndReplace() {
      var body = DocumentApp.getActiveDocument()
          .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, требующие авторизации.