Làm việc với tab

API Google Tài liệu cho phép bạn truy cập nội dung từ bất kỳ thẻ nào trong tài liệu.

Thẻ là gì?

Google Tài liệu có một lớp tổ chức được gọi là thẻ. Tài liệu cho phép người dùng tạo một hoặc nhiều thẻ trong một tài liệu, tương tự như cách các thẻ hiện có trong Trang tính. Mỗi thẻ có tiêu đề và mã nhận dạng (được thêm vào URL). Một thẻ cũng có thể có các thẻ con, đó là các thẻ được lồng bên dưới một thẻ khác.

Chúng tôi hiện đã hỗ trợ API cho thẻ con nhưng sắp ra mắt tính năng hỗ trợ giao diện người dùng. Bạn có thể xử lý các thẻ con trong mã của mình ngay hôm nay để khi tính năng hỗ trợ giao diện người dùng bắt đầu hoạt động bạn sẽ không phải cập nhật mã nữa.

Những thay đổi về cấu trúc đối với cách trình bày nội dung tài liệu trong Tài nguyên tài liệu

Trước đây, tài liệu không có khái niệm về thẻ, vì vậy, Tài nguyên Document trực tiếp chứa tất cả nội dung văn bản thông qua các trường sau:

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

Với hệ phân cấp cấu trúc bổ sung gồm các thẻ, các trường này không còn biểu thị nội dung văn bản từ tất cả các thẻ trong tài liệu theo đúng ngữ nghĩa. Chiến lược phát hành đĩa đơn nội dung dựa trên văn bản hiện được thể hiện trong một lớp khác. Thuộc tính thẻ và nội dung trong Google Tài liệu có thể truy cập được bằng document.tabs là danh sách Tab, mỗi đối tượng trong số đó chứa tất cả các trường nội dung văn bản nêu trên. Các phần sau sẽ cung cấp một thông tin tổng quan ngắn gọn; thời gian Biểu diễn dưới dạng JSON cho thẻ còn cung cấp thông tin chi tiết hơn.

Truy cập vào thuộc tính Thẻ

Truy cập vào các thuộc tính thẻ bằng tab.tabProperties! bao gồm các thông tin như mã nhận dạng, tiêu đề và vị trí của thẻ.

Truy cập vào nội dung văn bản trong một Thẻ

Nội dung tài liệu thực tế trong thẻ này được hiển thị dưới dạng tab.documentTab. Toàn bộ các trường nội dung văn bản nêu trên có thể truy cập được bằng tab.documentTab. Ví dụ: thay vì sử dụng document.body, bạn nên sử dụng document.tabs[indexOfTab].documentTab.body.

Hệ phân cấp thẻ

Các thẻ con được thể hiện trong API dưới dạng Trường tab.childTabs đang bật Tab. Truy cập tất cả các thẻ trong một tài liệu yêu cầu truyền tải "cây" trong số các thẻ con. Ví dụ: hãy cân nhắc tài liệu chứa hệ phân cấp thẻ như sau:

Để truy xuất Body tại Tab 3.1.2, bạn sẽ truy cập document.tabs[2].childTabs[0].childTabs[1].documentTab.body. Xem mẫu các khối mã ở phần sau. Phần này cung cấp mã mẫu để lặp lại trên tất cả các thẻ trong một tài liệu.

Các thay đổi đối với phương thức

Với sự ra mắt của thẻ, mỗi phương thức đối với tài liệu sẽ có một vài thay đổi có thể yêu cầu bạn cập nhật mã.

documents.get

Theo mặc định, một số nội dung trên thẻ không được trả về. Nhà phát triển nên cập nhật mã để truy cập tất cả các thẻ. Chiến lược phát hành đĩa đơn Phương thức documents.get sẽ hiển thị một Tham số includeTabsContent cho phép định cấu hình liệu nội dung từ tất cả các thẻ được cung cấp trong phản hồi.

• Nếu bạn đặt includeTabsContent thành true, Phương thức documents.get sẽ trả về Tài nguyên Document có phần tử Đã điền vào trường document.tabs. Tất cả các trường văn bản đều nằm ngay trên document (ví dụ: document.body) sẽ được để trống.
• Nếu bạn không cung cấp includeTabsContent, thì các trường văn bản trong Tài nguyên Document (ví dụ: document.body) sẽ chỉ được điền nội dung từ thẻ đầu tiên. Trường document.tabs sẽ trống và nội dung từ các thẻ khác sẽ không được trả về.

documents.create

