استخدام الاقتراحات

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

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

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

في حال عدم تقديم SuggestionsViewMode، تستخدم واجهة برمجة تطبيقات "مستندات Google" إعدادًا تلقائيًا يتناسب مع امتيازات المستخدم الحالي.

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

من بين أسباب أهمية SuggestionsViewMode هو أنّ الفهارس في الاستجابة قد تختلف حسب ما إذا كانت هناك اقتراحات، كما هو موضّح أدناه.

محتوى يتضمن اقتراحات محتوى بدون اقتراحات 
{
 "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"
  }
 }
},


{
 "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.

لغة Java

السلسلة النهائية SUGGEST_mode = "PREVIEW_WITHOUT_توصيات"; مستند المستند = service.documents().get(DOCUMENT_ID).setSuggestionsViewMode(SUGGEST_Mode).execute();

لغة Python

SUGGEST_mode="PREVIEW_WITHOUT_توصيات" النتيجة = service.documents().get(documentId=DOCUMENT_ID, 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] }

في المثال أعلاه، تتكون الفقرة من 3 عمليات تشغيل للنص، بدءًا من الأسطر 6 و14 و50. فحص تنفيذ النص الأوسط:

  • السطر 16: هناك كائن suggestedTextStyleChanges.
  • السطر 18: يحدد textStyle تنسيقات مختلفة.
  • السطر 36: يذكر textStyleSuggestionState أن الجزء الغامق فقط من هذه المواصفات هو الاقتراح.
  • السطر 42: النمط المائل لتشغيل هذا النص هو جزء من المستند الحالي (ولا يتأثر بالاقتراح).

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