Google Docs API की मदद से, दस्तावेज़ के किसी भी टैब से कॉन्टेंट ऐक्सेस किया जा सकता है.
टैब क्या होते हैं?
Google Docs में, टैब नाम की एक लेयर होती है. Docs में, उपयोगकर्ता एक ही दस्तावेज़ में एक या उससे ज़्यादा टैब बना सकते हैं. ठीक उसी तरह जैसे Sheets में टैब होते हैं. हर टैब का अपना टाइटल और आईडी होता है, जो यूआरएल में जोड़ा जाता है. किसी टैब में चाइल्ड टैब भी हो सकते हैं. ये ऐसे टैब होते हैं जो किसी दूसरे टैब के नीचे नेस्ट किए जाते हैं.
दस्तावेज़ के कॉन्टेंट को दस्तावेज़ संसाधन में दिखाने के तरीके में बदलाव
पहले, दस्तावेज़ों में टैब का कोई कॉन्सेप्ट नहीं था. इसलिए, 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 Docs में टैब प्रॉपर्टी और कॉन्टेंट को document.tabs
की मदद से ऐक्सेस किया जा सकता है. यह Tab
ऑब्जेक्ट की सूची होती है. इनमें से हर ऑब्जेक्ट में, ऊपर बताए गए सभी टेक्स्ट कॉन्टेंट फ़ील्ड होते हैं. बाद के सेक्शन में, इस बारे में कम शब्दों में जानकारी दी गई है. Tab JSON के तौर पर दिखाया गया डेटा भी ज़्यादा जानकारी देता है.
ऐक्सेस टैब की प्रॉपर्टी
tab.tabProperties
का इस्तेमाल करके टैब प्रॉपर्टी ऐक्सेस करें. इसमें टैब का आईडी, टाइटल, और पोज़िशन जैसी जानकारी शामिल होती है.
टैब में टेक्स्ट कॉन्टेंट ऐक्सेस करना
टैब में मौजूद दस्तावेज़ का असल कॉन्टेंट, tab.documentTab
के तौर पर दिखता है. ऊपर बताए गए सभी टेक्स्ट कॉन्टेंट फ़ील्ड को tab.documentTab
का इस्तेमाल करके ऐक्सेस किया जा सकता है.
उदाहरण के लिए, document.body
के बजाय, आपको
document.tabs[indexOfTab].documentTab.body
का इस्तेमाल करना चाहिए.
टैब की हैरारकी
चाइल्ड टैब, एपीआई में Tab
पर tab.childTabs
फ़ील्ड के तौर पर दिखाए जाते हैं. किसी दस्तावेज़ में सभी टैब ऐक्सेस करने के लिए, चाइल्ड टैब के "ट्री" को ट्रैवर्स करना ज़रूरी है. उदाहरण के लिए, ऐसे दस्तावेज़ पर विचार करें जिसमें टैब का क्रम इस तरह है:
टैब 3.1.2 से Body
को वापस पाने के लिए, आपको document.tabs[2].childTabs[0].childTabs[1].documentTab.body
को ऐक्सेस करना होगा. अगले सेक्शन में, सैंपल कोड ब्लॉक देखें. इसमें, किसी दस्तावेज़ के सभी टैब में एक से ज़्यादा बार इस्तेमाल करने के लिए सैंपल कोड दिया गया है.
तरीकों में बदलाव
टैब की सुविधा के आने के बाद, दस्तावेज़ के हर तरीके में कुछ बदलाव किए गए हैं. इन बदलावों की वजह से, आपको अपना कोड अपडेट करना पड़ सकता है.
documents.get
डिफ़ॉल्ट रूप से, सभी टैब का कॉन्टेंट नहीं दिखाया जाता. सभी टैब ऐक्सेस करने के लिए, डेवलपर को अपना कोड अपडेट करना चाहिए. documents.get
वाला तरीका, includeTabsContent
पैरामीटर दिखाता है. इसकी मदद से, यह कॉन्फ़िगर किया जा सकता है कि जवाब में सभी टैब का कॉन्टेंट दिया जाए या नहीं.
- अगर
includeTabsContent
कोtrue
पर सेट किया गया है, तोdocuments.get
तरीका,document.tabs
फ़ील्ड की जानकारी के साथDocument
संसाधन दिखाएगा.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
संसाधन में मौजूद link.bookmarkId
और link.headingId
फ़ील्ड, दस्तावेज़ के किसी टैब में बुकमार्क या हेडिंग को नहीं दिखा सकते.
डेवलपर को अपना कोड अपडेट करना चाहिए, ताकि वे पढ़ने और लिखने के ऑपरेशन में link.bookmark
और
link.heading
का इस्तेमाल कर सकें. ये BookmarkLink
और
HeadingLink
ऑब्जेक्ट का इस्तेमाल करके, इंटरनल लिंक दिखाते हैं. इनमें से हर ऑब्जेक्ट में, बुकमार्क या हेडिंग का आईडी और उस टैब का आईडी होता है जिसमें वह मौजूद होता है. इसके अलावा, link.tabId
टैब के इंटरनल लिंक दिखाता है.
includeTabsContent
पैरामीटर के हिसाब से, documents.get
रिस्पॉन्स के लिंक कॉन्टेंट में भी अंतर हो सकता है:
- अगर
includeTabsContent
कोtrue
पर सेट किया जाता है, तो सभी इंटरनल लिंकlink.bookmark
औरlink.heading
के तौर पर दिखेंगे. लेगसी फ़ील्ड का इस्तेमाल अब नहीं किया जाएगा. - अगर
includeTabsContent
नहीं दिया गया है, तो एक टैब वाले दस्तावेज़ों में, उस टैब में मौजूद बुकमार्क या हेडिंग के किसी भी इंटरनल लिंक कोlink.bookmarkId
औरlink.headingId
के तौर पर दिखाया जाता रहेगा. एक से ज़्यादा टैब वाले दस्तावेज़ों में, साइट के दूसरे पेज पर ले जाने वाले लिंकlink.bookmark
औरlink.heading
के तौर पर दिखेंगे.
document.batchUpdate
में, अगर किसी लेगसी फ़ील्ड का इस्तेमाल करके कोई इंटरनल लिंक बनाया जाता है, तो बुकमार्क या हेडिंग को Request
में बताए गए टैब आईडी से माना जाएगा. अगर कोई टैब नहीं दिया गया है, तो इसे दस्तावेज़ के पहले टैब से माना जाएगा.
लिंक के JSON काेड में दिखाए गए डेटा से ज़्यादा जानकारी मिलती है.
टैब के इस्तेमाल के सामान्य पैटर्न
यहां दिए गए कोड सैंपल में, टैब के साथ इंटरैक्ट करने के अलग-अलग तरीकों के बारे में बताया गया है.
दस्तावेज़ के सभी टैब का कॉन्टेंट पढ़ना
टैब की सुविधा उपलब्ध होने से पहले, ऐसा करने वाले मौजूदा कोड को टैब के साथ काम करने के लिए माइग्रेट किया जा सकता है. इसके लिए, includeTabsContent
पैरामीटर को true
पर सेट करें, टैब के ट्री के लेआउट को ट्रैवर्स करें, और Document
के बजाय, Tab
और DocumentTab
से गेट्टर मेथड को कॉल करें. यहां दिया गया कोड का कुछ हिस्सा, किसी दस्तावेज़ से टेक्स्ट निकालना सेक्शन में मौजूद स्निपेट पर आधारित है. इसमें, किसी दस्तावेज़ के हर टैब में मौजूद टेक्स्ट कॉन्टेंट को प्रिंट करने का तरीका बताया गया है. टैब के क्रम में आगे बढ़ने वाले इस कोड को, कई अन्य कामों के लिए इस्तेमाल किया जा सकता है. इनमें टैब के असल स्ट्रक्चर का ध्यान नहीं रखा जाता.
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(); }