टिप्पणियों और सुझावों का इस्तेमाल करना

Google Docs में, साथ मिलकर काम करने वाले लोग टिप्पणियां लिखकर और सुझाव देकर सहयोग कर सकते हैं. ये सुझाव, बदलाव के तौर पर सेव हो जाते हैं और मंज़ूरी मिलने का इंतज़ार करते हैं.

दस्तावेज़ के टेक्स्ट में, सुझाए गए बदलावों को इनलाइन देखने के लिए, एपीआई का इस्तेमाल किया जा सकता है. डेवलपर प्रीव्यू में, टिप्पणियों और सुझावों के थ्रेड को प्रोग्राम की मदद से पढ़ा, बनाया, जवाब दिया, अपडेट किया या मिटाया भी जा सकता है.

`documents.get` तरीके का इस्तेमाल करके, दस्तावेज़ का कॉन्टेंट फ़ेच करने पर, कॉन्टेंट में ऐसे सुझाव शामिल हो सकते हैं जिन पर अब तक कोई कार्रवाई नहीं की गई है.documents.get को कंट्रोल करने के लिए, documents.get से सुझावों को दिखाने के तरीके को कंट्रोल करने के लिए, ज़रूरी नहीं है SuggestionsViewMode पैरामीटर का इस्तेमाल करें. इस पैरामीटर के साथ, फ़िल्टर करने की ये शर्तें उपलब्ध हैं:

• SUGGESTIONS_INLINE के साथ कॉन्टेंट पाएं, ताकि दस्तावेज़ में ऐसा टेक्स्ट दिखे जिसे मिटाया जाना है या जोड़ा जाना है.
• सभी सुझावों को स्वीकार करके, कॉन्टेंट को झलक के तौर पर पाएं.
• सभी सुझावों को अस्वीकार करके, कॉन्टेंट को झलक के तौर पर पाएं. इसमें सुझाव शामिल नहीं होते.

अगर SuggestionsViewMode की वैल्यू नहीं दी जाती है, तो Google Docs API, डिफ़ॉल्ट सेटिंग का इस्तेमाल करता है. यह सेटिंग, मौजूदा उपयोगकर्ता के अधिकारों के हिसाब से होती है.

सुझाव और इंडेक्स

SuggestionsViewMode ज़रूरी है, क्योंकि जवाब में मौजूद इंडेक्स, सुझावों के आधार पर अलग-अलग हो सकते हैं. इसकी जानकारी यहां दी गई है.

