Como trabalhar com guias

A API Google Docs permite acessar o conteúdo em qualquer guia no documento.

O que são guias?

O Documentos Google apresenta uma camada organizacional chamada guias. No app Documentos, os usuários podem criar uma ou mais guias em um único documento, parecido com as guias atuais no Planilhas. Cada guia tem o próprio título e ID (incluídos no URL). Uma guia também pode ter guias secundárias, que são guias aninhadas abaixo de outra guia.

O suporte da API para as guias secundárias já está disponível, mas o suporte à interface do usuário estará disponível em breve. É possível lidar com guias secundárias no seu código hoje para que, quando o suporte à interface for iniciado, não será necessário fazer outras atualizações no código.

Mudanças estruturais na forma como o conteúdo do documento é representado no recurso "Document"

No passado, os documentos não tinham um conceito de guias, portanto a Document Recurso contido diretamente todo o conteúdo de texto por meio dos seguintes campos:

Com a hierarquia estrutural adicional das guias, esses campos não representam mais semanticamente o conteúdo de texto de todas as guias no documento. O o conteúdo baseado em texto agora é representado em uma camada diferente. Propriedades da guia e do conteúdo dos Documentos Google são acessíveis com document.tabs, que é uma lista de objetos Tab, cada um dos quais contém todos os campos de conteúdo de texto mencionados acima. As seções posteriores dão uma breve visão geral, as Representação JSON da guia também fornece informações mais detalhadas.

Propriedades da guia "Acesso"

Acessar as propriedades da guia usando tab.tabProperties, que inclui informações como ID, título e posicionamento da guia.

Acessar conteúdo de texto em uma guia

O conteúdo real do documento na guia é exposto como tab.documentTab Todas as os campos de conteúdo de texto mencionados acima podem ser acessados usando tab.documentTab. Por exemplo, em vez de usar document.body, use document.tabs[indexOfTab].documentTab.body.

Hierarquia de guias

As guias filhas são representadas na API como uma Campo tab.childTabs ativado Tab Acessar todas as guias em uma documento requer atravessar a "árvore" de guias secundárias. Por exemplo, considere um documento que contém uma hierarquia de guias, da seguinte maneira:

IU de lista de guias contendo três guias de nível superior, algumas das quais têm guias filhas

Para recuperar o Body da Guia 3.1.2, você acessaria document.tabs[2].childTabs[0].childTabs[1].documentTab.body. Ver o exemplo blocos de código na próxima seção, que fornece exemplos de código para iterar em todas as guias de um documento.

Mudanças nos métodos

Com a introdução das guias, cada um dos métodos do documento tem algumas mudanças que podem exigir a atualização do código.

documents.get

Por padrão, nem todo o conteúdo da guia é retornado. Os desenvolvedores precisam atualizar para acessar todas as guias. O O método documents.get expõe um includeTabsContent, que permite configurar se o conteúdo de todas as guias são fornecidas na resposta.

  • Se includeTabsContent for definido como true, o método documents.get vai retornar um recurso Document com o campo document.tabs preenchido. Todos os campos de texto diretamente em document (por exemplo, document.body) será deixado em branco.
  • Se includeTabsContent não for informado, os campos de texto do recurso Document (por exemplo, document.body) serão preenchidos apenas com conteúdo da primeira guia. O campo document.tabs estará vazio, e o conteúdo de outras guias não será retornado.

documents.create

O método documents.create retorna um recurso Document. que representa o documento vazio que foi criado. O O recurso Document vai preencher conteúdo vazio nos campos de conteúdo de texto do documento e document.tabs.

document.batchUpdate

Cada Request inclui uma maneira de especificar as guias às quais aplicar a atualização. Por padrão, se uma guia não for especificado, o Request vai na maioria os casos podem ser aplicados à primeira guia no documento. ReplaceAllTextRequest, DeleteNamedRangeRequest, e ReplaceNamedRangeContentRequest há três solicitações especiais que, por padrão, serão aplicadas a todas as guias.

Consulte o Requests a documentação para mais detalhes.

Os usuários podem criar links internos para guias, favoritos e títulos em um documento. Com a introdução do recurso de guias, os campos link.bookmarkId e link.headingId no recurso Link não podem mais representar um marcador ou título em uma guia específica no documento.

Os desenvolvedores devem atualizar o código para usar link.bookmark e link.heading em operações de leitura e gravação. Eles expõem links internos usando BookmarkLink e Objetos HeadingLink, cada um contendo o ID do favorito ou título e o ID da guia no qual está localizado Além disso, o link.tabId expõe links internos para guias.

Vincular conteúdo de um documents.get a resposta também pode variar dependendo do parâmetro includeTabsContent:

  • Se includeTabsContent for definido como true, todos os links internos serão expostos como link.bookmark e link.heading. Os campos legados não serão mais usados.
  • Se includeTabsContent não for fornecido, em documentos que contêm uma guia única, todos os links internos para favoritos ou títulos nessa guia única continuam sendo expostas como link.bookmarkId e link.headingId. Nos documentos contendo várias guias, os links internos serão expostos como link.bookmark e link.heading.

No document.batchUpdate, se um link interno for criado usando um dos campos legados, o favorito ou título será considerado como sendo do ID da guia especificado no Request Se nenhuma guia for especificada, ela será considerada da primeira guia no documento.

O A representação JSON do link fornece informações mais detalhadas.

Padrões de uso comuns de guias

Os exemplos de código a seguir descrevem várias maneiras de interagir com guias.

Ler o conteúdo de todas as guias do documento

O código existente que fez isso antes que o recurso de guias pudesse ser migrado para oferecer suporte a guias definindo o parâmetro includeTabsContent como true, percorrendo a hierarquia de guias e chamando métodos de getter de Tab e DocumentTab em vez de Document. O exemplo de código parcial a seguir é baseado no snippet em Extrair o texto de um documento. Mostra como imprimir todo o conteúdo de texto de cada guia de um documento. Esta guia o código de travessia pode ser adaptado para muitos outros casos de uso que não a estrutura real das guias.

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) {
  ...
}

Ler conteúdo da primeira guia no documento

Isso é semelhante à leitura de todas as guias.

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

Faça uma solicitação para atualizar a primeira guia

O exemplo de código parcial a seguir mostra como segmentar uma guia específica em um Request Este código é baseado na amostra Guia Inserir, excluir e mover texto.

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