Ta strona została przetłumaczona przez Cloud Translation API.

Struktura dokumentu w Dokumentach Google

Aby efektywnie korzystać z interfejsu Google Docs API, musisz znać architekturę dokumentu Google Docs oraz elementy, z których się składa, a także relacje między nimi. Na tej stronie znajdziesz szczegółowe omówienie tych tematów:

Model koncepcyjny elementów dokumentu
Sposób reprezentowania tych elementów w interfejsie Docs API
właściwości stylów elementów,

Elementy najwyższego poziomu

Najbardziej zewnętrznym elementem kontenera w Dokumentach Google jest dokument. Jest to jednostka, którą można zapisać na Dysku Google, udostępnić innym użytkownikom i zaktualizować za pomocą tekstu i obrazów.

Elementy najwyższego poziomu zasobu documents obejmują jego Tab, SuggestionsViewMode i inne atrybuty:

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

Karty

Jeden dokument może zawierać wiele kart, które mają różną zawartość na poziomie tekstu. Właściwość tabs dokumentu to sekwencja obiektów Tab. 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 pod nią).
DocumentTab: Reprezentuje treść tekstową karty.

**Rysunek 1.** Struktura kart dokumentu.

W dalszych sekcjach znajdziesz krótkie omówienie hierarchii kart dokumentu. Więcej szczegółowych informacji znajdziesz też w reprezentacji JSON karty. Więcej informacji o funkcji kart znajdziesz w artykule Praca z kartami.

Aby manipulować funkcjami kart dokumentu globalnego poza treścią Body, prawie zawsze lepiej jest użyć co najmniej jednego szablonu dokumentu, którego możesz użyć jako podstawy do programowego generowania nowych dokumentów. Więcej informacji znajdziesz w artykule Scalanie tekstu z dokumentem.

Treść

Tag Body zwykle zawiera pełną zawartość karty dokumentu. Większość elementów, których możesz lub chcesz używać programowo, to elementy w treści Body:

Element konstrukcyjny

StructuralElement opisuje treść, która nadaje dokumentowi strukturę. Zawartość Body to sekwencja obiektów StructuralElement. Element treści personalizuje każdy obiekt StructuralElement, jak pokazano 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 zakres treści zakończony znakiem nowego wiersza. Składa się z tych obiektów:

ParagraphElement: opisuje treść w akapitach.
ParagraphStyle: opcjonalny element, który jawnie ustawia właściwości stylu akapitu.
Bullet: jeśli akapit jest częścią listy, element opcjonalny, który zawiera specyfikację punktorów.

ParagraphElement działa podobnie do StructuralElement. Zestaw typów elementów treści (np. ColumnBreak i Equation) personalizuje własny ParagraphElement, jak pokazano na tym diagramie:

**Rysunek 4.** 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 strukturalnych i treści, a także użycie indeksów początkowych i końcowych, co opisujemy w następnej sekcji.

Ciągi tekstowe

TextRun to ParagraphElement reprezentujący ciągły ciąg tekstu o tym samym stylu. A akapit może zawierać wiele fragmentów tekstu, ale fragmenty tekstu nigdy nie przekraczają granic akapitu. Treść jest dzielona po znaku nowego wiersza, aby utworzyć osobne fragmenty tekstu. Weź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 wizualizować sekwencję akapitów w poprzednim dokumencie, z których każdy ma własne ustawienia TextRun i opcjonalne ustawienia Bullet.

**Rysunek 6.** Struktura ciągu tekstowego.

AutoText

AutoText to ParagraphElement, który reprezentuje miejsce w tekście dynamicznie zastępowane treścią, która może się zmieniać z czasem. W Dokumentach jest to używane w przypadku numerów stron.

Indeksy początkowy i końcowy

Gdy wprowadzisz zmiany w treści karty dokumentu, każda aktualizacja zostanie zastosowana w określonym miejscu lub zakresie w dokumencie. Te lokalizacje i zakresy są określane za pomocą indeksów, które reprezentują przesunięcie w segmencie dokumentu zawierającego. Segment to treść główna, nagłówek, stopka lub przypis zawierający elementy strukturalne lub treści. Indeksy elementów w segmencie są określane względem początku tego segmentu.

Większość elementów w treści ma właściwości startIndex i endIndex oparte na indeksie zerowym. Wskazują one przesunięcie początku i końca elementu względem początku otaczającego go segmentu. Więcej informacji o tym, jak uporządkować wywołania zbiorcze interfejsu API Dokumentów, znajdziesz w artykule Aktualizacje zbiorcze.

Indeksy są mierzone w jednostkach kodu UTF-16. Oznacza to, że pary zastępcze zajmują 2 indeksy. Na przykład emoji „UŚMIECHNIĘTA TWARZ” 😄 jest reprezentowany jako \uD83D\uDE00 i zajmuje 2 indeksy.

W przypadku elementów w treści dokumentu indeksy reprezentują przesunięcia od początku treści, czyli elementu „root”.

Typy „personalizujące” dla elementów strukturalnych – SectionBreak, TableOfContents, Table i Paragraph – nie mają tych indeksów, ponieważ ich element nadrzędny StructuralElement zawiera te pola. Dotyczy to również typów personalizacji zawartych w ParagraphElement, takich jak TextRun, AutoText i PageBreak.

Elementy dostępu

Wiele elementów można modyfikować za pomocą metody documents.batchUpdate. Na przykład za pomocą tagu InsertTextRequest możesz zmienić treść dowolnego elementu zawierającego tekst. Podobnie możesz użyć UpdateTextStyleRequest, aby zastosować formatowanie do zakresu tekstu zawartego w co najmniej 1 elemencie.

Aby odczytać elementy dokumentu, użyj metody documents.get, aby uzyskać zrzut JSON całego dokumentu. Następnie możesz przeanalizować wynikowy plik JSON, aby znaleźć wartości poszczególnych elementów. Więcej informacji znajdziesz w artykule Wyświetlanie zawartości dokumentu wyjściowego w formacie JSON.

Analizowanie treści może być przydatne w różnych przypadkach użycia. Rozważmy na przykład aplikację katalogującą dokumenty, która wyświetla listę znalezionych dokumentów. Ta aplikacja może wyodrębniać tytuł, identyfikator wersji i numer strony początkowej kart dokumentu, jak pokazano na poniższym diagramie:

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

Nie ma metod, które umożliwiają bezpośrednie odczytywanie tych ustawień, więc aplikacja musi pobrać cały dokument, a następnie przeanalizować kod JSON, aby wyodrębnić te wartości.

Dziedziczenie w usługach

StructuralElement może dziedziczyć właściwości z obiektów nadrzędnych. Właściwości obiektu, w tym te, które definiuje, i te, które dziedziczy, określają jego ostateczny wygląd.

Formatowanie znaków tekstu określa sposób renderowania tekstu w dokumencie, np. pogrubienie, kursywa i podkreślenie. Zastosowane formatowanie zastępuje domyślne formatowanie odziedziczone z akapitów bazowychTextStyle. Z kolei wszystkie znaki, których formatowania nie ustawisz, nadal będą dziedziczyć style 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 ParagraphStyle. Z kolei wszystkie funkcje formatowania, których nie ustawisz, będą nadal dziedziczone ze stylu akapitu.