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

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

แท็บคืออะไร

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

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

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

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

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

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

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

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

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

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

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

หากต้องการเรียกดู body จาก Tab 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.bookmark และ link.headingในการดำเนินการอ่านและเขียน โฆษณาดังกล่าวแสดงลิงก์ภายในโดยใช้ BookmarkLink และ ออบเจ็กต์ HeadingLink รายการ แต่ละรายการ ที่มีรหัสบุ๊กมาร์กหรือส่วนหัว และรหัสของแท็บที่บันทึก นิ้ว นอกจากนี้ link.tabId จะแสดงลิงก์ภายในให้แท็บต่างๆ เห็นด้วย

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

  • หากตั้งค่า includeTabsContent เป็น true ลิงก์ภายในทั้งหมดจะแสดง ในชื่อ link.bookmark และ link.heading ช่องเดิม (link.bookmarkId และ link.headingId) จะใช้งานไม่ได้อีกต่อไป
  • หากไม่ได้ระบุ 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();
}