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

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

وقتی از روش 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 است که از 2 بخش تشکیل شده است:

  • 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] }

در نمونه بالا، پاراگراف شامل 3 اجرای متن است که از خطوط 6، 14 و 50 شروع می شود. اجرای متن میانی را بررسی کنید:

  • خط 16: یک شیء suggestedTextStyleChanges وجود دارد.
  • خط 18: textStyle قالب بندی های مختلفی را مشخص می کند.
  • خط 36: textStyleSuggestionState به شما می گوید که فقط قسمت برجسته این مشخصات پیشنهاد بود.
  • خط 42: سبک مورب این متن اجرا شده بخشی از سند جاری است (و تحت تأثیر پیشنهاد قرار نمی گیرد).

فقط ویژگی‌های سبک که در textStyleSuggestionState روی true تنظیم شده‌اند، بخشی از پیشنهاد هستند.