Rozszerzenie Dokumentów Google

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

Podstawy

Apps Script może wchodzić w interakcje z Dokumentami 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 być też 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, kliknij Rozszerzenia > Apps Script.

W obu przypadkach możesz wchodzić w interakcje z dokumentem Dokumentów Google, korzystając z usługi dokumentów Apps Script, jak pokazano w tym przykładzie.

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 też wprowadzać te zmiany w istniejącym dokumencie, zastępując wywołanie funkcji DocumentApp.create funkcją 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 perspektywy Apps Script dokument Google Docs jest skonstruowany podobnie jak dokument HTML – składa się z co najmniej 1 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 w Dokumentach, 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 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. Poniższe drzewo pokazuje, które elementy mogą być zawarte w określonym typie elementu.

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

Zastąp tekst

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

Tekst możesz zastąpić za pomocą metody replaceText, która obsługuje większość funkcji wyrażeń regularnych w JavaScript. W tym przykładzie pierwsza funkcja dodaje do dokumentu tekst zastępczy, a druga zastępuje go właściwościami z obiektu client.

Obie te funkcje korzystają z metod getActiveDocument i getActiveTab, które mają zastosowanie tylko do skryptów utworzonych w dokumencie Dokumentów Google. W przypadku skryptu autonomicznego 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

Możesz dostosować Dokumenty, dodając niestandardowe menu, okna dialogowe i paski boczne. Pamiętaj, że skrypt może wchodzić w interakcję tylko z interfejsem dokumentu, z którym jest powiązany.

Więcej informacji o tworzeniu niestandardowych interfejsów za pomocą HTML i CSS znajdziesz w przewodniku po usłudze HTML. Jeśli planujesz opublikować interfejs jako dodatek, postępuj zgodnie z przewodnikiem po stylu, aby jego wygląd był spójny z edytorem Dokumentów.

Dodatki do Dokumentów

Dodatki działają w Dokumentach i można je instalować ze sklepu z dodatkami do Dokumentów. Jeśli masz skrypt do Dokumentów i chcesz udostępnić go innym, Apps Script umożliwia opublikowanie skryptu jako dodatku, aby inni użytkownicy mogli go zainstalować ze sklepu z dodatkami.

Aby utworzyć dodatek do Dokumentów, 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, aby reagować na onOpen zdarzenie dokumentu, które występuje, gdy użytkownik z uprawnieniami do edycji dokumentu otwiera go w Dokumentach.

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