Praca z kartami

Interfejs API Dokumentów Google umożliwia dostęp do treści z dowolnej karty w dokumencie.

Co to są karty?

Dokumenty Google mają warstwę organizacyjną zwaną kartami. Dokumenty umożliwiają użytkownikom tworzenie co najmniej jednej karty w pojedynczym dokumencie, podobnie jak w przypadku kart w Arkuszach. Każda karta ma swój własny tytuł i identyfikator (dołączony w adresie URL). Karta może też mieć karty podrzędne, czyli karty zagnieżdżone pod inną kartą.

zmiany strukturalne dotyczące sposobu, w jaki treść dokumentu jest reprezentowana w zasobach dokumentu;

W przeszłości dokumenty nie zawierały pojęcia kart, więc zasób Document zawierał bezpośrednio całą treść tekstową w tych polach:

• document.body
• document.headers
• document.footers
• document.footnotes
• document.documentStyle
• document.suggestedDocumentStyleChanges
• document.namedStyles
• document.suggestedNamedStylesChanges
• document.lists
• document.namedRanges
• document.inlineObjects
• document.positionedObjects

Dzięki dodatkowej hierarchii strukturalnej kart te pola nie odzwierciedlają już semantycznie treści tekstowej ze wszystkich kart w dokumencie. Treści tekstowe są teraz wyświetlane w innej warstwie. Właściwości kart i zawartość w Dokumentach Google są dostępne za pomocą obiektu document.tabs, który jest listą obiektów Tab, z których każdy zawiera wszystkie wspomniane pola treści tekstowych. W kolejnych sekcjach znajdziesz krótkie omówienie, a reprezentacja tablicy w formacie JSON zawiera bardziej szczegółowe informacje.

Właściwości karty dostępu

Dostęp do właściwości karty za pomocą tab.tabProperties, która zawiera informacje takie jak identyfikator, tytuł i pozycjonowanie karty.

Dostęp do treści tekstowych na karcie

Rzeczywista treść dokumentu na karcie jest widoczna jakotab.documentTab. Wszystkie wspomniane pola treści tekstowych są dostępne za pomocą tab.documentTab. 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 Tab. Dostęp do wszystkich kart w dokumencie wymaga przejścia przez „drzewo” kart podrzędnych. Weź pod uwagę na przykład dokument, który zawiera hierarchię kart w ten sposób:

Aby pobrać dane Body z karty 3.1.2, należy otworzyć document.tabs[2].childTabs[0].childTabs[1].documentTab.body. W następującej sekcji znajdziesz przykładowe bloki kodu, które zawierają przykładowy kod do iteracji po 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 zwracane są nie wszystkie treści karty. Deweloperzy powinni zaktualizować kod, aby uzyskać dostęp do wszystkich kart. Metoda documents.get udostępnia parametr includeTabsContent, który umożliwia skonfigurowanie, czy w odpowiedzi mają być uwzględnione treści ze wszystkich kart.

• Jeśli wartość includeTabsContent to 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 parametru includeTabsContent, pola tekstowe w zasobie Document (np. document.body) zostaną wypełnione tylko treściami 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 utworzony pusty dokument. Zwrócony zasób Document wypełni pustą zawartość dokumentu zarówno w polach treści tekstowych dokumentu, jak i w document.tabs.

document.batchUpdate

Każdy element Request zawiera sposób określania kart, na których ma zostać zastosowana aktualizacja. Jeśli nie określisz karty, domyślnie zostanie użyty tag Request, który w większości przypadków zostanie zastosowany do pierwszej karty w dokumencie. ReplaceAllTextRequest, DeleteNamedRangeRequesti ReplaceNamedRangeContentRequestto 3 specjalne żądania, które domyślnie zostaną zastosowane do wszystkich kart.

Szczegółowe informacje znajdziesz w dokumentacji Request.

Zmiany linków wewnętrznych

Użytkownicy mogą tworzyć wewnętrzne linki do kart, zakładek i nagłówków w dokumencie. Wraz z wprowadzeniem funkcji kart pola link.bookmarkId i link.headingId w zasobach Link nie mogą już reprezentować zakładki ani nagłówka na konkretnej karcie w dokumencie.

Deweloperzy powinni zaktualizować kod, aby używać funkcji link.bookmark i link.heading w operacjach odczytu i zapisu. Zawierają one linki wewnętrzne za pomocą obiektów BookmarkLink i HeadingLink, z których każdy zawiera identyfikator zakładki lub zaznaczenia oraz identyfikator karty, na której się ona znajduje. Dodatkowo link.tabId udostępnia linki wewnętrzne do kart.

Treść linku w odpowiedzi documents.get 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. Stare pola nie będą już używane.
• Jeśli nie podasz wartości includeTabsContent, w dokumentach zawierających jedną kartę wszystkie wewnętrzne linki do zakładek lub nagłówków na tej karcie będą nadal widoczne 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 traktowana jako zakładka z bookmarkiem lub nagłówkiem. Jeśli nie określisz karty, zostanie uznana za pierwszą kartę w dokumencie.

Reprezentacja linku w formacie JSON zawiera bardziej szczegółowe informacje.

Typowe wzorce korzystania z kart

Poniższe przykłady kodu opisują różne sposoby interakcji z kartami.

odczytywać zawartość kart we wszystkich kartach w dokumencie;

Istniejący kod, który wykonywał tę czynność przed wprowadzeniem funkcji kart, można przenieść do obsługi kart, ustawiając parametr includeTabsContent na true, przechodząc hierarchię drzewa kart i wywołując metody gettera z Tab i DocumentTab zamiast z Document. Ten częściowy przykład kodu jest oparty na fragmencie kodu w sekcji Wyodrębnianie tekstu z dokumentu. Pokazuje on, jak wydrukować cały tekst z każdej karty w dokumencie. Ten kod przeszukiwania kart można dostosować do wielu innych zastosowań, w których nie ma znaczenia rzeczywista struktura 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) {
  ...
}

Czytanie treści karty na pierwszej karcie w dokumencie

Jest to podobne do odczytania 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

Ten częściowy przykład kodu pokazuje, jak ustawić kierowanie na konkretną kartę w Request. Ten kod jest oparty na przykładzie w przewodniku Wstawianie, usuwanie i przenoszenie tekstu.

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