Làm việc với tab

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

Thẻ là gì?

Tài liệu có một lớp tổ chứ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 Trang tính hiện có các thẻ. Mỗi thẻ có tiêu đề riêng và một mã nhận dạ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.

Truy cập vào thẻ

Bạn có thể truy cập vào các thuộc tính và nội dung của thẻ bằng Document.getTabs, phương thức này trả về danh sách Tab. Các phần sau đây cung cấp thông tin tổng quan ngắn gọn về lớp Tab. Tài liệu về lớp Thẻ cũng cung cấp thông tin chi tiết hơn.

Thuộc tính thẻ

Bạn có thể truy xuất các thuộc tính của thẻ bằng các phương thức như Tab.getId và Tab.getTitle.

Nội dung thẻ

Bạn có thể truy xuất nội dung tài liệu trong mỗi thẻ bằng Tab.asDocumentTab. Phần Thay đổi đối với cấu trúc Lớp tài liệu mô tả cách sử dụng phương thức này.

Hệ thống phân cấp thẻ

Các thẻ con được hiển thị trong Apps Script thông qua Tab.getChildTabs. Để truy cập vào nội dung từ tất cả các thẻ, bạn cần di chuyển qua "cây" thẻ con. Ví dụ: hãy xem xét một tài liệu chứa hệ thống phân cấp thẻ như sau:

Giao diện người dùng Tablist chứa 3 thẻ cấp cao nhất, một số thẻ có thẻ con

Để truy cập vào Thẻ 3.1.2, hãy làm như sau:

// Print the ID of Tab 3.1.2.
const doc = DocumentApp.getActiveDocument();
const tab = doc.getTabs()[2].getChildTabs()[0].getChildTabs()[1];
console.log(tab.getId());

Hãy xem các khối mã mẫu trong các phần sau để biết mã mẫu lặp lại trên tất cả các thẻ trong một tài liệu.

Các cách khác để truy xuất thẻ

Có 2 cách khác để truy xuất thẻ:

Document.getTab: Trả về Thẻ có mã nhận dạng đã chỉ định.
Document.getActiveTab: Trả về Thẻ đang hoạt động của người dùng. Chỉ hoạt động trong các tập lệnh được liên kết với một tài liệu. Các phần sau đây mô tả chi tiết hơn về vấn đề này.

Thay đổi đối với cấu trúc Lớp tài liệu

Trước đây, tài liệu không có khái niệm về thẻ, vì vậy, Lớp tài liệu hiển thị các phương thức để truy cập và sửa đổi trực tiếp nội dung văn bản của tài liệu. Các phương thức sau đây thuộc danh mục này:

Với hệ thống phân cấp cấu trúc bổ sung của các thẻ, các phương thức này không còn biểu thị ngữ nghĩa nội dung văn bản từ tất cả các thẻ trong tài liệu. Nội dung văn bản hiện sẽ được biểu thị trong một lớp khác. Bạn có thể truy cập vào tất cả các phương thức văn bản nêu trên thông qua DocumentTab.

Các phương thức hiện có này trên lớp Document sẽ truy cập hoặc sửa đổi nội dung từ thẻ đang hoạt động (trong các tập lệnh được liên kết với một tài liệu cụ thể) hoặc thẻ đầu tiên (nếu không có thẻ đang hoạt động).

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

Thay vì sử dụng các phương thức văn bản của Document, bạn nên sử dụng các phương thức có sẵn của lớp DocumentTab (có sẵn thông qua Tab.asDocumentTab phương thức). Ví dụ:

// Print the text from the body of the active tab.
const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();
const body = documentTab.getBody();
console.log(body.getText());

Thay đổi đối với lựa chọn của người dùng

Khái niệm về lựa chọn của người dùng chỉ có liên quan và chỉ có thể được sử dụng hoặc thay đổi bởi các tập lệnh được liên kết với một tài liệu.

Phương thức chọn văn bản

Lớp Document cung cấp các phương thức getter và setter để quản lý vị trí mà người dùng đang chọn trong văn bản, trong tài liệu đang hoạt động. Các phương thức này hoạt động trong bối cảnh của thẻ đang hoạt động của người dùng đang chạy tập lệnh.

