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

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

Вы можете использовать API для просмотра предложений, но не для их программного принятия, отклонения или создания.

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

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

Если вы не укажете SuggestionsViewMode , API Google Docs будет использовать настройку по умолчанию, соответствующую правам текущего пользователя.

Предложения и указатели

Одна из причин важности параметра 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 .

Java 

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: Курсивное написание этого фрагмента текста является частью текущего документа (и не затрагивается предложенным вариантом).

В подсказку включаются только те элементы стиля, для которых в параметре textStyleSuggestionState установлено значение true .