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
การเข้าถึงแท็บทั้งหมดในเอกสารจำเป็นต้องข้าม "ต้นไม้" ของแท็บย่อย
ตัวอย่างเช่น ลองพิจารณาเอกสารที่มีลำดับชั้นของแท็บดังต่อไปนี้:
หากต้องการเรียกดู 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(); }