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. Skrypt może w taki sam sposób wprowadzić te zmiany w dotychczasowym dokumencie, zastępując wywołanie DocumentApp.create() wartością DocumentApp.openById() lub openByUrl(). W przypadku skryptów utworzonych w dokumencie (związanych z kontenerem) używaj 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, które modyfikują dokument Dokumentów Google, zaczyna się wywołaniem funkcji getTab() i asDocumentTab(), a następnie getBody(), ponieważ Body to element podstawowy, 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ć w inne elementy tylko określone typy elementów. Drzewo poniżej pokazuje, które elementy mogą zawierać dany typ elementu.

Elementy wyświetlane pogrubioną czcionką można wstawiać, a elementy niewyróżnione można tylko przemieszczać.

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ępczychZastąp zmienne
function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}
 
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 dodać do Dokumentów Google niestandardowe menu i okna. 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. Jeśli masz skrypt do Dokumentów Google i chcesz udostępnić go innym, możesz go opublikować 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ć ten element, napisz funkcję o nazwie onOpen(). Przykład tego wyzwalacza znajdziesz w artykule Menu niestandardowe w Google Workspace. Chociaż prosty przełącznik jest przydatny do dodawania menu, nie może korzystać z żadnych usług Apps Script, które wymagają autoryzacji.