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

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

แท็บคืออะไร

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

วันนี้การรองรับ API สำหรับแท็บย่อยพร้อมให้บริการแล้ว แต่จะรองรับ UI ในเร็วๆ นี้ คุณสามารถจัดการแท็บย่อยในโค้ดของคุณได้แล้ว เพื่อที่ว่าเมื่อมีการเปิดตัวการรองรับ UI คุณจะไม่ต้องอัปเดตโค้ดเพิ่มเติม

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

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

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

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

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

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

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

โปรดดู 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/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();
}