Struktura dokumentu w Dokumentach Google

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:

Struktura treści.
Rysunek 1. Struktura treści.

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.
Rysunek 2. Elementy strukturalne.

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:

Struktura elementów akapitu.
Rysunek 3. Struktura elementów akapitu.

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:

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

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.

Struktura uruchomienia tekstu.
Rysunek 5. Struktura uruchomienia tekstu.

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:

Struktura katalogu dokumentów.
Rysunek 6. Struktura katalogu dokumentów.

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.