با پیشنهادها کار کنید، با پیشنهادها کار کنید

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

وقتی از متد 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 تنظیم شده‌اند، بخشی از پیشنهاد هستند.