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

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 ของรายการแท็บที่มีแท็บระดับบนสุด 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(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/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(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()));
}

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

ตัวอย่างโค้ดบางส่วนต่อไปนี้แสดงวิธีกำหนดเป้าหมายแท็บที่เฉพาะเจาะจงใน 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(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();
}