Document.getCursor: Trả về vị trí con trỏ của người dùng trong thẻ đang hoạt động.
Document.getSelection: Trả về phạm vi lựa chọn của người dùng trong thẻ đang hoạt động.
Document.setCursor: Đặt vị trí con trỏ của người dùng trong tài liệu đang hoạt động. Nếu Vị trí nằm trong một thẻ không hoạt động, thì thẻ đang hoạt động của người dùng cũng sẽ chuyển sang thẻ được liên kết với Vị trí đó.
Document.setSelection: Đặt phạm vi lựa chọn của người dùng trong tài liệu đang hoạt động. Nếu Phạm vi nằm trong một thẻ không hoạt động, thì thẻ đang hoạt động của người dùng cũng sẽ chuyển sang thẻ được liên kết với Phạm vi đó.

Phương thức chọn thẻ và trường hợp sử dụng

Khi giới thiệu các thẻ, hãy lấy và đặt thẻ đang hoạt động của người dùng đang chạy tập lệnh. Sử dụng các phương thức sau:

Document.getActiveTab: Trả về Tab đang hoạt động của người dùng trong tài liệu đang hoạt động.
Document.setActiveTab: Đặt Tab đã chọn của người dùng trong tài liệu hiện tại thành thẻ có mã nhận dạng đã chỉ định.

"Lựa chọn" tổng thể của người dùng được tạo thành từ sự kết hợp của thẻ đang hoạt động cùng với vị trí con trỏ hiện tại hoặc phạm vi lựa chọn. Hai mẫu để làm việc với lựa chọn đang hoạt động là sửa đổi rõ ràng thẻ đang hoạt động của người dùng thành một thẻ cụ thể hoặc sử dụng thẻ đang hoạt động của người dùng.

Thay đổi rõ ràng thẻ đang hoạt động của người dùng bằng cách sử dụng Document.setActiveTab. Ngoài ra, việc gọi Document.setCursor hoặc Document.setSelection bằng Position hoặc Range từ một thẻ không hoạt động sẽ khiến thẻ đó mới hoạt động.

Nếu hành vi dự kiến của tập lệnh là sử dụng thẻ đang hoạt động của người dùng mà không thay đổi thẻ đó, thì Document.setActiveTab không cần thiết. Các phương thức Document.getCursor và Document.getSelection hoạt động trên thẻ đang hoạt động, dựa trên thẻ mà người dùng đang chạy tập lệnh.

Một tài liệu không hỗ trợ nhiều lựa chọn thẻ hoặc nhiều vị trí hoặc phạm vi trên nhiều thẻ. Do đó, việc sử dụng Document.setActiveTab sẽ xoá vị trí con trỏ hoặc phạm vi lựa chọn trước đó.

Phương thức vị trí và phạm vi cho một Thẻ cụ thể

Thẻ cụ thể mang lại ý nghĩa cho các khái niệm chọn văn bản của Position và Range. Vị trí con trỏ hoặc phạm vi lựa chọn chỉ có ý nghĩa nếu tập lệnh biết thẻ cụ thể mà vị trí hoặc phạm vi nằm trong đó.

Bạn có thể thực hiện việc này bằng cách sử dụng các phương thức DocumentTab.newPosition và DocumentTab.newRange, phương thức này tạo một Vị trí hoặc Phạm vi nhắm đến DocumentTab cụ thể mà phương thức được gọi từ đó. Ngược lại, Document.newPosition và Document.newRange tạo một Vị trí hoặc Phạm vi trong thẻ đang hoạt động (hoặc thẻ đầu tiên, nếu tập lệnh không được liên kết).

Hãy xem các khối mã mẫu trong các phần sau để biết mã mẫu dùng để làm việc với các lựa chọn.

Các mẫu sử dụng phổ biến cho thẻ

Các đoạn mã 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 tính năng thẻ có thể được di chuyển để hỗ trợ các thẻ bằng cách di chuyển qua cây thẻ và gọi các phương thức getter của Tab và DocumentTab thay vì Document. Đoạn mã mẫu sau đâ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 thẻ này cho nhiều trường hợp sử dụng khác mà không quan tâm đến cấu trúc thực tế của các thẻ.

/** Logs all text contents from all tabs in the active document. */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs. DocumentApp.openById('abc123456') can also
  // be used instead of DocumentApp.getActiveDocument().
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from each tab in the document.
  for (const tab of allTabs) {
    // Get the DocumentTab from the generic Tab object.
    const documentTab = tab.asDocumentTab();
    // Get the body from the given DocumentTab.
    const body = documentTab.getBody();
    // Get the body text and log it to the console.
    console.log(body.getText());
  }
}

/**
 * Returns a flat list of all tabs in the document, in the order
 * they would appear in the UI (i.e. top-down ordering). Includes
 * all child tabs.
 */