Phương thức documents.create trả về tài nguyên Document đại diện cho tài liệu trống đã được tạo. Được trả về Tài nguyên Document sẽ điền sẵn nội dung tài liệu trống trong cả trường nội dung văn bản của tài liệu lẫn document.tabs.

document.batchUpdate

Mỗi Request bao gồm một cách chỉ định các thẻ để áp dụng bản cập nhật. Theo mặc định, nếu bạn không chỉ định thẻ, thì trong hầu hết các trường hợp, Request sẽ được áp dụng cho thẻ đầu tiên trong tài liệu. ReplaceAllTextRequest! DeleteNamedRangeRequest, và ReplaceNamedRangeContentRequest là ba yêu cầu đặc biệt mà theo mặc định sẽ áp dụng cho tất cả các thẻ.

Tham khảo Request giây tài liệu cụ thể.

Các thay đổi đối với đường liên kết nội bộ

Người dùng có thể tạo các đường liên kết nội bộ đến thẻ, dấu trang và tiêu đề trong một tài liệu. Khi tính năng thẻ được ra mắt, các trường link.bookmarkId và link.headingId trong tài nguyên Link không còn thể đại diện cho một dấu trang hoặc tiêu đề trong một thẻ cụ thể trong tài liệu.

Nhà phát triển nên cập nhật mã nguồn để sử dụng link.bookmark và link.heading trong các thao tác đọc và ghi. Các thẻ này hiển thị các đường liên kết nội bộ bằng cách sử dụng các đối tượng BookmarkLink và HeadingLink, mỗi đối tượng chứa mã nhận dạng của dấu trang hoặc tiêu đề và mã nhận dạng của thẻ chứa dấu trang hoặc tiêu đề đó. Ngoài ra, link.tabId hiển thị các đường liên kết nội bộ đến các thẻ.

Đường liên kết đến nội dung của documents.get thì phản hồi cũng có thể khác nhau tuỳ thuộc vào thông số includeTabsContent:

• Nếu bạn đặt includeTabsContent thành true, thì mọi đường liên kết nội bộ sẽ hiển thị dưới dạng link.bookmark và link.heading. Các trường cũ sẽ không còn được sử dụng nữa.
• Nếu includeTabsContent không được cung cấp, thì trong các tài liệu có chứa thẻ đơn, mọi đường liên kết nội bộ đến dấu trang hoặc đề mục trong thẻ duy nhất đó tiếp tục hiển thị dưới dạng link.bookmarkId và link.headingId. Trong tài liệu chứa nhiều thẻ, các đường liên kết nội bộ sẽ hiển thị dưới dạng link.bookmark và link.heading.

Tại document.batchUpdate, nếu liên kết nội bộ được tạo bằng một trong các trường cũ, dấu trang hoặc tiêu đề sẽ được coi là từ ID thẻ được chỉ định trong Request. Nếu không có thẻ nào đã chỉ định, nó sẽ được xem là từ thẻ đầu tiên trong tài liệu.

Chiến lược phát hành đĩa đơn Nội dung biểu diễn dưới dạng JSON của đường liên kết cung cấp thông tin chi tiết hơn.

Dạng sử dụng phổ biến cho thẻ

Các mã mẫu sau đây mô tả nhiều cách tương tác với thẻ.

Đọc nội dung thẻ từ tất cả các thẻ trong tài liệu

Mã hiện có đã thực hiện việc này trước khi có thể di chuyển tính năng thẻ để hỗ trợ bằng cách đặt tham số includeTabsContent thành true, truyền tải hệ thống phân cấp cây thẻ và gọi phương thức getter tắt Tab và DocumentTab thay vì Document Một phần mã mẫu dựa trên đoạn mã tại Trích xuất văn bản từ tài liệu. Chương này cho biết cách in tất cả nội dung văn bản từ mọi thẻ trong một tài liệu. Thẻ này mã truyền tải này có thể được điều chỉnh cho nhiều trường hợp sử dụng khác không quan tâm đến cấu trúc thực tế của các thẻ.

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

Đọc nội dung thẻ từ thẻ đầu tiên trong tài liệu

Thao tác này tương tự như việc đọc tất cả các thẻ.

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

Đưa ra yêu cầu cập nhật thẻ đầu tiên

Mã mẫu một phần sau đây cho biết cách nhắm mục tiêu một thẻ cụ thể trong Request. Mã này dựa trên mẫu trong Hướng dẫn về Chèn, xoá và di chuyển văn bản.

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