Interfejs API Dokumentów Google zapewnia dostęp do zawartości z dowolnej karty w dokumencie.
Co to są karty?
Dokumenty Google zawierają warstwę organizacyjną zwaną kartami. W Dokumentach można tworzyć jedną lub więcej kart podobnie jak karty w Arkuszach. Każda karta ma swoje własne tytuł i identyfikator (dołączone do adresu URL). Karta może też mieć karty podrzędne, które są umieszczone pod inną kartą.
Obsługa interfejsów API w kartach podrzędnych jest obecnie dostępna, ale wkrótce będzie też można korzystać z interfejsu użytkownika. Już dziś możesz zapewnić obsługę kart podrzędnych w kodzie, aby po wprowadzeniu obsługi interfejsu użytkownika nie musisz aktualizować kodu.
Zmiany strukturalne w sposobie prezentowania zawartości dokumentu w zasobie dokumentu
W przeszłości w dokumentach brakowało kart, więc
Document
Zasób umieszczony bezpośrednio w zasobie
całą zawartość tekstową tych pól:
document.body
document.headers
document.footers
document.footnotes
document.documentStyle
document.suggestedDocumentStyleChanges
document.namedStyles
document.suggestedNamedStylesChanges
document.lists
document.namedRanges
document.inlineObjects
document.positionedObjects
Ze względu na dodatkową strukturę kart, pola te nie są już
semantycznie przedstawiają treść tekstową ze wszystkich kart w dokumencie.
treści tekstowe są teraz reprezentowane w innej warstwie. Właściwości karty
materiały w Dokumentach Google są dostępne przy użyciu
document.tabs
, czyli listę
Tab
obiektów, z których każdy
zawiera wszystkie wyżej wymienione pola treści tekstowej. Późniejsze sekcje zawierają
krótkie omówienie;
Reprezentacja kodu JSON karty
zawiera też bardziej szczegółowe informacje.
Dostęp do właściwości karty
Dostęp do właściwości karty za pomocą
tab.tabProperties
który zawiera takie informacje jak identyfikator, tytuł i pozycjonowanie karty.
Dostęp do tekstu na karcie
Rzeczywista zawartość dokumentu na karcie jest wyświetlana jako
tab.documentTab
Wszystkie z tej listy
wymienione wyżej pola treści tekstowej są dostępne przy użyciu interfejsu tab.documentTab
.
Na przykład zamiast document.body
należy użyć
document.tabs[indexOfTab].documentTab.body
Hierarchia kart
Karty podrzędne są reprezentowane w interfejsie API jako karty
pole tab.childTabs
włączone
Tab
Dostęp do wszystkich kart w
dokument wymaga przemierzania „drzewa” kart podrzędnych. Weź na przykład pod uwagę
dokument, który zawiera taką hierarchię kart:
Aby pobrać: Body
na karcie 3.1.2 dostępne byłyby
document.tabs[2].childTabs[0].childTabs[1].documentTab.body
. Zobacz przykład
bloki kodu w dalszej sekcji, która zawiera przykładowy kod do iteracji.
na wszystkich kartach w dokumencie.
Zmiany metod
Wprowadzenie kart sprawiło, że w przypadku każdej metody tworzenia dokumentów wprowadzono kilka zmian może wymagać zaktualizowania kodu.
documents.get
Domyślnie nie jest zwracana cała zawartość kart. Deweloperzy powinni zaktualizować swoje
aby uzyskać dostęp do wszystkich kart.
documents.get
ujawnia
Parametr includeTabsContent
, który umożliwia określenie, czy treści z
w odpowiedzi znajdują się wszystkie karty.
- Jeśli
includeTabsContent
ma wartośćtrue
, makro Metodadocuments.get
zwróci wynik materiałDocument
z Poledocument.tabs
zostało wypełnione. Wszystkie pola tekstowe bezpośrednio wdocument
(np.document.body
) pozostanie pusta. - Jeśli nie podasz
includeTabsContent
, pola tekstowe zasobuDocument
(np.document.body
) zostaną wypełnione tylko treścią z pierwszej karty. Poledocument.tabs
będzie puste, a zawartość z innych kart nie zostanie zwrócona.
documents.create
Metoda documents.create
zwraca zasób Document
reprezentujący pusty dokument, który został utworzony. Zwrócone wartości
Document
Zasób będzie wypełniać pola
pustej zawartości dokumentu zarówno w jego polach treści, jak i
document.tabs
document.batchUpdate
Każda Request
obejmuje
pozwala określić karty, do których ma zostać zastosowana aktualizacja. Domyślnie, jeśli karta nie jest
parametr
Request
w większości
zostaną zastosowane na pierwszej karcie dokumentu.
ReplaceAllTextRequest
DeleteNamedRangeRequest
,
oraz
ReplaceNamedRangeContentRequest
to trzy żądania specjalne, które domyślnie zostaną zastosowane do wszystkich kart.
Zapoznaj się z
Request
s
dokumentację.
Zmiany dotyczące linków wewnętrznych
Użytkownicy mogą tworzyć wewnętrzne linki do kart, zakładek i nagłówków w dokumencie.
Dzięki wprowadzeniu funkcji kart funkcje link.bookmarkId
oraz
link.headingId
pól w
Zasób Link
nie może już zostać usunięty
reprezentują zakładkę lub nagłówek na konkretnej karcie w dokumencie.
Deweloperzy powinni zaktualizować swój kod tak, aby używał link.bookmark
i
link.heading
w operacjach odczytu i zapisu. Ujawnia linki wewnętrzne za pomocą
BookmarkLink
i
HeadingLink
obiektów, każdy
zawierająca identyfikator zakładki lub nagłówka oraz identyfikator karty, w której się znajduje
cal Dodatkowo link.tabId
ujawnia linki wewnętrzne dla kart.
Zawartość linku documents.get
odpowiedź może się też różnić w zależności od parametru includeTabsContent
:
- Jeśli zasada
includeTabsContent
ma wartośćtrue
, wszystkie linki wewnętrzne będą widoczne jakolink.bookmark
ilink.heading
. Starsze pola nie będą już używane. - Jeśli nie podano
includeTabsContent
, w dokumentach zawierających pojedyncza karta, wszelkie wewnętrzne linki do zakładek lub nagłówków na tej karcie będą nadal dostępne jakolink.bookmarkId
ilink.headingId
. W dokumentach zawierających wiele kart, linki wewnętrzne będą wyświetlane jakolink.bookmark
ilink.heading
W document.batchUpdate
jeśli link wewnętrzny został utworzony przy użyciu jednego ze starszych pól, zakładka lub
nagłówek zostanie uznany za pochodzący z identyfikatora karty określonego w
Request
Jeśli nie ma żadnej karty
zostanie uznany za pochodzący z pierwszej karty dokumentu.
Reprezentacja linku JSON zapewnia bardziej szczegółowe informacje.
Typowe wzorce używania kart
Poniżej znajduje się przykładowy kod opisujący różne sposoby korzystania z kart.
Odczytywanie zawartości wszystkich kart w dokumencie
Dotychczasowy kod, który to umożliwiał, zanim funkcja kart została przeniesiona do obsługi
kart, ustawiając parametr includeTabsContent
na true
, przechodząc przez
hierarchii drzewa kart, a także wywoływanie metod pobierania
Tab
i
DocumentTab
zamiast
Document
Oto część
Przykładowy kod jest oparty na fragmencie kodu dostępnym na stronie
Wyodrębnianie tekstu z dokumentu Pokazuje
Jak wydrukować cały tekst z każdej karty w dokumencie. Ta karta
który można dostosować do wielu innych zastosowań,
rzeczywistej struktury kart.
Java
/** Prints all text contents from all tabs in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from each tab in the document. for (Tab tab: allTabs) { // Get the DocumentTab from the generic Tab. DocumentTab documentTab = tab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); } } /** * Returns a flat list of all tabs in the document in the order they would * appear in the UI (top-down ordering). Includes all child tabs. */ private List<Tab> getAllTabs(Document doc) { List<Tab> allTabs = new ArrayList<>(); // Iterate over all tabs and recursively add any child tabs to generate a // flat list of Tabs. for (Tab tab: doc.getTabs()) { addCurrentAndChildTabs(tab, allTabs); } return allTabs; } /** * Adds the provided tab to the list of all tabs, and recurses through and * adds all child tabs. */ private void addCurrentAndChildTabs(Tab tab, List<Tab> allTabs) { allTabs.add(tab); for (Tab tab: tab.getChildTabs()) { addCurrentAndChildTabs(tab, allTabs); } } /** * Recurses through a list of Structural Elements to read a document's text * where text may be in nested elements. * * <p>For a code sample, see * <a href="https://developers.google.com/docs/api/samples/extract-text">Extract * the text from a document</a>. */ private static String readStructuralElements(List<StructuralElement> elements) { ... }
Odczytywanie zawartości pierwszej karty w dokumencie
Przypomina to odczytywanie wszystkich kart.
Java
/** Prints all text contents from the first tab in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from the first tab in the document. Tab firstTab = allTabs.get(0); // Get the DocumentTab from the generic Tab. DocumentTab documentTab = firstTab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); }
Prześlij prośbę o zaktualizowanie pierwszej karty
Poniższy przykładowy częściowy kod pokazuje, jak ustawić kierowanie na konkretną kartę w
Request
Ten kod
na podstawie próbki w
Przewodnik po wstawianiu, usuwaniu i przenoszeniu tekstu.
Java
/** Inserts text into the first tab of the document. */ static void insertTextInFirstTab(Docs service, String documentId) throws IOException { // Get the first tab's ID. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); Tab firstTab = doc.getTabs().get(0); String tabId = firstTab.getTabProperties().getTabId(); List<Request>requests = new ArrayList<>(); requests.add(new Request().setInsertText( new InsertTextRequest().setText(text).setLocation(new Location() // Set the tab ID. .setTabId(tabId) .setIndex(25)))); BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests); BatchUpdateDocumentResponse response = docsService.documents().batchUpdate(DOCUMENT_ID, body).execute(); }