Rozszerzanie możliwości Dokumentów Google

Skrypt Google Apps Script umożliwia programowe tworzenie i modyfikowanie Dokumentów Google, a także dostosowywanie interfejsu za pomocą nowych menu, okien dialogowych i pasków bocznych.

Podstawy

Apps Script może wchodzić w interakcje z Dokumentami Google na 2 ogólne sposoby: każdy skrypt może utworzyć lub zmodyfikować dokument, jeśli użytkownik ma do niego odpowiednie uprawnienia. Skrypt można też powiązać z dokumentem, co daje mu specjalne uprawnienia do modyfikowania interfejsu użytkownika lub reagowania po otwarciu dokumentu. Aby w Dokumentach Google utworzyć skrypt powiązany z kontenerem, kliknij Rozszerzenia > Apps Script.

W obu przypadkach można łatwo korzystać z dokumentu Google za pomocą usługi Dokumenty w Apps Script, jak pokazano w poniższym przykładzie.

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);
}

Powyższy skrypt tworzy nowy dokument na Dysku Google użytkownika, a następnie wstawia akapit zawierający ten sam tekst co nazwa dokumentu, styl ten akapit jako nagłówek i doda tabelę na podstawie wartości w dwuwymiarowej tablicy. Skrypt może równie łatwo wprowadzić te zmiany w istniejącym dokumencie, zastępując wywołanie DocumentApp.create() DocumentApp.openById() lub openByUrl(). W przypadku skryptów utworzonych w dokumencie (powiązanym z kontenerem) użyj DocumentApp.getActiveDocument().

Struktura dokumentu

Z punktu widzenia Apps Script widać, że dokument Google ma strukturę podobną do dokumentu HTML, czyli dokument Google złożony z elementów (np. Paragraph lub Table), które często zawierają inne elementy. Większość skryptów modyfikujących dokument Google zaczyna się od wywołania getBody(), ponieważ Body jest głównym elementem, który zawiera wszystkie pozostałe elementy z wyjątkiem elementów HeaderSection, FooterSection i Footnotes.

Istnieją jednak reguły, które określają, które typy elementów mogą zawierać inne typy. Poza tym usługa Document Service w Apps Script może wstawiać tylko niektóre elementy. Drzewo poniżej pokazuje, które elementy mogą zawierać elementy określonego typu.

Elementy pogrubione można wstawiać, a elementy, które nie są pogrubione, można manipulować tylko w ich miejscach.

Zastępowanie tekstu

Skrypt za pomocą Apps Script jest często używany do zastępowania tekstu w Dokumentach Google. Załóżmy, że masz arkusz kalkulacyjny zawierający informacje o kliencie i chcesz dla niego wygenerować spersonalizowane Dokumenty Google. Ten typ operacji jest często nazywany kreatora e-maili.

Istnieje wiele sposobów zastępowania tekstu, ale najprostszą z nich jest metoda replaceText() opisana w poniższym przykładzie. replaceText obsługuje większość funkcji JavaScriptu związanych z wyrażeniami regularnymi. Pierwsza z poniższych funkcji dodaje kilka wierszy tekstu zastępczego do Dokumentów Google. W świecie rzeczywistym te symbole zastępcze należy wpisać samodzielnie. Druga funkcja zastępuje zmienne właściwościami zdefiniowanymi w obiekcie client.

Pamiętaj, że obie te funkcje korzystają z metody getActiveDocument(), która ma zastosowanie tylko do skryptów utworzonych w Dokumentach Google. W samodzielnym skrypcie użyj metody DocumentApp.create(), openById() lub openByUrl().

Dodaj obiekty zastępcze

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

Zastąp zmienne

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);
}

Niestandardowe menu i interfejsy

Dokumenty Google można dostosowywać, dodając menu, okna dialogowe i paski boczne. Pamiętaj jednak, że skrypt może współdziałać z interfejsem tylko w bieżącej instancji otwartego dokumentu i tylko wtedy, gdy skrypt jest z nim powiązany.

Dowiedz się, jak dodawać niestandardowe menu i okna dialogowe do Dokumentów Google. Więcej informacji o tworzeniu niestandardowych interfejsów dla okna dialogowego lub paska bocznego znajdziesz w przewodniku po usłudze HTML. Jeśli planujesz opublikować własny interfejs jako część dodatku, postępuj zgodnie ze wskazówkami dotyczącymi stylu, aby zachować spójność ze stylem i układem edytora Dokumentów Google.

Dodatki do Dokumentów Google

Dodatki działają w Dokumentach Google i można je instalować ze sklepu z dodatkami do tej usługi. Gdy utworzysz skrypt do Dokumentów Google i chcesz go udostępnić światu, możesz użyć Apps Script, aby publish go jako dodatek, aby inni użytkownicy mogli go zainstalować ze sklepu z dodatkami.

Aby dowiedzieć się, jak utworzyć dodatek do Dokumentów Google, zapoznaj się z krótkim wprowadzeniem do tworzenia dodatków do Dokumentów.

Aktywatory

Skrypty powiązane z dokumentem Google mogą używać prostego wyzwalacza w celu reagowania na onOpen zdarzenie dokumentu, które występuje, gdy użytkownik z uprawnieniami do edycji tego dokumentu otworzy go w Dokumentach Google.

Aby skonfigurować aktywator, wystarczy napisać funkcję o nazwie onOpen(). Przykład tego aktywatora znajdziesz w artykule Menu niestandardowe w Google Workspace. Mimo że prosta reguła jest przydatna przy dodawaniu menu, nie może korzystać z żadnych usług Apps Script wymagających autoryzacji.