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

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

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

عند استخدام طريقة 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();

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 فقط هي جزء من الاقتراح.