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

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

แท็บคืออะไร

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

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

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

• document.body
• document.headers
• document.footers
• document.footnotes
• document.documentStyle
• document.suggestedDocumentStyleChanges
• document.namedStyles
• document.suggestedNamedStylesChanges
• document.lists
• document.namedRanges
• document.inlineObjects
• document.positionedObjects

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

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

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

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

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

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

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

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

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

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

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

/** 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 โค้ดนี้อิงตามตัวอย่างในคู่มือแทรก ลบ และย้ายข้อความ

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