Aby skutecznie korzystać z interfejsu API Dokumentów Google, musisz znać architekturę dokumentu Dokumentów Google i jego elementy, a także relacje między nimi. Ta strona zawiera szczegółowe omówienie tych tematów:
- Model koncepcyjny elementów dokumentu
- Sposób przedstawiania tych elementów za pomocą interfejsu API Dokumentów
- Właściwości stylu elementów
Elementy najwyższego poziomu
Najbardziej zewnętrznym elementem kontenera w Dokumentach Google jest dokument. Tę jednostkę można zapisać na Dysku Google, udostępnić innym użytkownikom i aktualizować za pomocą tekstu i obrazów.
Do elementów najwyższego poziomu zasobu documents
należą Body
, Header
, Footer
i wiele innych atrybutów:
document: { body: ... , documentStyle: ... , lists: ... , documentId: ... , namedStyles: ... , revisionId: ... , title: ... }
Aby manipulować globalnymi funkcjami dokumentu poza treścią Body
, niemal zawsze lepiej jest użyć co najmniej 1 szablonu dokumentu, który może służyć jako podstawa do programowego generowania nowych dokumentów. Więcej informacji znajdziesz w artykule Scalanie tekstu w dokument.
Treść
Pole Body
zazwyczaj zawiera pełną zawartość dokumentu. Większość elementów, które możesz lub prawdopodobnie chcesz wykorzystać w sposób zautomatyzowany, to elementy treści Body
:
Element konstrukcyjny
StructuralElement
opisuje treść, która określa strukturę dokumentu. Treść Body
to sekwencja obiektów StructuralElement
. Element content 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 tekstu, obrazów w tekście i formatowania.
Struktura akapitu
Paragraph
to element StructuralElement
reprezentujący akapit. Zawiera on zakres treści zakończonych znakiem nowego wiersza. Składa się z tych obiektów:
ParagraphElement
: opisuje treść akapitu.ParagraphStyle
: element opcjonalny, który jawnie ustawia właściwości stylu akapitu.Bullet
: jeśli akapit jest częścią listy, opcjonalny element zawierający specyfikację punktora.
ParagraphElement
działa na przykład tak: StructuralElement
. Zbiór typów elementów treści (np. ColumnBreak
i Equation
) personalizuje własny element ParagraphElement
, jak na tym schemacie:
Przykład pełnej struktury dokumentu znajdziesz w przykładzie dokumentu w formacie JSON. W danych wyjściowych widać wiele kluczowych elementów struktury i treści, a także korzystanie z indeksów początkowych i końcowych, co opisano w następnej sekcji.
Uruchomienia tekstu
TextRun
to element ParagraphElement
reprezentujący ciągły ciąg tekstowy o takim samym stylu. Akapit może zawierać wiele uruchomień tekstu, ale tekst nigdy nie przekracza granic akapitu. Treść jest dzielona po znaku nowego wiersza, aby utworzyć osobne biegi tekstowe. Rozważmy na przykład niewielki dokument, taki jak:
Na diagramie poniżej widać, jak można zwizualizować sekwencję akapitów poprzedniego dokumentu, z których każdy ma własne ustawienia TextRun
i opcjonalne ustawienia Bullet
.
AutoText
AutoText
to element ParagraphElement
reprezentujący miejsce w tekście, które jest dynamicznie zastępowane treściami, które mogą zmieniać się w czasie. W Dokumentach oznacza to
numery stron.
Indeksy początkowe i końcowe
Gdy aktualizujesz treść dokumentu, każda aktualizacja odbywa się w określonej lokalizacji lub w określonym zakresie w obrębie dokumentu. Te lokalizacje i zakresy są określane za pomocą indeksów, które reprezentują przesunięcie w obrębie zawartego w nim segmentu dokumentu. Segment to treść, nagłówek, stopka lub przypis zawierające elementy strukturalne lub treści. Indeksy elementów w segmencie są przedstawiane względem jego początku.
Większość elementów w treści ma właściwości startIndex
i endIndex
liczone od zera. Określają one przesunięcie początku i końca elementu względem początku jego segmentu nadrzędnego. Więcej informacji o kolejności zbiorczych wywołań interfejsu API Dokumentów znajdziesz w artykule Aktualizacje zbiorcze.
Indeksy są mierzone w jednostkach kodu UTF-16. Oznacza to, że pary zastępcze wykorzystują
2 indeksy. Na przykład emotikon „Uśmiechnięta TWARZ” (😄) jest oznaczony jako \uD83D\uDE00
i zbiera 2 indeksy.
W przypadku elementów w treści dokumentu indeksy reprezentują przesunięcia od początku treści, która jest elementem „root”.
Typy „personalizacji” elementów strukturalnych – SectionBreak
, TableOfContents
, Table
i Paragraph
– nie mają tych indeksów, ponieważ ich otaczające je StructuralElement
zawierają te pola. Dotyczy to też typów personalizacji zawartych w polu 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 właściwość InsertTextRequest
pozwala zmienić treść dowolnego elementu zawierającego tekst. Możesz też użyć funkcji UpdateTextStyleRequest
, aby zastosować formatowanie do zakresu tekstu zawartego w jednym lub wielu elementach.
Aby odczytać elementy dokumentu, użyj metody documents.get
, aby uzyskać zrzut JSON pełnego dokumentu. Następnie możesz przeanalizować wynikowy kod JSON, aby znaleźć wartości poszczególnych elementów. Więcej informacji znajdziesz w sekcji Zawartość dokumentów wyjściowych w formacie JSON.
Analiza treści może być przydatna w różnych przypadkach użycia. Weźmy np. aplikację katalogową dokumentów 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 metod umożliwiających jawne odczytanie tych ustawień, dlatego aplikacja musi pobrać cały dokument, a następnie przeanalizować plik JSON w celu wyodrębnienia tych 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 przez niego i odziedziczone, określają ostateczny wygląd obiektu.
Formatowanie znaków (np. pogrubienie, kursywa i podkreślenie) określa sposób renderowania tekstu w dokumencie. Zastosowane formatowanie zastępuje domyślne formatowanie odziedziczone z TextStyle
akapitu. I na odwrót: znaki, których formatowanie nie zostanie ustawione, będą nadal dziedziczyć styl ze stylów akapitu.
Formatowanie akapitu określa sposób renderowania bloków tekstu w dokumencie, np. wyrównanie, obramowanie i wcięcie. Zastosowane formatowanie zastępuje domyślne formatowanie odziedziczone z pierwotnego elementu (ParagraphStyle
).
I na odwrót: wszystkie funkcje formatowania, których nie skonfigurujesz, będą nadal dziedziczyć styl akapitu.