Aby skutecznie korzystać z interfejsu API Dokumentów Google, musisz znać architekturę dokumentu Dokumentów Google i elementy, które się w nim składają, a także zależności między nimi. Ta strona zawiera szczegółowe omówienie tych tematów:
- Model koncepcyjny elementów dokumentu
- Sposób, w jaki interfejs API Dokumentów przedstawia te elementy
- Właściwości stylu elementów
Elementy najwyższego poziomu
Najbardziej zewnętrznym elementem kontenera w Dokumentach Google jest dokument. Jednostkę tę można zapisywać na Dysku Google, udostępniać innym użytkownikom i aktualizować za pomocą tekstu oraz obrazów.
Najważniejsze elementy zasobu documents to Body, Header, Footer i wiele innych:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Aby manipulować globalnymi funkcjami dokumentu poza treścią Body, prawie zawsze lepiej jest użyć co najmniej 1 szablonu dokumentu, którego możesz użyć jako podstawy do automatycznego generowania nowych dokumentów. Więcej informacji znajdziesz w artykule Scalanie tekstu w dokument.
Treść
Element Body zwykle zawiera pełną zawartość dokumentu. Większość elementów, które można lub prawdopodobnie chcesz wykorzystać w sposób zautomatyzowany, to elementy w treści Body:
Element strukturalny
StructuralElement opisuje treść, która nadaje dokumentowi strukturę. Treść Body to sekwencja obiektów StructuralElement. Element treści personalizuje każdy obiekt StructuralElement, jak widać na tym diagramie:
Elementy strukturalne i ich obiekty treści zawierają wszystkie komponenty wizualne w dokumencie. Dotyczy to m.in. tekstu, obrazów w tekście i formatowania.
Struktura akapitu
Znak Paragraph to StructuralElement reprezentujący akapit. Zawiera zakres treści,
który kończy się znakiem nowego wiersza. Składa się z tych obiektów:
ParagraphElement: opisuje treść akapitu.ParagraphStyle: opcjonalny element, który bezpośrednio ustawia właściwości stylu akapitu.Bullet: jeśli akapit jest częścią listy, jest to opcjonalny element ze specyfikacją punktowaną.
Element ParagraphElement działa podobnie do StructuralElement. Zbiór typów elementów treści (np. ColumnBreak i Equation) personalizuje własny element ParagraphElement, jak widać na tym diagramie:
Przykład pełnej struktury dokumentu znajdziesz w przykładzie dokumentu w formacie JSON. W danych wyjściowych zobaczysz wiele kluczowych elementów struktury i treści, a także użycie indeksów początkowych i końcowych, co opisaliśmy w kolejnej sekcji.
Uruchomienia tekstu
TextRun to element ParagraphElement, który reprezentuje ciągły ciąg tekstowy o tym samym stylu. Akapit może zawierać wiele uruchomień tekstu, ale tekst nigdy nie przekracza granic akapitów. Treść jest dzielona po znaku nowego wiersza, aby utworzyć osobne uruchomienia tekstu. Rozważmy na przykład mały dokument, taki jak ten:
Ten diagram przedstawia wizualizację sekwencji akapitów w poprzednim dokumencie z własnymi ustawieniami TextRun i Bullet.
AutoText
AutoText to ParagraphElement reprezentujący miejsce w tekście, które jest dynamicznie zastępowane treściami, które mogą się zmieniać z biegiem czasu. W Dokumentach jest to numer strony.
Indeksy początkowe i końcowe
Gdy aktualizujesz treść dokumentu, każda aktualizacja ma miejsce w określonym miejscu lub w określonym zakresie w obrębie dokumentu. Te lokalizacje i zakresy określa się za pomocą indeksów, które reprezentują przesunięcie w obrębie segmentu dokumentu. Segment to treść, nagłówek, stopka lub przypis, który zawiera elementy strukturalne lub treść. Indeksy elementów w obrębie segmentu są określone względem jego początku.
Większość elementów w treści treści ma właściwości startIndex i endIndex liczone od zera. Wskazują one przesunięcie początku i końca elementu względem początku segmentu nadrzędnego. Więcej informacji o kolejności wywołań interfejsu wsadowego interfejsu API Dokumentów znajdziesz w artykule Aktualizacje wsadowe.
Indeksy są mierzone w jednostkach kodu UTF-16. Oznacza to, że pary zastępcze korzystają
z 2 indeksów. Na przykład emotikon „UŚMIECHNIONY TWARZ” 😄 jest przedstawiony jako \uD83D\uDE00, który zajmuje 2 indeksy.
W przypadku elementów treści dokumentu indeksy reprezentują przesunięcia od początku treści, która jest elementem głównym.
Typy „personalizacji” dla elementów strukturalnych – SectionBreak, TableOfContents, Table iParagraph, nie mają tych indeksów, ponieważ ich zawartość zawarta w nich (StructuralElement) zawiera te pola. Dotyczy to również typów personalizacji zawartych w ParagraphElement, takich jak TextRun, AutoText i PageBreak.
Dostęp do elementów
Wiele elementów można modyfikować za pomocą metody documents.batchUpdate. Na przykład używając właściwości InsertTextRequest, możesz zmienić zawartość dowolnego elementu zawierającego tekst. W ten sam sposób możesz użyć funkcji UpdateTextStyleRequest, aby zastosować formatowanie do zakresu tekstu zawartego w jednym lub kilku elementach.
Aby odczytać elementy dokumentu, użyj metody documents.get, aby uzyskać zrzut JSON całego dokumentu. Następnie możesz przeanalizować uzyskany kod JSON, aby znaleźć wartości poszczególnych elementów. Aby dowiedzieć się więcej, zapoznaj się z sekcją Wyjściowa zawartość dokumentu w formacie JSON.
Analiza treści może być przydatna w różnych przypadkach. Weźmy na przykład dokument katalogowy aplikacji z listą znalezionych dokumentów. Ta aplikacja może wyodrębnić tytuł, identyfikator wersji i numer strony początkowej dokumentu, jak pokazano na tym diagramie:
Nie ma żadnych metod odczytu tych ustawień, dlatego aplikacja musi pobrać cały dokument, a następnie przeanalizować plik JSON, aby wyodrębnić te wartości.
Dziedziczenie w usługach
Element StructuralElement może dziedziczyć właściwości z obiektów nadrzędnych. Właściwości obiektu, w tym zdefiniowane i odziedziczone, określają jego ostateczny wygląd.
Formatowanie znaków w tekście określa sposób renderowania tekstu w dokumencie (np. pogrubienie, kursywa czy podkreślenie). Zastosowane formatowanie zastępuje domyślne formatowanie odziedziczone z akapitu TextStyle. I na odwrót, wszystkie znaki, których formatowanie nie zostanie ustawione, będą dalej dziedziczyć ze stylów akapitu.
Formatowanie akapitu określa sposób renderowania bloków tekstu w dokumencie, np. wyrównanie, obramowanie i wcięcia. Zastosowane formatowanie zastępuje domyślne formatowanie odziedziczone z bazowego elementu ParagraphStyle.
I odwrotnie, wszystkie funkcje formatowania, których nie skonfigurujesz, będą dziedziczyć styl akapitu.