Rozszerzanie Dokumentów Google

Google Apps Script umożliwia programowe tworzenie i modyfikowanie Dokumentów Google, a także dostosowywanie interfejsu użytkownika za pomocą nowych menu, okien dialogowych i paska bocznego.

Podstawy

Apps Script może wchodzić w interakcje z Dokumentami Google na 2 sposoby: za pomocą dowolnego skryptu można tworzyć lub modyfikować dokument, jeśli użytkownik skryptu ma odpowiednie uprawnienia. Poza tym skrypt może być powiązany z dokumentem, co daje skryptowi specjalne uprawnienia do zmieniania 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żna łatwo pracować z dokumentem Google za pomocą usługi Document Service w Apps Script, co pokazuje poniższy przykład.

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 taki sam tekst jak nazwa dokumentu, dodaje styl tego akapitu jako nagłówek i dodaje tabelę w oparciu o wartości zawarte w tablicy dwuwymiarowej. Skrypt może równie łatwo wprowadzić te zmiany w istniejącym dokumencie, zastępując wywołanie DocumentApp.create() poleceniem DocumentApp.openById() lub openByUrl(). W przypadku skryptów utworzonych w dokumencie (powiązanych z kontenerem) użyj właściwości DocumentApp.getActiveDocument().

Struktura dokumentu

Z perspektywy Apps Script dokument Google ma strukturę podobną do dokumentu HTML, co oznacza, że składa się z elementów (takich jak 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 elementem głównym, który zawiera wszystkie pozostałe elementy oprócz HeaderSection, FooterSection i innych elementów Footnotes.

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

Elementy wyróżnione pogrubieniem można wstawiać, a elementy inne niż pogrubione można edytować tylko w miejscu.

Zastępowanie tekstu

Apps Script często używa się do zastępowania tekstu w Dokumentach Google. Załóżmy, że masz arkusz kalkulacyjny z informacjami o kliencie i chcesz wygenerować spersonalizowane Dokumenty Google dla każdego klienta. (Ten rodzaj operacji jest często nazywany scalaniem poczty).

Tekst można zastąpić na wiele sposobów, ale najprostszy to metoda replaceText() widoczna w poniższym przykładzie. replaceText obsługuje większość funkcji wyrażeń regularnych JavaScriptu. Pierwsza z poniższych funkcji dodaje kilka wierszy tekstu zastępczego do Dokumentów Google. W świecie rzeczywistym korzystniej jest wpisać symbole zastępcze w dokumencie. Druga funkcja zastępuje symbole zastępcze właściwościami określonymi w obiekcie client.

Pamiętaj, że obie te funkcje korzystają z metody getActiveDocument(), która ma zastosowanie tylko do skryptów utworzonych w pliku Dokumentów Google. W samodzielnym skrypcie użyj 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ępowanie zmiennych

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 użytkownika

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 bieżącym wystąpieniu otwartego dokumentu, gdy jest z nim powiązany.

Zobacz, jak dodawać do Dokumentów Google niestandardowe menu i okna dialogowe. Więcej informacji o tworzeniu niestandardowych interfejsów dla okna dialogowego lub paska bocznego znajdziesz w przewodniku po usłudze HTML. Jeśli zamierzasz opublikować interfejs niestandardowy 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 zainstalować ze sklepu z dodatkami do Dokumentów Google. Jeśli masz stworzony skrypt do Dokumentów Google i chcesz go udostępnić całemu światu, Apps Script umożliwia opublikowanie skryptu jako dodatku, dzięki czemu inni użytkownicy będą mogli go zainstalować ze sklepu z dodatkami.

Aby dowiedzieć się, jak utworzyć dodatek do Dokumentów Google, przeczytaj krótkie wprowadzenie do tworzenia dodatków do Dokumentów.

Aktywatory

Skrypty powiązane z Dokumentem Google mogą używać prostego wyzwalacza do odpowiadania na zdarzenie dokumentu onOpen, które ma miejsce, gdy użytkownik z uprawnieniami do edycji otwiera dokument w Dokumentach Google.

Aby skonfigurować aktywator, po prostu napisz funkcję o nazwie onOpen(). Przykład tego aktywatora znajdziesz w artykule Menu niestandardowe w Google Workspace. Prosty aktywator przydaje się do dodawania menu, ale nie może używać usług Apps Script wymagających autoryzacji.