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. Na tej stronie znajdziesz szczegółowe informacje na te tematy:

  • 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 Tab, SuggestionsViewMode i inne atrybuty:

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

Karty

Jeden dokument może zawierać wiele kart z różnymi treściami 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ą).
  • DocumentTab: reprezentuje tekst na karcie.
Struktura kart dokumentu.
Rysunek 1. Struktura kart dokumentu.

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órych możesz używać programowo, to elementy zawarte w komponencie Body:

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

Element konstrukcyjny

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 konstrukcyjne;
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ści są dzielone po znaku nowego wiersza, tworząc oddzielne ciągi tekstowe. Weźmy na przykład mały dokument:

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 przepływu tekstu
Rysunek 6. Struktura przepływu 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 czasem. W Dokumentach służy do numerowania stron.

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 są określane za pomocą indeksów, które reprezentują przesunięcie w segmencie dokumentu zawierającego. 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ŚMIECH” (😄) jest reprezentowany jako \uD83D\uDE00 i zajmuje 2 indeksy.

W przypadku elementów w treści dokumentu indeksy wskazują odstęp 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ż zawierające je elementy StructuralElement mają 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. Za pomocą elementu InsertTextRequest możesz na przykład zmienić zawartość 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 dokumentu. Następnie możesz przeanalizować otrzymany ciąg JSON, aby znaleźć wartości poszczególnych elementów. Więcej informacji znajdziesz w artykule Wyprowadzanie zawartości dokumentu w formacie JSON.

Analizowanie treści może być przydatne w różnych przypadkach użycia. Rozważ na przykład aplikację do katalogowania dokumentów, 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

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

Formatowanie znaków tekstu określa sposób wyświetlania tekstu w dokumencie, np. pogrubienie, kursywa i podkreślenie. Formatowanie, które zastosujesz, zastąpi domyślne formatowanie odziedziczone z akapitu źródłowego TextStyle. Znaki, których formatowania nie ustawisz, będą dziedziczyć styl od akapitu.

Formatowanie akapitu określa sposób renderowania 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 podstawowego ParagraphStyle. Z drugiej strony, wszystkie funkcje formatowania, których nie ustawisz, będą dziedziczyć ustawienia ze stylu akapitu.