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

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 करने के लिए) भी तय किया जा सकता है. हालांकि, यह ज़रूरी नहीं है.

Post ऑब्जेक्ट में, नया assigneeEmail तय करके, टिप्पणी के थ्रेड को फिर से असाइन भी किया जा सकता है.

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

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

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

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

JSON के इस सैंपल में, टिप्पणी के थ्रेड को फिर से असाइन करने का तरीका दिखाया गया है:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "content": "Replying to the comment thread.",
          "assigneeEmail": "user@example.com"
        }
      }
    }
  ]
}

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

अपनी लिखी गई किसी पोस्ट के टेक्स्ट कॉन्टेंट में बदलाव करने के लिए, 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 मॉडल में बदलाव सेव हो गए हों.