Struktura dokumentu w Dokumentach Google

Aby efektywnie korzystać z interfejsu API Dokumentów Google, musisz znać architekturę dokumentu Dokumentów Google oraz elementów tworzących dokumentu, a także relacji 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. To jest które można zapisać na Dysku Google, udostępnić innym użytkownikom i zaktualizować z tekstem i obrazami.

Elementy najwyższego poziomu documents obejmują następujące zasoby: Tab, SuggestionsViewMode i inne atrybuty:

document: {
    title: ... ,
    revisionId: ... ,
    documentId: ... ,
    suggestionsViewMode: ... ,
    tabs: ...
}

Karty

Pojedynczy dokument może zawierać wiele kart, które mają różne treści na poziomie tekstu. Właściwość tabs dokumentu to Tab obiektów. Tab składa się z tych pól:

  • TabProperties: Zawiera atrybuty karty, takie jak identyfikator, tytuł i indeks.
  • childTabs: wyświetla karty podrzędne karty (karty zagnieżdżone bezpośrednio). poniżej).
  • DocumentTab: Reprezentuje zawartość tekstową karty.
.
Struktura kart w dokumencie.
. Rysunek 1. Struktura kart w dokumencie.

W dalszych sekcjach znajdziesz krótkie omówienie hierarchii kart dokumentu. Reprezentacja kodu JSON karty też zawiera bardziej szczegółowe informacje. Zobacz Praca z kartami. .

Aby można było modyfikować globalne funkcje karty dokumentu poza treścią Body, niemal zawsze lepiej jest użyć jednego lub kilku szablonów dokumentów, których można używać jako stanowi podstawę do automatycznego generowania nowych dokumentów. Więcej informacji: Scalanie tekstu w dokument

Treść

Element Body zwykle zawiera pełną zawartość karty dokumentu. Większość to elementy, które możesz lub prawdopodobnie chcesz wykorzystać w sposób zautomatyzowany, treść Body:

Struktura treści.
Rysunek 2. Struktura treści.

Element strukturalny

StructuralElement opisują treści, które nadają dokumentowi strukturę. Treść Body jest sekwencję obiektów StructuralElement. Element „treść” personalizuje każdy StructuralElement obiekt, tak jak na tym diagramie:

Elementy strukturalne.
Rysunek 3. Elementy strukturalne.

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

Paragraph to StructuralElement reprezentujący akapit. Zawiera szeroki zakres treści 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, opcjonalnym elementem, który określa punktor specyfikacji.

Element ParagraphElement działa podobnie do StructuralElement. Zestaw typy elementów treści (takie jak ColumnBreak i Equation) personalizuje swój własnych danych ParagraphElement, jak widać na tym diagramie:

Struktura elementów akapitu.
Rysunek 4. Struktura elementów akapitu.

Przykład pełnej struktury dokumentu znajdziesz w dokumencie example w formacie JSON. W danych wyjściowych możesz wiele kluczowych elementów struktury i treści, a także użycia początkowych elementów i indeksach końcowych, jak opisano w następnej sekcji.

Uruchomienia tekstu

TextRun to ParagraphElement reprezentujący ciągły ciąg tekstowy o tym samym stylu. O akapit może zawierać wiele uruchomień tekstu, ale tekst nie biegnie nigdy między akapitami granic. Treść jest dzielona po znaku nowego wiersza w celu utworzenia osobnego tekstu biegi. Rozważmy na przykład mały dokument, taki jak ten:

Mały dokument z akapitami i listą punktowaną.
Rysunek 5. Mały dokument.

Poniższy diagram pokazuje, jak można zwizualizować sekwencję akapitów. w poprzednim dokumencie, każdy z własnym atrybutem TextRun i opcjonalnym Bullet ustawieniach.

Struktura uruchomienia tekstowego.
Rysunek 6. Struktura uruchomienia tekstowego.

AutoText

