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 paska bocznego.
Podstawy
Apps Script może wchodzić w interakcje z Dokumentami Google na 2 sposoby: za pomocą dowolnego skryptu można tworzyć lub modyfikować dokument, jeśli użytkownik skryptu ma odpowiednie uprawnienia. Poza tym skrypt może być powiązany z dokumentem, co daje skryptowi specjalne uprawnienia do zmieniania 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żna łatwo pracować z dokumentem Google za pomocą 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 zawierający taki sam tekst jak nazwa dokumentu, dodaje styl tego akapitu jako nagłówek i dodaje tabelę w oparciu o wartości zawarte w tablicy dwuwymiarowej. Skrypt może równie łatwo wprowadzić te zmiany w istniejącym dokumencie, zastępując wywołanie DocumentApp.create()
poleceniem DocumentApp.openById()
lub openByUrl()
.
W przypadku skryptów utworzonych w dokumencie (powiązanych z kontenerem) użyj właściwości DocumentApp.getActiveDocument()
.
Struktura dokumentu
Z perspektywy Apps Script dokument Google ma strukturę podobną do dokumentu HTML, co oznacza, że 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 zaczyna się od wywołania getBody()
, ponieważ Body
jest elementem głównym, który zawiera wszystkie pozostałe elementy oprócz HeaderSection
, FooterSection
i innych elementów Footnotes
.
Istnieją jednak reguły określające, jakie typy elementów mogą zawierać inne typy. Ponadto usługa Document Service w Apps Script może wstawiać elementy tylko określonych typów. Drzewo poniżej pokazuje, które elementy mogą zawierać określony typ elementu.
Elementy wyróżnione pogrubieniem można wstawiać, a elementy inne niż pogrubione można edytować tylko w miejscu.
- Dokument
- Treść
- HeaderSection
- ListItem
- Reguła pozioma
- Wbudowany rysunek
- Obraz wbudowany
- Tekst
- Nieobsługiwane (numer strony itp.)
- Akapit
- Reguła pozioma
- Wbudowany rysunek
- Obraz wbudowany
- Tekst
- Nieobsługiwane (numer strony itp.)
- Tabela
- ListItem
- FooterSection
- ListItem
- Reguła pozioma
- Wbudowany rysunek
- Obraz wbudowany
- Tekst
- Nieobsługiwane (numer strony itp.)
- Akapit
- Reguła pozioma
- Wbudowany rysunek
- Obraz wbudowany
- Tekst
- Nieobsługiwane (numer strony itp.)
- Tabela
- ListItem
- FootnoteSection
Zastępowanie tekstu
Apps Script często używa się do zastępowania tekstu w Dokumentach Google. Załóżmy, że masz arkusz kalkulacyjny z informacjami o kliencie i chcesz wygenerować spersonalizowane Dokumenty Google dla każdego klienta. (Ten rodzaj operacji jest często nazywany scalaniem poczty).
Tekst można zastąpić na wiele sposobów, ale najprostszy to metoda replaceText()
widoczna w poniższym przykładzie. replaceText
obsługuje większość funkcji wyrażeń regularnych JavaScriptu. Pierwsza z poniższych funkcji dodaje kilka wierszy tekstu zastępczego do Dokumentów Google. W świecie rzeczywistym korzystniej jest wpisać symbole zastępcze w dokumencie. Druga funkcja zastępuje symbole 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 pliku Dokumentów Google. W samodzielnym skrypcie użyj 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 zmiennych
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 użytkownika
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 bieżącym wystąpieniu otwartego dokumentu, 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 dla okna dialogowego lub paska bocznego znajdziesz w przewodniku po usłudze HTML. Jeśli zamierzasz opublikować interfejs niestandardowy jako część 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 stworzony skrypt do Dokumentów Google i chcesz go udostępnić całemu światu, Apps Script umożliwia opublikowanie skryptu 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 wprowadzenie do tworzenia dodatków do Dokumentów.
Aktywatory
Skrypty powiązane z Dokumentem Google mogą używać prostego wyzwalacza do odpowiadania na zdarzenie dokumentu onOpen
, które ma miejsce, gdy użytkownik z uprawnieniami do edycji otwiera dokument w Dokumentach Google.
Aby skonfigurować aktywator, po prostu napisz funkcję o nazwie onOpen()
. Przykład tego aktywatora znajdziesz w artykule Menu niestandardowe w Google Workspace.
Prosty aktywator przydaje się do dodawania menu, ale nie może używać usług Apps Script wymagających autoryzacji.