Rozszerzanie możliwości Dokumentów Google

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

Podstawy

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

W obu przypadkach można z łatwością pracować z dokumentem Google przy użyciu 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 z tym samym tekstem co nazwa dokumentu, styl, który ten akapit jest nagłówkiem, i dołącza 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() wartością DocumentApp.openById() lub openByUrl(). W przypadku skryptów utworzonych w dokumencie (powiązanym z kontenerem) użyj właściwości DocumentApp.getActiveDocument().

Struktura dokumentu

Z perspektywy Apps Script dokument Google ma strukturę podobną do dokumentu HTML, czyli składa się z elementów (takich jak Paragraph lub Table), które często zawierają także 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 Footnotes.

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

Elementy wyróżnione pogrubieniem można wstawiać; można tylko manipulować elementami, które nie są pogrubione.

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 kliencie i chcesz dla każdego klienta wygenerować spersonalizowane Dokumenty Google. (Ten typ operacji jest często nazywany kreatora e-maili).

Tekst można zastąpić na wiele sposobów. najprostszym z nich jest metoda replaceText() widoczna w poniższym przykładzie. replaceText obsługuje większość funkcji wyrażeń regularnych JavaScriptu. Pierwsza funkcja poniżej dodaje kilka wierszy tekstu zastępczego w Dokumentach Google. W świecie rzeczywistym korzystniej jest wpisać symbole zastępcze w dokumencie. Druga funkcja zastępuje obiekty 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 dokumencie Google. W osobnym skrypcie możesz użyć 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ępowanie obiektów zastępczych

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

Możesz dostosować Dokumenty Google, dodając menu, okna dialogowe i paski boczne. Pamiętaj jednak, że skrypt może wchodzić w interakcje z interfejsem tylko w przypadku bieżącego wystąpienia otwartego dokumentu i tylko wtedy, 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 okna dialogowego lub paska bocznego znajdziesz w przewodniku po usłudze HTML. Jeśli zamierzasz opublikować niestandardowy interfejs jako dodatek, 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 skrypt do Dokumentów Google i chcesz się nim podzielić ze światem, możesz 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, przeczytaj krótkie wprowadzenie do tworzenia dodatków do Dokumentów.

Aktywatory

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

Aby skonfigurować aktywator, wystarczy napisać funkcję o nazwie onOpen(). Przykład tej reguły znajdziesz w artykule Menu niestandardowe w Google Workspace. Prosty aktywator jest przydatny do dodawania menu, ale nie może używać żadnych usług Apps Script, które wymagają autoryzacji.