Praca z kartami

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, czyli karty zagnieżdżone 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:

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. Na przykład rozważ zastosowanie dokument, który zawiera taką hierarchię kart:

Interfejs listy kart obejmujący 3 karty najwyższego poziomu, z których część zawiera karty podrzędne

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 spowodowało, że każda z metod dokumentu została nieco zmieniona. Może to 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 Metoda documents.get zwróci wynik materiał Document z Pole document.tabs zostało wypełnione. Wszystkie pola tekstowe bezpośrednio w document (np. document.body) pozostanie pusta.
  • Jeśli nie podasz includeTabsContent, pola tekstowe w zasobie Document (np. document.body) zostaną wypełnione tylko treścią z pierwszej karty. Pole document.tabs będzie puste, a treści z innych kart nie zostaną zwrócone.

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 Requests dokumentację.

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 jako link.bookmark i link.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 jako link.bookmarkId i link.headingId. W dokumentach zawierających wiele kart, linki wewnętrzne będą wyświetlane jako link.bookmark i link.heading

W pliku document.batchUpdate, jeśli link wewnętrzny jest tworzony za pomocą jednego z uprzednich pól, zakładka z identyfikatorem określonym w Request będzie uważana za zakładkę z bookmarkiem lub nagłówkiem. 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, przemierzając hierarchii drzewa kart, a także wywoływanie metod pobierania Tab i DocumentTab zamiast Document Ten częściowy przykład kodu jest oparty na fragmencie kodu w sekcji 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();
}