AutoText to ParagraphElement reprezentujący miejsce w tekście, które jest dynamicznie zastępowane które mogą się zmieniać z biegiem czasu. W Dokumentach jest on używany do numery stron.

Indeksy początkowe i końcowe

Po zaktualizowaniu zawartości karty dokumentu każda aktualizacja w danym miejscu lub w obrębie zakresu w dokumencie. Te lokalizacje zakresów określa się za pomocą indeksów, które reprezentują przesunięcie w obrębie zawierający segment dokumentu. segment to treść, nagłówek, stopka lub przypis zawierający elementy strukturalne lub treści. Indeksy elementów są określone względem początku tego segmentu.

Większość elementów w treści treści ma parametry startIndex i Usługi: endIndex. Wskazują one przesunięcie początku elementu względem początku segmentu nadrzędnego. Więcej informacji na temat konfiguracji o kolejności wywołań interfejsu API Dokumentów wsadowych znajdziesz w artykule Wsadowy aktualizacje.

Indeksy są mierzone w jednostkach kodu UTF-16. Oznacza to, że pary zastępcze zużywają dwóch indeksów. Na przykład „UŚMIECHNIONY TWARZ” emotikon 😄 jest reprezentowany jako \uD83D\uDE00 i zużywa 2 indeksy.

W przypadku elementów w treści dokumentu indeksy przedstawiają przesunięcia od początku treści, która jest „główną” .

Funkcje „personalizacji” typy do konstrukcji elementy – SectionBreak, TableOfContents, Table oraz Paragraph – nie masz tych indeksów, ponieważ ich indeksy obejmują StructuralElement ma te pola. Dotyczy to również personalizacji typy zawarte w ParagraphElement, takie jak TextRun, AutoText, PageBreak

Dostęp do elementów

Wiele elementów można modyfikować za pomocą funkcji documents.batchUpdate . Na przykład użycie InsertTextRequest, możesz zmienić zawartość dowolnego elementu zawierającego tekst. Możesz też należy użyć funkcji UpdateTextStyleRequest w celu zastosowania formatowania do zakresu tekstu zawartego w jednym lub wielu elementach.

Aby odczytać elementy dokumentu, użyj documents.get, aby uzyskać Zrzut JSON całego dokumentu. Następnie możesz przeanalizować wynikowy kod JSON do aby znaleźć wartości poszczególnych elementów. Więcej informacji znajdziesz w sekcji Dane wyjściowe zawartość dokumentu w formacie JSON.

Analiza treści może być przydatna w różnych przypadkach. Pomyśl: np. dokument katalogowy aplikacji z listą znalezionych dokumentów. Ta aplikacja może wyodrębnić tytuł, identyfikator wersji i numer strony początkowej dokumentu jak na tym diagramie:

Struktura katalogu dokumentów.
Rysunek 7. Struktura katalogu dokumentów.

Nie ma żadnych metod odczytu tych ustawień, więc aplikacja musi aby uzyskać 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. An właściwości obiektu, w tym tych zdefiniowanych i odziedziczonych, aby określić ich końcowy wygląd.

Formatowanie znaków w tekście określa sposób renderowania tekstu w dokumencie, na przykład pogrubienie, kursywa i podkreślenie. Zastosowane formatowanie zastąpi ustawienia domyślne formatowanie dziedziczone z źródłowego akapitu TextStyle I odwrotnie: Znaki, których formatowanie nie zostanie ustawione, będą nadal dziedziczyć z parametru style akapitu.

Formatowanie akapitu określa sposób renderowania bloków tekstu w dokumencie. takie jak wyrównanie, obramowanie i wcięcia. zastosowane formatowanie, zastępuje domyślne formatowanie odziedziczone z bazowego elementu ParagraphStyle. I na odwrót – wszystkie funkcje formatowania, których nie ustawisz, będą nadal dziedziczyć z elementu stylu akapitu.