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, 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 samodzielnie 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 usługi documents.tabs, która jest listą Tabs, z których każde zawiera wszystkie wymienione wyżej pola treści tekstowych. 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

Uzyskaj dostęp do właściwości karty za pomocą tab.tabProperties. Zawierają one informacje takie jak: jak identyfikator, tytuł i położenie karty.

Dostęp do tekstu na karcie

Rzeczywista zawartość dokumentu na karcie jest wyświetlana jako tab.documentTab. Wszystkie wymienionych powyżej pól tekstowych jest dostępne przy użyciu 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 pole tab.childTabs w systemie Tab. Dostęp do wszystkich kart w dokumencie wymaga przemierzania „drzewa” kart podrzędnych. Weźmy na przykład taki dokument, który zawiera taką hierarchię kart:

Aby pobrać body z karty 3.1.2, należałoby wejść na 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. Metoda documents.get udostępnia Parametr includeTabsContent, który umożliwia określenie, czy treści z wszystkie karty znajdują się w odpowiedzi.

• Jeśli includeTabsContent ma wartość true, metoda documents.get zwraca zasób Document z wypełnionym polem document.tabs. Wszystkie pola tekstowe bezpośrednio w document (np. document.body) pozostaną puste.
• 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 zawartość z innych kart nie zostanie zwrócona.

documents.create

Metoda documents.create zwraca błąd Document Zasób reprezentujący pustego dokumentu, 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ę.

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 Pola link.headingId nie mogą już reprezentować zakładki ani nagłówka w sekcji określoną kartę 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 w odpowiedzi documents.get może się też różnić w zależności od Parametr includeTabsContent:

• Jeśli zasada includeTabsContent ma wartość true, wszystkie linki wewnętrzne będą widoczne jako link.bookmark i link.heading. Starsze pola (link.bookmarkId i link.headingId) 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

Jeśli w document.batchUpdate link wewnętrzny został utworzony za pomocą jednej z starszych pól, zakładka lub nagłówek będą uważane za pochodzące z identyfikatora karty określona w tagu 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 hierarchię drzewa kart oraz wywoływanie metod pobierania z tabel Tab i DocumentTab zamiast Document Poniższa próbka kodu jest oparta na fragmencie kodu dostępnym na stronie Wyodrębnianie tekstu z dokumentu Pokazuje on, jak wydrukować całą zawartość tekstu z każdej karty w dokumencie. Ten kod przemierzania kart można dostosować do wielu innych zastosowań, w których dbają o rzeczywistą strukturę kart.

/** 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.

/** 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 Kod ten opiera się na przykładzie w pliku Wstawianie, usuwanie i przenoszenie tekstu Przewodnik.

/** 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();
}