التعامل مع التعليقات والاقتراحات

يتيح "مستندات Google" للمتعاونين العمل معًا من خلال كتابة التعليقات وتقديم الاقتراحات التي تعمل كتعديلات مؤجّلة تنتظر الموافقة.

يمكنك استخدام واجهة برمجة التطبيقات لعرض التغييرات المقترَحة بشكل مضمّن في نص المستند. يمكنك أيضًا قراءة سلاسل الردود على التعليقات والاقتراحات أو إنشاؤها أو الرد عليها أو تعديلها أو حذفها آليًا.

عند استخدام طريقة documents.get لجلب محتوى المستند، قد يتضمّن المحتوى اقتراحات لم يتم حلّها. للتحكّم في طريقة عرض documents.get للاقتراحات، استخدِم المَعلمة الاختيارية SuggestionsViewMode. تتوفّر شروط الفلترة التالية مع هذه المَعلمة:

• احصل على المحتوى باستخدام SUGGESTIONS_INLINE، وبالتالي يظهر النص الذي ينتظر إما الحذف أو الإدراج في المستند.
• الحصول على المحتوى كمعاينة مع قبول جميع الاقتراحات
• الحصول على المحتوى كمعاينة بدون اقتراحات، مع رفض جميع الاقتراحات

في حال عدم توفير SuggestionsViewMode، تستخدم واجهة Google Docs API إعدادًا تلقائيًا مناسبًا للأذونات الممنوحة للمستخدم الحالي.

للتحكّم في ما إذا كان سيتم تضمين التعليقات عند جلب مستند، استخدِم المَعلمة الاختيارية commentsViewMode. لا يتم عرض التعليقات إلا إذا تم عرض الاقتراحات مضمّنة. عند ضبط commentsViewMode، عليك أيضًا ضبط suggestionsViewMode على النحو التالي:

• إذا تم ضبط commentsViewMode على COMMENTS_VIEW_MODE_INCLUDED، يجب ضبط suggestionsViewMode على SUGGESTIONS_INLINE.
• إذا تم ضبط commentsViewMode على COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS، يجب ضبط suggestionsViewMode على SUGGESTIONS_INLINE أو DEFAULT_FOR_CURRENT_ACCESS.

في حال ضبط commentsViewMode على COMMENTS_VIEW_MODE_INCLUDED، عليك أيضًا ضبط includeTabsContent على true. في حال استخدام قناع حقل يشير إلى الحقل tabs (أو أي حقل فرعي)، ستتعامل واجهة برمجة التطبيقات ضِمنيًا مع الطلب كما لو أنّك ضبطت قيمة includeTabsContent على true.

الاقتراحات والفهارس

أحد أسباب أهمية 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: يشكّل نمط الخط المائل في هذا النص جزءًا من المستند الحالي(ولا يتأثّر بالاقتراح).

لا يشمل الاقتراح سوى ميزات الأسلوب التي تم ضبطها على true في textStyleSuggestionState.

إنشاء التعليقات وإدارتها

يمكنك إضافة تعليقات وردود وتعديلها وحذفها آليًا باستخدام طريقة 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 السلسلة).

يمكنك أيضًا إعادة تعيين سلسلة محادثات تعليق من خلال تحديد assigneeEmail جديد في الكائن Post.

في ما يلي نماذج ردود على سلسلة محادثات حالية:

{
  "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"
      }
    }
  ]
}

كتابة اقتراحات وإدارة سلاسل المحادثات الخاصة بالاقتراحات

يمكنك كتابة التعديلات كاقتراحات بدلاً من التعديلات المباشرة، وقبول سلاسل الاقتراحات أو رفضها أو حذفها آليًا.

عند إجراء تعديلات مجمّعة تتضمّن اقتراحات، عليك مراقبة الأخطاء الجزئية المحتملة. لمزيد من المعلومات، يُرجى الاطّلاع على حالة تحديث التعليقات والاقتراحات.

إنشاء اقتراحات باستخدام وضع "الاقتراح"

لتطبيق التعديلات كاقتراحات، اضبط الحقل writeMode الخاص بالكائن WriteControl على 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"
      }
    }
  ]
}

حالة تعديل التعليقات والاقتراحات

قد تحدث حالات إخفاق جزئي في الطلبات التي تتطلّب حفظ سلاسل المحادثات أو الاقتراحات (مثل إدراج التعليقات أو إضافة الردود أو تقديم الاقتراحات). في هذه الحالات، قد يتم حفظ تغييرات نموذج المستند (مثل عمليات إدراج أو حذف النصوص) بنجاح في نموذج "مستندات Google"، ولكن قد يتعذّر حفظ التعليقات أو الاقتراحات المرتبطة بها.

يمكنك التأكّد من تطبيق تعديلات التعليقات أو الاقتراحات بنجاح من خلال التحقّق من حقل commentUpdateState في BatchUpdateDocumentResponse.

يتم عرض الحالات التالية في CommentUpdateState:

• ‫NO_UPDATES_REQUESTED: لم يتم طلب أي تعديلات على التعليقات أو الاقتراحات في العملية المجمّعة.
• ALL_SAVED: تم تطبيق جميع التعديلات المطلوبة على التعليقات أو الاقتراحات بنجاح.
• ALL_FAILED_UNKNOWN_REASON: تعذّر حفظ جميع التعديلات المطلوبة على التعليقات أو الاقتراحات، على الرغم من أنّه قد تم تنفيذ تغييرات نموذج "مستندات Google".