{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 51,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 50,
          "textRun": {
           "content": "Suggested insertion",
           "suggestedInsertionIds": [
            "suggest.vcti8ewm4mww"
           ],
           "textStyle": {}
          }
         },
         {
          "startIndex": 50,
          "endIndex": 51,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 51,
       "endIndex": 81,
       "paragraph": {
        "elements": [
         {
          "startIndex": 51,
          "endIndex": 81,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 32,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 32,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 32,
       "endIndex": 62,
       "paragraph": {
        "elements": [
         {
          "startIndex": 32,
          "endIndex": 62,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

ऊपर दिए गए जवाब में, "सुझाव के बाद का टेक्स्ट" वाली लाइन वाले पैराग्राफ़ में, SuggestionsViewMode का इस्तेमाल करने पर दिखने वाले अंतर को दिखाया गया है. वैल्यू को SUGGESTIONS_INLINE पर सेट करने पर, startIndex का ParagraphElement 51 से शुरू होता है और endIndex 81 पर खत्म होता है. सुझावों के बिना, startIndex और endIndex की रेंज 32–62 होती है.

बिना सुझावों वाला कॉन्टेंट पाना

यहां दिए गए कोड के नमूने में, दस्तावेज़ को झलक के तौर पर पाने का तरीका बताया गया है. इसके लिए, SuggestionsViewMode पैरामीटर को PREVIEW_WITHOUT_SUGGESTIONS पर सेट करें. इससे, सभी सुझावों को अस्वीकार कर दिया जाता है. हालांकि, यह तब लागू होता है, जब दस्तावेज़ में सुझाव मौजूद हों.

final string SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS";
Document doc =
    service
        .documents()
        .get(DOCUMENT_ID)
        .setIncludeTabsContent(true)
        .setSuggestionsViewMode(SUGGEST_MODE)
        .execute();

SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS"
result = (
  service.documents()
  .get(
      documentId=DOCUMENT_ID,
      includeTabsContent=True,
      suggestionsViewMode=SUGGEST_MODE,
  )
  .execute()
)

SuggestionsViewMode पैरामीटर को शामिल न करने का मतलब है कि पैरामीटर की वैल्यू के तौर पर DEFAULT_FOR_CURRENT_ACCESS दिया गया है.

स्टाइल से जुड़े सुझाव

दस्तावेज़ों में स्टाइल से जुड़े सुझाव भी मिल सकते हैं. ये सुझाव, कॉन्टेंट में बदलाव के बजाय, फ़ॉर्मैटिंग और प्रज़ेंटेशन में बदलाव के लिए होते हैं.

टेक्स्ट जोड़ने या मिटाने के उलट, इनसे इंडेक्स में कोई बदलाव नहीं होता. हालांकि, ऐसा हो सकता है कि इनसे TextRun को छोटे-छोटे हिस्सों में बांटा जा सके. इनसे सिर्फ़ सुझाए गए स्टाइल में बदलाव के बारे में एनोटेशन जोड़े जाते हैं.

ऐसा ही एक एनोटेशन SuggestedTextStyle, है, जो दो हिस्सों से मिलकर बना होता है:

• textStyle, जिससे यह पता चलता है कि सुझाए गए बदलाव के बाद, टेक्स्ट को किस स्टाइल में दिखाया जाएगा. हालांकि, इससे यह पता नहीं चलता कि क्या बदला गया है.

• textStyleSuggestionState, जिससे यह पता चलता है कि सुझाव से textStyle के फ़ील्ड में किस तरह बदलाव होता है.

इसे दस्तावेज़ के टैब के इस एक्सट्रैक्ट में देखा जा सकता है. इसमें स्टाइल में बदलाव का एक सुझाव शामिल है:

[01] "paragraph": {
[02]    "elements": [
[03]        {
[04]            "endIndex": 106,
[05]            "startIndex": 82,
[06]            "textRun": {
[07]                "content": "Some text that does not ",
[08]                "textStyle": {}
[09]            }
[10]        },
[11]        {
[12]            "endIndex": 115,
[13]            "startIndex": 106,
[14]            "textRun": {
[15]                "content": "initially",
[16]                "suggestedTextStyleChanges": {
[17]                    "suggest.xymysbs9zldp": {
[18]                        "textStyle": {
[19]                            "backgroundColor": {},
[20]                            "baselineOffset": "NONE",
[21]                            "bold": true,
[22]                            "fontSize": {
[23]                                "magnitude": 11,
[24]                                "unit": "PT"
[25]                            },
[26]                            "foregroundColor": {
[27]                                "color": {
[28]                                    "rgbColor": {}
[29]                                }
[30]                            },
[31]                            "italic": false,
[32]                            "smallCaps": false,
[33]                            "strikethrough": false,
[34]                            "underline": false
[35]                        },
[36]                        "textStyleSuggestionState": {
[37]                            "boldSuggested": true,
[38]                            "weightedFontFamilySuggested": true
[39]                        }
[40]                    }
[41]                },
[42]                "textStyle": {
[43]                    "italic": true
[44]                }
[45]            }
[46]        },
[47]        {
[48]            "endIndex": 143,
[49]            "startIndex": 115,
[50]            "textRun": {
[51]                "content": " contain any boldface text.\n",
[52]                "textStyle": {}
[53]            }
[54]        }
[55]    ],
[56]    "paragraphStyle": {
[57]        "direction": "LEFT_TO_RIGHT",
[58]        "namedStyleType": "NORMAL_TEXT"
[59]    }
[60] }

ऊपर दिए गए नमूने में, पैराग्राफ़ में तीन टेक्स्ट रन शामिल हैं. ये लाइन 6, 14, और 50 से शुरू होते हैं. बीच वाले टेक्स्ट रन की जांच करें:

• लाइन 16: इसमें suggestedTextStyleChanges ऑब्जेक्ट है.
• लाइन 18: textStyle में अलग-अलग तरह की फ़ॉर्मैटिंग की जानकारी दी गई है.
• लाइन 36: textStyleSuggestionState से पता चलता है कि इस जानकारी में सिर्फ़ बोल्ड वाला हिस्सा, सुझाव के तौर पर दिया गया था.
• लाइन 42: इस टेक्स्ट रन की इटैलिक स्टाइलिंग, मौजूदा दस्तावेज़ का हिस्सा है. इस पर सुझाव का कोई असर नहीं पड़ा है.

textStyleSuggestionState में, सिर्फ़ वे स्टाइल फ़ीचर सुझाव का हिस्सा होते हैं जिनकी वैल्यू true पर सेट होती है.

टिप्पणियां बनाना और मैनेज करना

`documents.batchUpdate` तरीके का इस्तेमाल करके, टिप्पणियां और जवाब जोड़े जा सकते हैं. साथ ही, टिप्पणियों में बदलाव किया जा सकता है और टिप्पणियां या जवाब मिटाए जा सकते हैं .

टिप्पणियों या सुझावों से जुड़े बैच अपडेट करते समय, आपको आंशिक तौर पर होने वाली गड़बड़ियों पर नज़र रखनी चाहिए. ज़्यादा जानकारी के लिए, टिप्पणी और सुझाव के अपडेट की स्थिति देखें.

कोई टिप्पणी जोड़ना

टिप्पणी का थ्रेड जोड़ने के लिए, InsertCommentRequest ऑब्जेक्ट का इस्तेमाल करें. आपको टिप्पणी का टेक्स्ट कॉन्टेंट और ऐंकर की जगह (जैसे, कोई रेंज) देनी होगी, जहां टिप्पणी अटैच की गई है.

यहां दिए गए JSON के उदाहरण में, तय की गई रेंज में, बिना असाइन की गई टिप्पणी का थ्रेड जोड़ा गया है:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added via the API.",
        "range": {
          "startIndex": 10,
          "endIndex": 25
        }
      }
    }
  ]
}

assigneeEmailAddress फ़ील्ड में, ईमेल पता डालकर किसी टिप्पणी को किसी खास उपयोगकर्ता को असाइन किया जा सकता है:

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review this paragraph.",
        "assigneeEmailAddress": "user@example.com",
        "range": {
          "startIndex": 10,
          "endIndex": 25
        }
      }
    }
  ]
}

