با نظرات و پیشنهادات کار کنید

گوگل داکز به همکاران اجازه می‌دهد تا با نوشتن نظرات و ارائه پیشنهاداتی که به عنوان ویرایش‌های معوق منتظر تأیید عمل می‌کنند، با یکدیگر همکاری کنند.

شما می‌توانید از API برای مشاهده تغییرات پیشنهادی درون متنی سند استفاده کنید. در پیش‌نمایش توسعه‌دهندگان، می‌توانید به صورت برنامه‌نویسی شده، موضوعات نظرات و پیشنهادات را بخوانید، ایجاد کنید، پاسخ دهید، به‌روزرسانی کنید یا حذف کنید.

وقتی از متد documents.get برای دریافت محتوای سند استفاده می‌کنید، محتوا ممکن است شامل پیشنهادهای حل نشده باشد. برای کنترل نحوه نمایش پیشنهادها توسط documents.get ، از پارامتر اختیاری SuggestionsViewMode استفاده کنید. شرایط فیلتر زیر با این پارامتر در دسترس هستند:

  • با استفاده از SUGGESTIONS_INLINE محتوا را دریافت کنید، بنابراین متنی که در انتظار حذف یا درج است در سند ظاهر می‌شود.
  • محتوا را به عنوان پیش‌نمایش دریافت کنید و همه پیشنهادات پذیرفته شده را مشاهده کنید.
  • محتوا را به صورت پیش‌نمایش، بدون پیشنهاد، با تمام پیشنهادهای رد شده دریافت کنید.

اگر SuggestionsViewMode ارائه ندهید، 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 از ۵۱ شروع می‌شود و endIndex در ۸۱ متوقف می‌شود. بدون پیشنهادها، startIndex و endIndex از ۳۲ تا ۶۲ متغیر هستند.

دریافت محتوا بدون پیشنهاد

نمونه کد ناقص زیر نشان می‌دهد که چگونه می‌توان با تنظیم پارامتر 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] }

در نمونه بالا، پاراگراف شامل ۳ رشته متن است که از خطوط ۶، ۱۴ و ۵۰ شروع می‌شوند. رشته متن میانی را بررسی کنید:

  • خط ۱۶: یک شیء suggestedTextStyleChanges وجود دارد.
  • خط ۱۸: textStyle قالب‌بندی‌های مختلفی را مشخص می‌کند.
  • خط ۳۶: عبارت textStyleSuggestionState به شما می‌گوید که فقط قسمت پررنگ این مشخصات، پیشنهاد بوده است.
  • خط ۴۲: استایل‌بندی ایتالیک این متن بخشی از سند فعلی است (و تحت تأثیر پیشنهاد قرار نمی‌گیرد).

فقط ویژگی‌های سبکی که در 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"
      }
    }
  ]
}

نوشتن پیشنهادات و مدیریت موضوعات پیشنهادی

شما می‌توانید ویرایش‌ها را به عنوان پیشنهاد بنویسید، نه ویرایش‌های مستقیم، و به صورت برنامه‌نویسی شده رشته‌های پیشنهاد را بپذیرید، رد کنید یا حذف کنید.

هنگام انجام به‌روزرسانی‌های دسته‌ای شامل پیشنهادها، باید بر خرابی‌های جزئی احتمالی نظارت داشته باشید. برای اطلاعات بیشتر، به وضعیت به‌روزرسانی نظرات و پیشنهادها مراجعه کنید.

ایجاد پیشنهاد با استفاده از حالت پیشنهاد

برای اعمال ویرایش‌ها به عنوان پیشنهاد، فیلد 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"
      }
    }
  ]
}

وضعیت به‌روزرسانی نظرات و پیشنهادات

درخواست‌هایی که نیاز به ذخیره رشته‌های نظرات یا پیشنهادات دارند (مانند درج نظرات، اضافه کردن پاسخ‌ها یا ارائه پیشنهادات) ممکن است با شکست‌های جزئی مواجه شوند. در این موارد، تغییرات مدل سند (مانند درج یا حذف متن) ممکن است با موفقیت در مدل Docs ثبت شوند، اما نظرات یا پیشنهادات مرتبط ممکن است ذخیره نشوند.

شما می‌توانید با بررسی فیلد commentUpdateState در BatchUpdateDocumentResponse ، تأیید کنید که آیا به‌روزرسانی‌های نظر یا پیشنهاد با موفقیت اعمال شده‌اند یا خیر.

حالت‌های زیر در CommentUpdateState برگردانده می‌شوند:

  • NO_UPDATES_REQUESTED : هیچ به‌روزرسانی نظر یا پیشنهادی در عملیات دسته‌ای درخواست نشد.
  • ALL_SAVED : تمام به‌روزرسانی‌های درخواستی برای نظرات یا پیشنهادات با موفقیت اعمال شدند.
  • ALL_FAILED_UNKNOWN_REASON : تمام به‌روزرسانی‌های درخواست‌شده برای نظرات یا پیشنهادات ذخیره نشدند، حتی با اینکه ممکن است تغییرات مدل Docs ثبت شده باشند.