Rozszerzanie możliwości 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 paneli bocznych.

Podstawy

Apps Script może wchodzić w interakcje z Dokumentami Google na 2 sposoby: każdy skrypt może tworzyć lub modyfikować dokument, jeśli użytkownik skryptu ma odpowiednie uprawnienia do dokumentu. Skrypt może też być powiązany z dokumentem, co daje mu specjalne możliwości zmiany interfejsu użytkownika lub reagowania na otwarcie dokumentu. Aby utworzyć skrypt powiązany z kontenerem w Dokumentach Google, kliknij Rozszerzenia > Apps Script.

W każdym przypadku interakcja z dokumentem Google jest prosta dzięki usłudze dokumentów Apps Script, co 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ślnie pierwszą kartę), wstawia akapit zawierający ten sam tekst co nazwa dokumentu, formatuje ten akapit jako nagłówek i dołącza tabelę na podstawie wartości w dwuwymiarowej tablicy. Skrypt może z łatwością wprowadzić te zmiany w istniejącym dokumencie, zastępując wywołanie DocumentApp.create() wywołaniem DocumentApp.openById() lub openByUrl(). W przypadku skryptów utworzonych w dokumencie (powiązanych z kontenerem) używaj DocumentApp.getActiveDocument() i Document.getActiveTab().

Struktura dokumentu

Z punktu widzenia Apps Script dokument Dokumentów Google ma strukturę podobną do dokumentu HTML – składa się z co najmniej jednego obiektu Tab, z których każdy zawiera elementy (np. Paragraph lub Table), które często zawierają inne elementy. Większość skryptów, które modyfikują dokument Google, zaczyna się od wywołania funkcji getTab() i asDocumentTab(), a następnie getBody(), ponieważ Body jest podstawowym elementem, który zawiera wszystkie inne elementy na karcie z wyjątkiem HeaderSection, FooterSection i wszystkich 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, jakie elementy mogą być zawarte w określonym typie elementu.

Elementy wyświetlane pogrubioną czcionką można wstawiać, a elementy niepogrubione można tylko modyfikować w miejscu.

Zastępowanie tekstu

Apps Script jest często używany do zastępowania tekstu w Dokumentach Google. Załóżmy, że masz arkusz kalkulacyjny pełen informacji o klientach i chcesz wygenerować spersonalizowane dokumenty Google dla każdego z nich. (Ten typ operacji jest często nazywany scalaniem poczty).

Tekst można zastąpić na wiele sposobów, ale najprostsza jest metoda replaceText() pokazana w przykładzie poniżej. replaceText obsługuje większość funkcji wyrażeń regularnych w JavaScript. Pierwsza funkcja poniżej dodaje do Dokumentów Google kilka wierszy tekstu zastępczego. W rzeczywistości prawdopodobnie wpiszesz te elementy zastępcze w dokumencie samodzielnie. Druga funkcja zastępuje symbole 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 Google Docs. W samodzielnym skrypcie użyj zamiast tego metod DocumentApp.create(), openById()> lub openByUrl() w połączeniu z metodą Document.getTab() .

Dodaj kilka 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 niestandardowe i interfejsy użytkownika

Możesz dostosować Dokumenty Google, 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 jest powiązany z dokumentem.

Dowiedz się, jak dodawać menu niestandardowe i okna w Dokumentach Google. Więcej informacji o tworzeniu niestandardowych interfejsów do okna lub paska bocznego znajdziesz w przewodniku po usłudze HTML. Jeśli planujesz opublikować interfejs niestandardowy jako dodatek, postępuj zgodnie z przewodnikiem po 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 udostępnić go innym użytkownikom, Apps Script umożliwia opublikowanie skryptu jako dodatku, aby inni użytkownicy mogli go zainstalować ze sklepu z dodatkami.

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

Reguły

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

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