कोई जवाब जोड़ना या कार्रवाई करना

किसी टिप्पणी या सुझाव के थ्रेड का जवाब देने या किसी थ्रेड को हल करने या फिर से खोलने के लिए, AddCommentReplyRequest का इस्तेमाल करें.

किसी जवाब को Post ऑब्जेक्ट के तौर पर दिखाया जाता है. Post ऑब्जेक्ट में, जवाब का content शामिल होता है. साथ ही, इसमें ज़रूरत के हिसाब से commentAction (थ्रेड को RESOLVE या REOPEN करने के लिए) तय किया जा सकता है.

यहां दिए गए नमूने में, मौजूदा टिप्पणी के थ्रेड का जवाब दिया गया है:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

यहां दिए गए नमूने में, टिप्पणी के थ्रेड को हल किया गया है. इसके लिए, कॉन्टेंट की ज़रूरत नहीं होती:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "commentAction": "RESOLVE"
        }
      }
    }
  ]
}

किसी पोस्ट में बदलाव करना

अपनी लिखी गई किसी पोस्ट के टेक्स्ट कॉन्टेंट में बदलाव करने के लिए, UpdateCommentPostRequest का इस्तेमाल करें. आपको थ्रेड की आईडी (commentId या suggestionId), उस पोस्ट की postId बतानी होगी जिसमें आपको बदलाव करना है. साथ ही, नया सादा टेक्स्ट content भी बताना होगा.

ध्यान दें कि सुझाव के थ्रेड की मुख्य पोस्ट में बदलाव नहीं किया जा सकता. ऐसा इसलिए, क्योंकि ये पोस्ट, सुझाव मोड में किए गए बदलावों से जनरेट होती हैं.

{
  "requests": [
    {
      "updateCommentPost": {
        "commentId": "comment_thread_id",
        "postId": "post_id",
        "content": "This is the updated comment text."
      }
    }
  ]
}

टिप्पणियां और जवाब मिटाना

• टिप्पणी का थ्रेड मिटाना: टिप्पणी का पूरा थ्रेड हटाने के लिए, DeleteCommentRequest का इस्तेमाल करें. टिप्पणी का थ्रेड सिर्फ़ तब मिटाया जा सकता है, जब आप थ्रेड की मुख्य पोस्ट के लेखक हों.
• कोई जवाब मिटाना: किसी खास जवाब वाली पोस्ट को मिटाने के लिए, DeleteCommentReplyRequest का इस्तेमाल करें. सिर्फ़ वे जवाब मिटाए जा सकते हैं जिन्हें आपने लिखा है. जवाब वाली ऐसी पोस्ट नहीं मिटाई जा सकती जिनमें कार्रवाइयां या असाइन किए गए लोग शामिल हों.

यहां दिए गए नमूने में, टिप्पणी का थ्रेड मिटाया गया है:

{
  "requests": [
    {
      "deleteComment": {
        "commentId": "comment_thread_id"
      }
    }
  ]
}

सुझाव लिखना और सुझावों के थ्रेड मैनेज करना

सीधे बदलाव करने के बजाय, बदलावों को सुझाव के तौर पर लिखा जा सकता है. साथ ही, सुझावों के थ्रेड को प्रोग्राम की मदद से स्वीकार, अस्वीकार या मिटाया जा सकता है.

