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 อื่นๆ อีกมากมายที่ไม่สนใจโครงสร้างจริงของแท็บ
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(); }