Struktura dokumentu w Dokumentach Google

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

  • Model koncepcyjny elementów dokumentu
  • Jak interfejs Docs API reprezentuje te elementy
  • właściwości stylizacji 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 to jego elementy Tab, SuggestionsViewMode oraz inne:

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

Karty

Pojedynczy dokument może zawierać wiele kart o różnych zawartości 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 (zagnieżdżone bezpośrednio pod nią karty).
  • DocumentTab: reprezentuje zawartość tekstową karty.
Struktura kart dokumentu.
Rysunek 1. Struktura kart w dokumencie.

W kolejnych sekcjach znajdziesz krótki opis hierarchii kart dokumentu. Więcej szczegółowych informacji znajdziesz w reprezentacji karty w formacie JSON. Więcej informacji o funkcji kart znajdziesz w artykule Praca z kartami.

Aby manipulować funkcjami globalnych kart dokumentu poza treścią Body, prawie zawsze lepiej jest użyć co najmniej jednego szablonu dokumentu, który można wykorzystać jako podstawę do generowania nowych dokumentów za pomocą kodu. Więcej informacji znajdziesz w artykule Łączenie tekstu w dokumencie.

Treść

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

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

Element strukturalny

StructuralElementopisuje treść, która nadaje strukturę dokumentowi. Treść Body to sekwencja obiektów StructuralElement. Element treści personalizuje każdy obiekt StructuralElement, jak pokazano na diagramie poniżej:

Elementy strukturalne.
Rysunek 3. elementy konstrukcyjne;

Elementy strukturalne i ich obiekty treści zawierają wszystkie elementy wizualne w dokumencie. Dotyczy to tekstu, obrazów w tekście i formatowania.

Struktura akapitu

Element Paragraph to element StructuralElement reprezentujący akapit. Zawiera różne treści zakończone znakiem nowego wiersza. Składa się z tych elementów:

  • ParagraphElement: opisuje treść w akapicie.
  • ParagraphStyle: opcjonalny element, który wyraźnie ustawia właściwości stylu dla akapitu.
  • Bullet: jeśli akapit jest częścią listy, opcjonalny element, który określa specyfikację wypunktowania.

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

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

Przykład pełnej struktury dokumentu znajdziesz w przykładowym dokumencie w formacie JSON. W wyniku możesz zobaczyć wiele kluczowych elementów struktury i treści, a także indeksy początkowy i końcowy, jak opisano w następnej sekcji.

Przebiegi tekstu

Element TextRun to ParagraphElementreprezentujący ciągły ciąg znaków w tym samym stylu. Akapit może zawierać wiele przebiegów tekstu, ale przebiegi tekstu nigdy nie przekraczają granic akapitu. Treść jest dzielona po znaku nowego wiersza, aby utworzyć osobne uruchomienia tekstu. Rozważmy na przykład niewielki dokument, taki jak ten:

Mały dokument z akapitami i listą wypunktowaną.
Rysunek 5. mały dokument,

Na poniższym diagramie pokazano, jak można wizualizować kolejność akapitów w poprzednim dokumencie. Każdy akapit ma własne ustawienia TextRun i opcjonalne ustawienia Bullet.

Struktura przebiegu tekstu
Rysunek 6. Struktura przebiegu tekstu

AutoText

AutoText to ParagraphElement, który reprezentuje miejsce w tekście, w którym dynamicznie zastępuje zawartość, która może się zmieniać z upływem czasu. W Dokumentach jest to numer strony.

Indeksy początkowy i końcowy

Gdy aktualizujesz zawartość karty dokumentu, każda zmiana jest wprowadzana w określonym miejscu lub zakresie w dokumencie. Te lokalizacje i zakresy określa się za pomocą indeksów, które reprezentują przesunięcie w obrębie konkretnego segmentu dokumentu. Segment to treść, nagłówek, stopka lub przypis zawierający elementy strukturalne lub treści. Indeksy elementów w danym segmencie są podawane względem początku tego segmentu.

Większość elementów w treści elementu ma właściwości startIndex i endIndex zliczane od 0. Wskazują one przesunięcie początku i końca elementu względem początku otaczającego go segmentu. Więcej informacji o tym, jak zamówić zbiorcze wywołania interfejsu API Dokumentów, znajdziesz w artykule Zbiorcze aktualizacje.

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 w treści dokumentu indeksy wskazują odstęp od początku treści, czyli elementu „root”.

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.

Elementy dostępu

Wiele elementów można modyfikować za pomocą metody documents.batchUpdate. Na przykład za pomocą parametru 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ć otrzymany ciąg 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.

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

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

Ponieważ nie ma metod umożliwiających odczytywanie tych ustawień w prosty sposób, aplikacja musi pobrać cały dokument, a następnie przeanalizować kod 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. Znaki, których formatowania nie ustawisz, będą dziedziczyć styl od akapitu.

Formatowanie akapitu określa sposób wyświetlania bloków tekstu w dokumencie, na przykład wyrównanie, obramowania i wcięcia. Formatowanie, które zastosujesz, zastąpi domyślne formatowanie odziedziczone z poziomu ParagraphStyle. Z drugiej strony, wszystkie funkcje formatowania, których nie ustawisz, będą dziedziczyć ustawienia ze stylu akapitu.