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ã riêng (được thêm vào URL). Một thẻ cũng có thể có thẻ con, là các thẻ được lồng bên dưới một thẻ khác.

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ệ thống phân cấp cấu trúc bổ sung của các thẻ, các trường này không còn đại diện về ngữ nghĩa cho nội dung văn bản của tất cả các thẻ trong tài liệu nữa. Nội dung dựa trên văn bản hiện được thể hiện trong một lớp khác. Bạn có thể truy cập vào thuộc tính và nội dung của thẻ trong Google Tài liệu bằng document.tabs. Đây là danh sách các đối tượng Tab, mỗi đối tượng 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 đây sẽ cung cấp thông tin tổng quan ngắn gọn; Biểu diễn JSON theo thẻ cũng cung cấp thêm thông tin chi tiết.

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

Truy cập vào các thuộc tính thẻ bằng cách sử dụ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 Thẻ

Nội dung tài liệu thực tế trong thẻ được hiển thị dưới dạng tab.documentTab. Bạn có thể truy cập vào tất cả các trường nội dung văn bản nêu trên 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ẻ

Thẻ con được biểu thị trong API dưới dạng trường tab.childTabs trên Tab. Để truy cập vào tất cả thẻ trong một tài liệu, bạn cần phải duyệt qua "cây" của các thẻ con. Ví dụ: hãy xem xét một tài liệu chứa hệ phân cấp thẻ như sau:

Để truy xuất Body từ Thẻ 3.1.2, bạn sẽ truy cập vào document.tabs[2].childTabs[0].childTabs[1].documentTab.body. Hãy xem các khối mã mẫu trong 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.

Thay đổi đối với phương thức

Với việc giới thiệu thẻ, mỗi phương thức tài liệu 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, không phải tất cả nội dung thẻ đều được trả về. Nhà phát triển nên cập nhật mã để truy cập vào tất cả các thẻ. Phương thức documents.get hiển thị một thông số includeTabsContent cho phép định cấu hình xem nội dung từ tất cả các thẻ có được cung cấp trong phản hồi hay không.

• Nếu includeTabsContent được đặt thành true, thì phương thức documents.get sẽ trả về một Tài nguyên Document có điền sẵn trường document.tabs. Tất cả các trường văn bản trực tiếp 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ề một Tài nguyên Document đại diện cho tài liệu trống đã tạo. Tài nguyên Document được trả về sẽ điền nội dung tài liệu trống vào cả trường nội dung văn bản của tài liệu cũng như document.tabs.

document.batchUpdate

Mỗi Request bao gồm một cách để chỉ định các thẻ cần á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à 3 yêu cầu đặc biệt sẽ áp dụng cho tất cả các thẻ theo mặc định.

Hãy tham khảo tài liệu về Request để biết thông tin chi tiết.

Thay đổi đối với đường liên kết nội bộ

Người dùng có thể tạo đường liên kết nội bộ đến các thẻ, dấu trang và tiêu đề trong 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ã để 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ẻ.

Nội dung liên kết của phản hồi documents.get cũng có thể thay đổi tuỳ thuộc vào tham số includeTabsContent:

• Nếu bạn đặt includeTabsContent thành true, tất cả đườ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 bạn không cung cấp includeTabsContent, thì trong các tài liệu chứa một thẻ duy nhất, mọi đường liên kết nội bộ đến dấu trang hoặc tiêu đề trong thẻ duy nhất đó sẽ tiếp tục hiển thị dưới dạng link.bookmarkId và link.headingId. Trong các 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.

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

Biểu diễn JSON của đường liên kết cung cấp thêm thông tin chi tiết.

Các mẫu 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ả thẻ trong tài liệu

Bạn có thể di chuyển mã hiện có đã thực hiện việc này trước khi có tính năng thẻ để hỗ trợ thẻ bằng cách đặt tham số includeTabsContent thành true, duyệt qua hệ phân cấp cây thẻ và gọi các phương thức getter từ Tab và DocumentTab thay vì Document. Mẫu mã một phần sau đây dựa trên đoạn mã tại phần 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. Bạn có thể điều chỉnh mã di chuyển qua thẻ này 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()));
}

Tạo yêu cầu cập nhật thẻ đầu tiên

Mẫu mã một phần sau đây cho thấy cách nhắm đến một thẻ cụ thể trong Request. Mã này dựa trên mẫu trong Hướng dẫn 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();
}