टैब के साथ कार्य करना

Google Docs API की मदद से, दस्तावेज़ के किसी भी टैब से कॉन्टेंट ऐक्सेस किया जा सकता है.

टैब क्या होते हैं?

Google Docs में, टैब नाम की एक लेयर होती है. Docs में, उपयोगकर्ता एक ही दस्तावेज़ में एक या उससे ज़्यादा टैब बना सकते हैं. यह सुविधा, Sheets में मौजूद टैब की तरह ही है. हर टैब का अपना टाइटल और आईडी होता है, जो यूआरएल में जोड़ा जाता है. किसी टैब में चाइल्ड टैब भी हो सकते हैं. ये ऐसे टैब होते हैं जो किसी दूसरे टैब के नीचे नेस्ट किए जाते हैं.

दस्तावेज़ के कॉन्टेंट को दस्तावेज़ संसाधन में दिखाने के तरीके में बदलाव

पहले, दस्तावेज़ों में टैब का कॉन्सेप्ट नहीं था. इसलिए, Document रिसॉर्स में सीधे तौर पर, इन फ़ील्ड के ज़रिए सारा टेक्स्ट कॉन्टेंट शामिल होता था:

टैब के स्ट्रक्चर की अतिरिक्त हैरारकी के साथ, ये फ़ील्ड अब दस्तावेज़ के सभी टैब के टेक्स्ट कॉन्टेंट को सेमैटिक तरीके से नहीं दिखाते. टेक्स्ट पर आधारित कॉन्टेंट अब अलग लेयर में दिखता है. 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();
}