सुझावों से जुड़े बैच अपडेट करते समय, आपको आंशिक तौर पर होने वाली गड़बड़ियों पर नज़र रखनी चाहिए. ज़्यादा जानकारी के लिए, टिप्पणी और सुझाव के अपडेट की स्थिति देखें.

सुझाव मोड का इस्तेमाल करके सुझाव बनाना

बदलावों को सुझाव के तौर पर लागू करने के लिए, बैच अपडेट के अनुरोध में WriteControl ऑब्जेक्ट के writeMode फ़ील्ड को SUGGEST पर सेट करें. अनुरोध में मौजूद सभी अपडेट को सुझाव के तौर पर प्रोसेस किया जाता है.

{
  "requests": [
    {
      "insertText": {
        "text": "suggested insertion text",
        "location": {
          "index": 1
        }
      }
    }
  ],
  "writeControl": {
    "writeMode": "SUGGEST"
  }
}

सुझाव मोड में, इन अनुरोधों को प्रोसेस नहीं किया जा सकता

WriteMode.SUGGEST का इस्तेमाल करने पर, अनुरोध के इन टाइप को प्रोसेस नहीं किया जा सकता. साथ ही, इनके लिए गड़बड़ी का मैसेज दिखेगा:

• AddDocumentTab
• CreateNamedRange
• DeleteFooter
• DeleteHeader
• DeleteNamedRange
• DeleteTab
• UpdateDocumentTabProperties
• UpdateTableColumnProperties

इसके अलावा, दस्तावेज़ के फ़ॉर्मैट या हेडर/फ़ुटर की सेटिंग में बदलाव के लिए सुझाव नहीं दिए जा सकते. UpdateDocumentStyle में, स्टाइल के इन टाइप के लिए सुझाव नहीं दिए जा सकते:

• documentFormat
• useEvenPageHeaderFooter
• useFirstPageHeaderFooter

सुझावों के थ्रेड स्वीकार, अस्वीकार या मिटाना

सुझावों के थ्रेड को इन अनुरोधों का इस्तेमाल करके मैनेज किया जा सकता है:

• सुझाव स्वीकार करना: सुझाव स्वीकार करने के लिए, AcceptSuggestionRequest का इस्तेमाल करें. इसके लिए, दस्तावेज़ में बदलाव करने का ऐक्सेस होना ज़रूरी है.
• सुझाव अस्वीकार करना: सुझाव अस्वीकार करने के लिए, RejectSuggestionRequest का इस्तेमाल करें. इसके लिए, दस्तावेज़ में बदलाव करने का ऐक्सेस होना ज़रूरी है. साथ ही, यह भी ज़रूरी है कि आप सुझाव के लेखक हों.
• सुझाव मिटाना: सुझाव मिटाने के लिए, DeleteSuggestionRequest का इस्तेमाल करें. इसके लिए, यह ज़रूरी है कि आप सुझाव के लेखक हों.

यहां दिए गए नमूने में, सुझाव के थ्रेड को स्वीकार किया गया है:

{
  "requests": [
    {
      "acceptSuggestion": {
        "suggestionId": "suggestion_thread_id"
      }
    }
  ]
}

टिप्पणी और सुझाव के अपडेट की स्थिति

ऐसे अनुरोधों में आंशिक तौर पर गड़बड़ियां हो सकती हैं जिनमें टिप्पणी या सुझाव के थ्रेड सेव करने की ज़रूरत होती है. जैसे, टिप्पणियां जोड़ना, जवाब जोड़ना या सुझाव देना. इन मामलों में, ऐसा हो सकता है कि दस्तावेज़ के मॉडल में किए गए बदलाव (जैसे, टेक्स्ट जोड़ना या मिटाना) Docs मॉडल में सेव हो जाएं. हालांकि, उनसे जुड़ी टिप्पणियां या सुझाव सेव न हो पाएं.

BatchUpdateDocumentResponse में, commentUpdateState फ़ील्ड की जांच करके यह पता लगाया जा सकता है कि टिप्पणी या सुझाव के अपडेट, सही तरीके से लागू हुए हैं या नहीं.

CommentUpdateState में ये स्थितियां दिखती हैं:

• NO_UPDATES_REQUESTED: बैच ऑपरेशन में, टिप्पणी या सुझाव के अपडेट का कोई अनुरोध नहीं किया गया.
• ALL_SAVED: टिप्पणी या सुझाव के अपडेट के सभी अनुरोध सही तरीके से लागू किए गए.
• ALL_FAILED_UNKNOWN_REASON: टिप्पणी या सुझाव के अपडेट के सभी अनुरोध सेव नहीं हो पाए. भले ही, Docs मॉडल में किए गए बदलाव सेव हो गए हों.