Rozszerzanie możliwości Dokumentów Google

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

Podstawy

Interakcje między Apps Script a Dokumentami Google mogą odbywać się na 2 sposoby: dowolny skrypt może tworzyć lub modyfikować dokumenty, jeśli użytkownik skryptu ma odpowiednie uprawnienia do tych dokumentów. Skrypt może też być powiązany z dokumentem, co daje mu specjalne możliwości modyfikowania interfejsu użytkownika lub reagowania na otwarcie dokumentu. Aby utworzyć skrypt powiązany z kontenerem w Dokumentach Google, kliknij Rozszerzenia > Apps Script.

W obu przypadkach możesz łatwo pracować z dokumentem Dokumentów Google za pomocą usługi Dokumentów w Apps Script, jak pokazuje poniższy przykład.

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

Powyższy skrypt tworzy nowy dokument na Dysku Google użytkownika, a następnie pobiera kartę o identyfikatorze t.0 (domyślna pierwsza karta), wstawia akapit zawierający ten sam tekst co nazwa dokumentu, nadaje mu styl nagłówka i dodaje tabelę na podstawie wartości w macierzy dwuwymiarowej. Ten skrypt może równie łatwo wprowadzać te zmiany w dotychczasowym dokumencie, zastępując wywołanie DocumentApp.create() DocumentApp.openById() lub openByUrl(). W przypadku skryptów utworzonych w dokumencie (powiązanych z kontenerem) użyj właściwości DocumentApp.getActiveDocument() i Document.getActiveTab().

Struktura dokumentu

Z punktu widzenia Apps Script dokument Dokumenty Google ma strukturę podobną do dokumentu HTML, czyli składa się z co najmniej jednego obiektu Tab, który zawiera elementy (takie jak Paragraph lub Table), które często zawierają inne elementy. Większość skryptów modyfikujących dokument w Dokumentach Google zaczyna się od wywołania getTab() oraz asDocumentTab() przed znakiem getBody(), bo Body to podstawowy element, który zawiera wszystkie pozostałe elementy na karcie poza HeaderSection, FooterSection oraz Footnotes.

Istnieją jednak reguły określające, które typy elementów mogą zawierać inne typy. Ponadto usługa Document Service w Apps Script może wstawiać do innych elementów tylko określone typy elementów. Drzewo poniżej pokazuje, które elementy mogą zawierać dany typ elementu.

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

Zastępowanie tekstu

Apps Script jest często używany do zastępowania tekstu w Dokumentach Google. Załóżmy, że masz arkusz kalkulacyjny z informacjami o klientach i chcesz wygenerować spersonalizowane dokumenty Google Docs dla każdego z nich. (ta operacja jest często nazywana scalaniem wiadomości).

Tekst można zastępować na wiele sposobów, ale najprostsza jest metoda replaceText(), jak pokazano w przykładzie poniżej. replaceText obsługuje większość funkcji wyrażeń regularnych w JavaScript. Pierwsza funkcja poniżej dodaje kilka wierszy tekstu zastępczego do Dokumentów Google. W rzeczywistości prawdopodobnie wpiszesz te teksty samodzielnie. Druga funkcja zastępuje zmienne zastępcze właściwościami zdefiniowanymi w obiekcie client.

Pamiętaj, że obie te funkcje korzystają z metod getActiveDocument() i getActiveTab(), które mają zastosowanie tylko do skryptów utworzonych w dokumencie Dokumentów Google. W samodzielnym skrypcie użyj zamiast tego metod DocumentApp.create(), openById() lub openByUrl() w połączeniu z metodą Document.getTab().

Dodawanie obiektów zastępczych

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

Zastąp zmienne

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

Menu i interfejsy niestandardowe

Dokumenty Google możesz dostosować, dodając menu, okna dialogowe i paski boczne. Pamiętaj jednak, że skrypt może wchodzić w interakcję z interfejsem tylko w przypadku bieżącej instancji otwartego dokumentu i tylko wtedy, gdy skrypt jest powiązany z tym dokumentem.

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ć interfejs niestandardowy jako dodatek, postępuj zgodnie z przepisami zawartymi w przewodniku po stylach, 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 zainstalować ze sklepu z dodatkami do Dokumentów Google. Gdy utworzysz skrypt do Dokumentów Google i chcesz go udostępnić światu, możesz użyć Apps Script, aby opublikować 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 samouczkiem dotyczącym tworzenia dodatków do Dokumentów.

Reguły

Skrypty powiązane z dokumentem Google Docs mogą używać prostego wyzwalacza, aby reagować na onOpen zdarzenie dokumentu, które występuje, gdy użytkownik z dostępem do edycji 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.