Работа с предложениями

Документы Google позволяют соавторам вносить предложения, которые по сути являются отложенными изменениями, ожидающими одобрения.

Когда вы используете метод documents.get для получения содержимого документа, оно может содержать неразрешенные предложения. Чтобы контролировать способ представления предложений в documents.get , используйте необязательный параметр SuggestionsViewMode . С этим параметром доступны следующие условия фильтрации:

  • Получите контент с помощью SUGGESTIONS_INLINE , чтобы в документе появился текст, ожидающий удаления или вставки.
  • Получите контент в виде предварительного просмотра со всеми принятыми предложениями.
  • Получите контент в виде предварительного просмотра, без предложений и отклонения всех предложений.

Если вы не укажете SuggestionsViewMode , API Документов 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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

В приведенном выше ответе абзац, содержащий строку «Текст после предложения», показывает разницу при использовании 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 , которая состоит из двух частей:

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

В приведенном выше примере абзац состоит из трех фрагментов текста, начиная со строк 6, 14 и 50. Проверьте средний фрагмент текста:

  • Строка 16: Предлагается объект suggestedTextStyleChanges .
  • Строка 18: textStyle определяет различное форматирование.
  • Строка 36: textStyleSuggestionState сообщает вам, что только жирная часть этой спецификации была предложением.
  • Строка 42: Курсив этого фрагмента текста является частью текущего документа (на него это предложение не влияет).

Частью предложения являются только те функции стиля, для которых в textStyleSuggestionState установлено значение true .