ทำงานกับแท็บ

Google Apps Script สำหรับ Google เอกสารช่วยให้คุณเข้าถึงเนื้อหาจากแท็บใดก็ได้ในเอกสาร

แท็บคืออะไร

Docs มีเลเยอร์การจัดระเบียบที่เรียกว่าแท็บ เอกสารช่วยให้ผู้ใช้สร้างแท็บอย่างน้อย 1 แท็บภายในเอกสารเดียวได้ ซึ่งคล้ายกับแท็บในชีตในปัจจุบัน แต่ละแท็บจะมีชื่อและรหัสของตัวเอง (ต่อท้ายใน URL) แท็บยังมีแท็บย่อยได้ด้วย ซึ่งเป็นแท็บที่ซ้อนอยู่ใต้แท็บอื่น

เข้าถึงแท็บ

เข้าถึงพร็อพเพอร์ตี้และเนื้อหาของแท็บได้ด้วย Document.getTabs ซึ่งจะแสดงรายการ Tab ส่วนต่อๆ ไปจะให้ภาพรวมโดยย่อของ Tab คลาส รวมถึงเอกสารประกอบของคลาส Tab ซึ่งจะให้ข้อมูลที่ละเอียดยิ่งขึ้น

คุณสมบัติของแท็บ

คุณเรียกข้อมูลพร็อพเพอร์ตี้ของแท็บได้โดยใช้วิธีต่างๆ เช่น Tab.getId และ Tab.getTitle

เนื้อหาของแท็บ

คุณสามารถดึงเนื้อหาของเอกสารภายในแต่ละแท็บได้โดยใช้ Tab.asDocumentTab ส่วนการเปลี่ยนแปลงโครงสร้างคลาสเอกสาร จะอธิบายวิธีใช้

ลำดับชั้นของแท็บ

แท็บของบุตรหลานจะแสดงใน Apps Script ผ่าน Tab.getChildTabs การเข้าถึงเนื้อหาจากแท็บทั้งหมดต้องมีการไปยังส่วนต่างๆ ของ "โครงสร้าง" ของแท็บย่อย ตัวอย่างเช่น พิจารณาเอกสารที่มีลำดับชั้นของแท็บดังนี้

หากต้องการเข้าถึงแท็บ 3.1.2 ให้ทำดังนี้

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

ดูบล็อกโค้ดตัวอย่างในส่วนท้ายๆ เพื่อดูโค้ดตัวอย่างที่วนซ้ำ ในแท็บทั้งหมดในเอกสาร

วิธีอื่นๆ ในการดึงแท็บ

คุณเรียกแท็บกลับมาได้อีก 2 วิธีดังนี้

• Document.getTab: แสดงผลแท็บที่มีรหัสที่ระบุ
• Document.getActiveTab: แสดงแท็บที่ใช้งานอยู่ของผู้ใช้ ใช้ได้เฉพาะในสคริปต์ที่เชื่อมโยงกับเอกสาร ส่วนต่อๆ ไปจะอธิบายเรื่องนี้โดยละเอียด

การเปลี่ยนแปลงโครงสร้างคลาสเอกสาร

ในอดีต เอกสารไม่มีแนวคิดเรื่องแท็บ ดังนั้นคลาสเอกสาร จึงแสดงเมธอดเพื่อเข้าถึงและแก้ไขเนื้อหาข้อความของเอกสารโดยตรง วิธีการต่อไปนี้อยู่ในหมวดหมู่นี้

• Document.addBookmark
• Document.addFooter
• Document.addHeader
• Document.addNamedRange
• Document.getBody
• Document.getBookmark
• Document.getBookmarks
• Document.getFooter
• Document.getFootnotes
• Document.getHeader
• Document.getNamedRangeById
• Document.getNamedRanges
• Document.getNamedRanges
• Document.newPosition
• Document.newRange

เมื่อมีลำดับชั้นโครงสร้างเพิ่มเติมของแท็บ วิธีการเหล่านี้จะไม่ แสดงเนื้อหาข้อความจากแท็บทั้งหมดในเอกสารอีกต่อไป ตอนนี้ข้อความ เนื้อหาจะแสดงในเลเยอร์อื่น และเข้าถึงวิธีการข้อความที่กล่าวถึงข้างต้นทั้งหมดได้ผ่าน DocumentTab

