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

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

แท็บคืออะไร

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

การเปลี่ยนแปลงโครงสร้างของวิธีแสดงเนื้อหาเอกสารในทรัพยากรเอกสาร

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

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

เข้าถึงพร็อพเพอร์ตี้ของแท็บ

เข้าถึงพร็อพเพอร์ตี้ของแท็บโดยใช้ tab.tabProperties ซึ่งมีข้อมูลต่างๆ เช่น รหัส ชื่อ และตำแหน่งของแท็บ

เข้าถึงเนื้อหาข้อความภายในแท็บ

เนื้อหาเอกสารจริงภายในแท็บจะแสดงเป็น tab.documentTab ฟิลด์เนื้อหาข้อความทั้งหมดที่กล่าวถึงข้างต้นสามารถเข้าถึงได้โดยใช้ tab.documentTab เช่น คุณควรใช้ document.tabs[indexOfTab].documentTab.body แทน document.body

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

แท็บย่อยจะแสดงใน API เป็นฟิลด์ tab.childTabs ใน Tab การเข้าถึงแท็บทั้งหมด ในเอกสารต้องผ่าน "ทรี" ของแท็บย่อย ตัวอย่างเช่น พิจารณาเอกสารที่มีลำดับชั้นของแท็บดังนี้

UI ของ Tablist ที่มีแท็บระดับบนสุด 3 แท็บ ซึ่งบางแท็บมีแท็บย่อย

หากต้องการดึงข้อมูล Body จากแท็บ 3.1.2 คุณจะต้องเข้าถึง document.tabs[2].childTabs[0].childTabs[1].documentTab.body ดูบล็อกโค้ดตัวอย่างในส่วนถัดไป ซึ่งมีโค้ดตัวอย่างสำหรับการวนซ้ำในแท็บทั้งหมดในเอกสาร

การเปลี่ยนแปลงวิธีการ

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

documents.get

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

  • หากตั้งค่า includeTabsContent เป็น true เมธอด documents.get จะแสดงทรัพยากร Document ที่มี ฟิลด์ document.tabs ที่มีข้อมูล ระบบจะปล่อยให้ช่องข้อความทั้งหมดใน document (เช่น document.body) ว่างไว้
  • หากไม่ได้ระบุ includeTabsContent ระบบจะป้อนข้อมูลฟิลด์ข้อความในทรัพยากร Document (เช่น document.body) ด้วยเนื้อหาจากแท็บแรกเท่านั้น ฟิลด์ document.tabs จะว่างเปล่าและระบบจะไม่แสดงเนื้อหาจากแท็บอื่นๆ

documents.create

เมธอด documents.create จะแสดงผลทรัพยากร Document ที่แสดงถึงเอกสารเปล่าที่สร้างขึ้น ทรัพยากร Document ที่แสดงผลจะ ป้อนข้อมูลเนื้อหาเอกสารที่ว่างเปล่าทั้งในฟิลด์เนื้อหาข้อความของเอกสาร และ document.tabs

document.batchUpdate

แต่ละ Request รายการจะมีวิธีระบุแท็บที่จะใช้การอัปเดต โดยค่าเริ่มต้น หากไม่ได้ระบุแท็บ ระบบจะใช้ Request กับแท็บแรกในเอกสารในกรณีส่วนใหญ่ ReplaceAllTextRequest DeleteNamedRangeRequest และ ReplaceNamedRangeContentRequest เป็นคำขอพิเศษ 3 รายการที่จะมีผลกับทุกแท็บโดยค่าเริ่มต้นแทน

ดูรายละเอียดได้ที่เอกสารประกอบของ Request

ผู้ใช้สามารถสร้างลิงก์ภายในไปยังแท็บ บุ๊กมาร์ก และส่วนหัวในเอกสารได้ เมื่อเปิดตัวฟีเจอร์แท็บแล้ว ฟิลด์ link.bookmarkId และ link.headingId ในแหล่งข้อมูล Link จะไม่สามารถแสดงบุ๊กมาร์กหรือส่วนหัวในแท็บใดแท็บหนึ่งในเอกสารได้อีกต่อไป

นักพัฒนาแอปควรอัปเดตโค้ดเพื่อใช้ link.bookmark และ link.heading ในการดำเนินการอ่านและเขียน โดยจะแสดงลิงก์ภายในโดยใช้ออบเจ็กต์ BookmarkLink และ HeadingLink ซึ่งแต่ละออบเจ็กต์จะมีรหัสของที่คั่นหน้าหรือหัวข้อ และรหัสของแท็บ ที่อยู่ที่คั่นหน้าหรือหัวข้อนั้น นอกจากนี้ link.tabId ยังแสดงลิงก์ภายในไปยังแท็บด้วย

เนื้อหาลิงก์ของคำตอบ documents.get อาจแตกต่างกันไปตามพารามิเตอร์ includeTabsContent ด้วย

  • หากตั้งค่า includeTabsContent เป็น true ระบบจะแสดงลิงก์ภายในทั้งหมดเป็น link.bookmark และ link.heading ระบบจะไม่ใช้ฟิลด์เดิมอีกต่อไป
  • หากไม่ได้ระบุ includeTabsContent ในเอกสารที่มีแท็บเดียว ลิงก์ภายในไปยังบุ๊กมาร์กหรือส่วนหัวภายในแท็บเดียวดังกล่าวจะยังคงแสดงเป็น link.bookmarkId และ link.headingId ใน เอกสารที่มีหลายแท็บ ลิงก์ภายในจะแสดงเป็น link.bookmark และ link.heading

ใน document.batchUpdate หากสร้างลิงก์ภายในโดยใช้ช่องเดิมช่องใดช่องหนึ่ง ระบบจะถือว่าบุ๊กมาร์กหรือ ส่วนหัวมาจากรหัสแท็บที่ระบุใน Request หากไม่ได้ระบุแท็บ ระบบจะถือว่ามาจากแท็บแรกในเอกสาร

การแสดง JSON ของลิงก์จะให้ข้อมูล โดยละเอียดเพิ่มเติม

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

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

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

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

Java

/** 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(<var>DOCUMENT_ID</var>).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/workspace/docs/api/samples/extract-text">Extract
 * the text from a document</a>.
 */
private static String readStructuralElements(List<StructuralElement> elements) {
  ...
}

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

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

Java

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

ส่งคำขออัปเดตแท็บแรก

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

Java

/** 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(<var>DOCUMENT_ID</var>).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(<var>DOCUMENT_ID</var>, body).execute();
}