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

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

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

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

في حال عدم تقديم SuggestionsViewMode، ستستخدم Google Docs API إعدادًا SuggestionsViewModeتلقائيًا مناسبًا لإمتيازات المستخدم الحالي.

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

من بين الأسباب التي تجعل 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.

JavaPython

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

في العيّنة أعلاه، تتألف الفقرة من 3 عمليات تشغيل نصية، بدءًا من السطرَين 6 و 14 و50. راجِع النص الأوسط:

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

إنّ ميزات الأنماط التي تم ضبطها على true في textStyleSuggestionState هي فقط التي تشكّل جزءًا من الاقتراح.