วิธีการที่มีอยู่เหล่านี้ในคลาส Document จะเข้าถึงหรือแก้ไขเนื้อหา จากแท็บที่ใช้งานอยู่ (ในสคริปต์ที่ผูกกับเอกสาร ใดเอกสารหนึ่ง) หรือแท็บแรก (หากไม่มีแท็บที่ใช้งานอยู่)

เข้าถึงเนื้อหาข้อความภายในแท็บที่เฉพาะเจาะจง

เราขอแนะนำให้ใช้เมธอดที่พร้อมใช้งานในคลาส DocumentTab แทน (ซึ่งพร้อมใช้งานผ่านเมธอด Tab.asDocumentTab ) แทนการใช้วิธีข้อความจาก Document เช่น

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

การเปลี่ยนแปลงการเลือกผู้ใช้

แนวคิดของการเลือกของผู้ใช้เกี่ยวข้องและใช้ได้เฉพาะกับสคริปต์ที่เชื่อมโยงกับเอกสารเท่านั้น

วิธีการเลือกข้อความ

คลาส Document มีตัวรับและตัวตั้งค่าเพื่อจัดการตำแหน่งในข้อความที่ผู้ใช้เลือกภายในเอกสารที่ใช้งานอยู่ เมธอดเหล่านี้ทำงานภายใน บริบทของแท็บที่ใช้งานอยู่ของผู้ใช้ที่เรียกใช้สคริปต์

• Document.getCursor: แสดงตำแหน่งเคอร์เซอร์ของผู้ใช้ในแท็บที่ใช้งานอยู่
• Document.getSelection: แสดงช่วงที่ผู้ใช้เลือกในแท็บที่ใช้งานอยู่
• Document.setCursor: กำหนดตำแหน่งเคอร์เซอร์ของผู้ใช้ในเอกสารที่ใช้งานอยู่ หากตำแหน่งอยู่ในแท็บที่ไม่ได้ใช้งาน ระบบจะเปลี่ยนแท็บที่ใช้งานอยู่ของผู้ใช้ไปยังแท็บที่เชื่อมโยงกับตำแหน่งนั้นด้วย
• Document.setSelection: กำหนดช่วงการเลือกของผู้ใช้ในเอกสารที่ใช้งานอยู่ หากช่วงอยู่ในแท็บที่ไม่ได้ใช้งาน ระบบจะเปลี่ยนแท็บที่ใช้งานอยู่ของผู้ใช้ไปยังแท็บที่เชื่อมโยงกับช่วงนั้นด้วย

วิธีการเลือกแท็บและกรณีการใช้งาน

เมื่อมีการเปิดตัวแท็บ ให้รับและตั้งค่าแท็บที่ใช้งานอยู่ของผู้ใช้ที่เรียกใช้สคริปต์ โดยใช้วิธีการต่อไปนี้

• Document.getActiveTab: แสดง Tab ที่ใช้งานอยู่ของผู้ใช้ในเอกสารที่ใช้งานอยู่
• Document.setActiveTab: ตั้งค่า Tab ที่ผู้ใช้เลือกในเอกสารปัจจุบันเป็นแท็บที่มี รหัสที่ระบุ

"การเลือก" แบบองค์รวมของผู้ใช้ประกอบด้วยแท็บที่ใช้งานอยู่ พร้อมกับตำแหน่งเคอร์เซอร์ปัจจุบันหรือช่วงการเลือก รูปแบบ 2 รูปแบบสำหรับการทำงานกับการเลือกที่ใช้งานอยู่คือการแก้ไขแท็บที่ใช้งานอยู่ของผู้ใช้เป็นแท็บที่เฉพาะเจาะจงอย่างชัดเจน หรือใช้แท็บที่ใช้งานอยู่ของผู้ใช้

เปลี่ยนแท็บที่ใช้งานของผู้ใช้อย่างชัดเจนโดยใช้ Document.setActiveTab หรือการเรียกใช้ Document.setCursor หรือ Document.setSelection ด้วย Position หรือ Range จากแท็บที่ไม่ได้ใช้งานจะทำให้แท็บนั้นใช้งานได้อีกครั้ง

หากลักษณะการทำงานที่ต้องการของสคริปต์คือการใช้แท็บที่ใช้งานอยู่ของผู้ใช้ โดยไม่ต้องเปลี่ยนแท็บ ก็ไม่จำเป็นต้องใช้ Document.setActiveTab เมธอด Document.getCursor และ Document.getSelection จะทำงานในแท็บที่ใช้งานอยู่ โดยอิงตามแท็บที่ผู้ใช้เรียกใช้ สคริปต์

