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

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

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

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

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

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

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

أحد أسباب أهمية 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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

في الردّ أعلاه، تعرض الفقرة التي تحتوي على السطر "Text following the suggestion" الفرق عند استخدام 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();

Python

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

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

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

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