function getAllTabs(doc) {
  const allTabs = [];
  // Iterate over all tabs and recursively add any child tabs to
  // generate a flat list of Tabs.
  for (const tab of 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.
 */
function addCurrentAndChildTabs(tab, allTabs) {
  allTabs.push(tab);
  for (const childTab of tab.getChildTabs()) {
    addCurrentAndChildTabs(childTab, allTabs);
  }
}

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

Tương tự như việc đọc tất cả các thẻ.

/** 
 * Logs all text contents from the first tab in the active 
 * document. 
 */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs.
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from the first tab in the document.
  const firstTab = allTabs[0];
  // Get the DocumentTab from the generic Tab object.
  const documentTab = firstTab.asDocumentTab();
  // Get the body from the DocumentTab.
  const body = documentTab.getBody();
  // Get the body text and log it to the console.
  console.log(body.getText());
}

Cập nhật nội dung thẻ trong thẻ đầu tiên

Đoạn mã mẫu sau đây cho biết cách nhắm mục tiêu đến một thẻ cụ thể khi thực hiện các bản cập nhật.

/** Inserts text into the first tab of the active document. */
function insertTextInFirstTab() {
  // Get the first tab's body.
  const doc = DocumentApp.getActiveDocument();
  const firstTab = doc.getTabs()[0];
  const firstDocumentTab = firstTab.asDocumentTab();
  const firstTabBody = firstDocumentTab.getBody();

  // Append a paragraph and a page break to the first tab's body
  // section.
  firstTabBody.appendParagraph("A paragraph.");
  firstTabBody.appendPageBreak();
}

Cập nhật nội dung thẻ trong thẻ đang hoạt động hoặc thẻ đã chọn

Đoạn mã mẫu sau đây cho biết cách nhắm mục tiêu đến thẻ đang hoạt động khi thực hiện các bản cập nhật.

/**
 * Inserts text into the active/selected tab of the active
 * document.
 */
function insertTextInActiveTab() {
  // Get the active/selected tab's body.
  const doc = DocumentApp.getActiveDocument();
  const activeTab = doc.getActiveTab();
  const activeDocumentTab = activeTab.asDocumentTab();
  const activeTabBody = activeDocumentTab.getBody();

  // Append a paragraph and a page break to the active tab's body
  // section.
  activeTabBody.appendParagraph("A paragraph.");
  activeTabBody.appendPageBreak();
}

Đặt vị trí con trỏ hoặc phạm vi lựa chọn trong thẻ đang hoạt động

Đoạn mã mẫu sau đây cho biết cách cập nhật vị trí con trỏ hoặc phạm vi lựa chọn trong thẻ đang hoạt động của người dùng. Điều này chỉ có liên quan trong các tập lệnh được liên kết.

/**
 * Changes the user's selection to select all tables within the tab
 * with the provided ID.
 */
function selectAllTables(tabId) {
  const doc = DocumentApp.getActiveDocument();
  const tab = doc.getTab(tabId);
  const documentTab = tab.asDocumentTab();

  // Build a range that encompasses all tables within the specified
  // tab.
  const rangeBuilder = documentTab.newRange();
  const tables = documentTab.getBody().getTables();
  for (let i = 0; i < tables.length; i++) {
    rangeBuilder.addElement(tables[i]);
  }
  // Set the document's selection to the tables within the specified
  // tab. Note that this actually switches the user's active tab as
  // well.
  doc.setSelection(rangeBuilder.build());
}

Đặt thẻ đang hoạt động hoặc thẻ đã chọn

Đoạn mã mẫu sau đây cho biết cách thay đổi thẻ đang hoạt động của người dùng. Điều này chỉ có liên quan trong các tập lệnh được liên kết.

/**
 * Changes the user's selected tab to the tab immediately following
 * the currently selected one. Handles child tabs.
 *
 * Only changes the selection if there is a tab following the
 * currently selected one.
 */
function selectNextTab() {
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);
  const activeTab = doc.getActiveTab();

  // Find the index of the currently active tab.
  let activeTabIndex = -1;
  for (let i = 0; i < allTabs.length; i++) {
    if (allTabs[i].getId() === activeTab.getId()) {
      activeTabIndex = i;
    }
  }

  // Update the user's selected tab if there is a valid next tab.
  const nextTabIndex = activeTabIndex + 1;
  if (nextTabIndex < allTabs.length) {
    doc.setActiveTab(allTabs[nextTabIndex].getId());
  }
}

Làm việc với tab Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.