เอกสารไม่รองรับการเลือกหลายแท็บหรือหลายตำแหน่งหรือช่วงในแท็บต่างๆ ดังนั้น การใช้ Document.setActiveTab จะล้างตำแหน่งเคอร์เซอร์หรือช่วงการเลือกก่อนหน้า

วิธีการระบุตำแหน่งและช่วงสำหรับแท็บที่เฉพาะเจาะจง

แท็บที่เฉพาะเจาะจงจะให้ความหมายแก่แนวคิดการเลือกข้อความของ Position และ Range ตำแหน่งเคอร์เซอร์หรือช่วงการเลือกจะมีความหมายก็ต่อเมื่อสคริปต์ทราบแท็บที่เฉพาะเจาะจงซึ่งตำแหน่งหรือช่วงอยู่ภายใน

ซึ่งทำได้โดยใช้เมธอด DocumentTab.newPosition และ DocumentTab.newRange ซึ่งสร้าง Position หรือ Range ที่กำหนดเป้าหมายไปยัง DocumentTab ที่เฉพาะเจาะจงซึ่งเมธอดนั้นเรียกใช้ ในทางตรงกันข้าม Document.newPosition และ Document.newRange จะสร้างตำแหน่งหรือช่วงภายในแท็บที่ใช้งานอยู่ (หรือแท็บแรก หากสคริปต์ไม่ได้ผูกไว้)

ดูบล็อกโค้ดตัวอย่างในส่วนท้ายๆ เพื่อดูโค้ดตัวอย่างสำหรับการทำงาน กับการเลือก

รูปแบบการใช้งานแท็บทั่วไป

ตัวอย่างโค้ดต่อไปนี้อธิบายวิธีต่างๆ ในการโต้ตอบกับแท็บ

อ่านเนื้อหาแท็บจากแท็บทั้งหมดในเอกสาร

คุณสามารถย้ายข้อมูลโค้ดที่มีอยู่ซึ่งทำสิ่งนี้ก่อนฟีเจอร์แท็บเพื่อรองรับแท็บได้โดยการข้ามผ่านโครงสร้างแท็บและเรียกใช้เมธอด Getter จาก Tab และ DocumentTab แทน Document ตัวอย่างโค้ดบางส่วนต่อไปนี้แสดงวิธี พิมพ์เนื้อหาข้อความทั้งหมดจากทุกแท็บในเอกสาร คุณสามารถปรับโค้ดการข้ามแท็บนี้ให้เหมาะกับกรณีการใช้งานอื่นๆ อีกมากมายที่ไม่สนใจ โครงสร้างที่แท้จริงของแท็บ

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

อ่านเนื้อหาแท็บจากแท็บแรกในเอกสาร

ซึ่งคล้ายกับการอ่านแท็บทั้งหมด

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

อัปเดตเนื้อหาแท็บในแท็บแรก

ตัวอย่างโค้ดบางส่วนต่อไปนี้แสดงวิธีกำหนดเป้าหมายแท็บที่เฉพาะเจาะจงเมื่อทำการอัปเดต

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

อัปเดตเนื้อหาแท็บในแท็บที่ใช้งานอยู่หรือแท็บที่เลือก

ตัวอย่างโค้ดบางส่วนต่อไปนี้แสดงวิธีกำหนดเป้าหมายแท็บที่ใช้งานอยู่เมื่อทำการอัปเดต

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

ตั้งค่าตำแหน่งเคอร์เซอร์หรือช่วงการเลือกในแท็บที่ใช้งานอยู่

ตัวอย่างโค้ดบางส่วนต่อไปนี้แสดงวิธีอัปเดตตำแหน่งเคอร์เซอร์หรือช่วงการเลือกภายในแท็บที่ใช้งานอยู่ของผู้ใช้ โดยจะเกี่ยวข้องกับสคริปต์ที่เชื่อมโยงเท่านั้น

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

ตั้งค่าแท็บที่ใช้งานอยู่หรือแท็บที่เลือก

ตัวอย่างโค้ดบางส่วนต่อไปนี้แสดงวิธีเปลี่ยนแท็บที่ใช้งานอยู่ของผู้ใช้ โดยจะเกี่ยวข้องกับสคริปต์ที่เชื่อมโยงเท่านั้น

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