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

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

แท็บคืออะไร

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

เข้าถึงแท็บ

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

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

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

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

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

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

แท็บของบุตรหลานจะแสดงใน Google 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(tabId): แสดงผลแท็บที่มีรหัสที่ระบุ
• Document.getActiveTab(): แสดงแท็บที่ใช้งานอยู่ของผู้ใช้ ใช้ได้เฉพาะในสคริปต์ที่เชื่อมโยงกับเอกสาร ส่วนต่อๆ ไปจะอธิบายเรื่องนี้โดยละเอียด

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

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

• Document.addBookmark(position)
• Document.addFooter()
• Document.addHeader()
• Document.addNamedRange(name, range)
• Document.getBody()
• Document.getBookmark(id)
• Document.getBookmarks()
• Document.getFooter()
• Document.getFootnotes()
• Document.getHeader()
• Document.getNamedRangeById(id)
• Document.getNamedRanges()
• Document.getNamedRanges(name)
• Document.newPosition(element, offset)
• Document.newRange()

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

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

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

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

// 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(position): กำหนดตำแหน่งเคอร์เซอร์ของผู้ใช้ในเอกสารที่ใช้งานอยู่ หากตำแหน่งอยู่ในแท็บที่ไม่ได้ใช้งาน ระบบจะเปลี่ยนแท็บที่ใช้งานอยู่ของผู้ใช้ไปยังแท็บที่เชื่อมโยงกับตำแหน่งนั้นด้วย
• Document.setSelection(range): กำหนดช่วงการเลือกของผู้ใช้ในเอกสารที่ใช้งานอยู่ หากช่วงอยู่ในแท็บที่ไม่ได้ใช้งาน ระบบจะเปลี่ยนแท็บที่ใช้งานอยู่ของผู้ใช้ไปยังแท็บที่เชื่อมโยงกับช่วงนั้นด้วย

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

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

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

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

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

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

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

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

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

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

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

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

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

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

คุณสามารถย้ายข้อมูลโค้ดที่มีอยู่ซึ่งทำสิ่งนี้ก่อนฟีเจอร์แท็บเพื่อรองรับแท็บได้โดยการไปยังส่วนต่างๆ ของโครงสร้างแท็บและเรียกใช้เมธอด 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());
  }
}