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 .
Создавайте и управляйте комментариями.
С помощью метода documents.batchUpdate вы можете программно добавлять комментарии и ответы, редактировать комментарии и удалять комментарии или ответы.
При выполнении пакетных обновлений, содержащих комментарии или предложения, следует отслеживать возможные частичные сбои. Дополнительную информацию см. в разделе «Статус обновления комментариев и предложений» .
Оставьте комментарий
Для вставки ветки комментариев используйте объект InsertCommentRequest . Необходимо указать текст комментария и точку привязки (например, диапазон), куда будет прикреплен комментарий.
Следующий пример JSON добавляет в указанный диапазон ветку комментариев, для которой не назначен ни один комментарий:
{
"requests": [
{
"insertComment": {
"content": "This is a comment added via the API.",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
Вы можете назначить комментарий конкретному пользователю, указав его адрес электронной почты в поле assigneeEmailAddress :
{
"requests": [
{
"insertComment": {
"content": "Please review this paragraph.",
"assigneeEmailAddress": "user@example.com",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
Добавить комментарий или предпринять действия
Чтобы ответить на комментарий или предложение, а также чтобы разрешить или возобновить обсуждение, используйте AddCommentReplyRequest .
Ответ представляется объектом Post . Объект Post содержит content ответа и может дополнительно указывать commentAction (для RESOLVE или REOPEN ветки обсуждения).
В приведенном ниже примере дается ответ на существующую ветку комментариев:
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
В следующем примере отображается ветка комментариев, для которой не требуется контент:
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
Редактировать сообщение
Чтобы отредактировать текстовое содержимое созданного вами сообщения, используйте UpdateCommentPostRequest . Необходимо указать идентификатор темы ( commentId или suggestionId ), postId сообщения, которое вы хотите отредактировать, и новое текстовое content .
Обратите внимание, что вы не можете редактировать заголовок сообщения в ветке предложений (поскольку они создаются в режиме редактирования предложений).
{
"requests": [
{
"updateCommentPost": {
"commentId": "comment_thread_id",
"postId": "post_id",
"content": "This is the updated comment text."
}
}
]
}
Удалять комментарии и ответы
- Удаление ветки комментариев: Чтобы удалить всю ветку комментариев, используйте
DeleteCommentRequest. Вы можете удалить ветку комментариев только в том случае, если являетесь автором заголовочного сообщения в этой ветке. - Удаление ответа: Чтобы удалить конкретный ответ, используйте
DeleteCommentReplyRequest. Вы можете удалять только ответы, которые вы написали. Вы не можете удалять ответы, содержащие действия или назначенных лиц.
Следующий пример удаляет ветку комментариев:
{
"requests": [
{
"deleteComment": {
"commentId": "comment_thread_id"
}
}
]
}
Пишите предложения и управляйте ветками обсуждений с предложениями.
Вы можете вносить правки в виде предложений, а не в виде прямых правок, и программно принимать, отклонять или удалять ветки с предложениями.
При выполнении пакетных обновлений, включающих предложения, следует отслеживать возможные частичные сбои. Дополнительную информацию см. в разделе «Статус обновления комментариев и предложений» .
Создавайте подсказки, используя режим предложений.
Чтобы вносить изменения в качестве предложений, установите для поля writeMode объекта WriteControl значение SUGGEST в вашем пакетном запросе на обновление. Все обновления в запросе будут обрабатываться как предложения.
{
"requests": [
{
"insertText": {
"text": "suggested insertion text",
"location": {
"index": 1
}
}
}
],
"writeControl": {
"writeMode": "SUGGEST"
}
}
Неподдерживаемые запросы в режиме подсказок
При использовании WriteMode.SUGGEST следующие типы запросов не поддерживаются и приведут к ошибке:
-
AddDocumentTab -
CreateNamedRange -
DeleteFooter -
DeleteHeader -
DeleteNamedRange -
DeleteTab -
UpdateDocumentTabProperties -
UpdateTableColumnProperties
Кроме того, вы не можете предлагать изменения формата документа или настроек верхних/нижних колонтитулов. В UpdateDocumentStyle предложения не поддерживаются для следующих типов стилей:
-
documentFormat -
useEvenPageHeaderFooter -
useFirstPageHeaderFooter
Принять, отклонить или удалить ветки с предложениями.
Вы можете управлять ветками предложений, используя следующие запросы:
- Принять предложение: Используйте
AcceptSuggestionRequest, чтобы принять предложение. Для этого необходимы права на редактирование документа. - Отклонить предложение: Используйте
RejectSuggestionRequest, чтобы отклонить предложение. Для этого необходимы права на редактирование документа или статус автора предложения. - Удаление предложения: Используйте
DeleteSuggestionRequestдля удаления предложения. Для этого необходимо быть автором предложения.
В приведенном ниже примере принимаются предложения по улучшению:
{
"requests": [
{
"acceptSuggestion": {
"suggestionId": "suggestion_thread_id"
}
}
]
}
Статус обновления комментариев и предложений
Запросы, требующие сохранения веток комментариев или предложений (например, вставка комментариев, добавление ответов или внесение предложений), могут частично завершаться с ошибкой. В таких случаях изменения в модели документа (например, вставка или удаление текста) могут быть успешно зафиксированы в модели Docs, но связанные с ними комментарии или предложения могут не сохраниться.
Проверить успешность применения обновлений комментариев или предложений можно, проверив поле commentUpdateState в объекте BatchUpdateDocumentResponse .
В CommentUpdateState возвращаются следующие состояния:
-
NO_UPDATES_REQUESTED: В пакетной операции не было запрошено никаких комментариев или предложений по обновлению. -
ALL_SAVED: Все запрошенные комментарии или предложения были успешно применены. -
ALL_FAILED_UNKNOWN_REASON: Все запрошенные обновления комментариев или предложений не удалось сохранить, даже несмотря на то, что изменения в модели документации, возможно, были зафиксированы.