Rozszerzanie Dokumentów Google

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Skrypt usługi Google Apps umożliwia automatyczne tworzenie i modyfikowanie Dokumentów Google oraz dostosowywanie interfejsu użytkownika za pomocą nowych menu, okien dialogowych i pasków bocznych.

Podstawy

Skrypt Apps Script może współpracować z Dokumentami Google na 2 sposoby: każdy skrypt może utworzyć lub zmodyfikować dokument, jeśli skrypt ma odpowiednie uprawnienia do dokumentu, a skrypt może być także powiązany z tym dokumentem, dzięki czemu skrypt będzie mógł zmieniać interfejs lub reagować po otwarciu dokumentu. Aby utworzyć skrypt powiązany z kontenerem, korzystając z Dokumentów Google, kliknij Rozszerzenia > Apps Script.

W obu przypadkach można łatwo korzystać z dokumentu Google za pomocą usługi Apps Script, jak pokazano w poniższych przykładach.

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 na Dysku Google użytkownika nowy dokument, a następnie wstawia akapit zawierający ten sam tekst co nazwa dokumentu, style i akapity jako nagłówek oraz dołącza tabelę na podstawie wartości dwuwymiarowej tablicy. Skrypt może łatwo wprowadzić takie zmiany w istniejącym dokumencie. W tym celu trzeba zastąpić wywołanie DocumentApp.create() parametrem DocumentApp.openById() lub openByUrl(). W przypadku skryptów utworzonych w dokumencie (powiązanych z kontenerem) użyj polecenia DocumentApp.getActiveDocument().

Struktura dokumentu

Z punktu widzenia Apps Script dokument Google ma strukturę podobną do dokumentu HTML – czyli dokument Google 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 rozpoczyna się od wywołania getBody(), bo element Body jest elementem głównym, który zawiera wszystkie pozostałe elementy oprócz HeaderSection, FooterSection i Footnotes.

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

Można wstawiać elementy pogrubione, a elementy inne niż pogrubione można modyfikować tylko w miejscu.

Zastępuję tekst

Apps Script często służy do zastępowania tekstu w Dokumentach Google. Załóżmy, że masz arkusz kalkulacyjny z informacjami o kliencie i chcesz wygenerować spersonalizowany dokument Google dla każdego z nich. (operacja ta jest często określana jako scalanie poczty).

Tekst można zastąpić na wiele sposobów, ale najprostsza jest metoda replaceText() widoczna w poniższym przykładzie. replaceText obsługuje większość funkcji wyrażeń regularnych JavaScriptu. Pierwsza z tych funkcji dodaje kilka wierszy tekstu zastępczego do dokumentu Google, a w rzeczywistości symbole zastępcze wpiszesz lepiej samodzielnie. Druga funkcja zastępuje obiekty zastępcze właściwościami zdefiniowanymi w obiekcie client.

Obie te funkcje korzystają z metody getActiveDocument(), która dotyczy tylko skryptów utworzonych w Dokumentach Google. W samodzielnym skrypcie użyj wartości 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ąp elementy zastępcze

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

Dokumenty Google możesz dostosowywać, 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 i tylko wtedy, gdy jest on związany z dokumentem.

Dowiedz się, jak dodawać do Dokumentów Google niestandardowe menu i okna. Więcej informacji o tworzeniu niestandardowych interfejsów w oknie dialogowym lub na pasku bocznym znajdziesz w przewodniku po usłudze HTML. Jeśli chcesz opublikować interfejs niestandardowy w ramach 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 utworzony skrypt Dokumentów Google i chcesz udostępnić go światu, Apps Script umożliwia opublikowanie go 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 informacje o tworzeniu dodatków do Dokumentów.

Aktywatory

Skrypty powiązane z dokumentem Google mogą używać prostej reguły, by na nie odpowiadać w onOpenzdarzeniu, które ma miejsce za każdym razem, gdy użytkownik z uprawnieniami do edycji otworzy dokument w Dokumentach Google.

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