Google 文档允许协作者通过撰写评论和提出建议来协作，这些评论和建议相当于等待批准的延迟编辑。
您可以使用该 API 在文档文本中内嵌查看建议的更改。 在开发者预览版中，您还可以通过编程方式读取、创建、回复、更新或删除评论和建议串。
当您使用 documents.get 方法提取文档内容时，该内容可能包含未解决的建议。如需控制 documents.get 表示建议的方式，请使用可选的 SuggestionsViewMode 参数。此参数支持以下过滤条件：
- 使用
SUGGESTIONS_INLINE获取内容，以便在文档中显示待删除或待插入的文本。 - 获取接受所有建议后的预览内容。
- 以预览形式获取内容，不显示建议，拒绝所有建议。
如果您未提供 SuggestionsViewMode，Google Docs API 会使用适合当前用户权限的默认设置。
如需控制在提取文档时是否包含评论，请使用可选的 commentsViewMode 参数。如果您将 commentsViewMode 设置为 COMMENTS_VIEW_MODE_INCLUDED，则还必须将 includeTabsContent 设置为 true。此外，如果您使用的字段掩码引用了 tabs 字段（或任何子字段），API 会隐式地将该请求视为您将 includeTabsContent 设置为 true。
建议和索引
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，则 ParagraphElement 的 startIndex 从 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] }
在上面的示例中，段落包含三个文本运行，分别从第 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）。
您还可以在 Post 对象中指定新的 assigneeEmail 来重新分配评论串。
以下示例回复了现有评论串：
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
以下示例用于解决评论串，无需提供内容：
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
以下 JSON 示例展示了如何重新分配评论串：
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"content": "Replying to the comment thread.",
"assigneeEmail": "user@example.com"
}
}
}
]
}
修改帖子
如需修改您撰写的帖子的文字内容，请使用 UpdateCommentPostRequest。
您必须指定线程 ID（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"
}
}
]
}
撰写建议和管理建议对话串
您可以将修改内容写成建议，而不是直接修改，并以编程方式接受、拒绝或删除建议线程。
执行涉及建议的批量更新时，您应监控潜在的部分失败情况。如需了解详情，请参阅评论和建议更新状态。
使用建议模式创建建议
如需将编辑内容作为建议应用，请在批量更新请求中将 WriteControl 对象的 writeMode 字段设置为 SUGGEST。请求中的所有更新都将作为建议进行处理。
{
"requests": [
{
"insertText": {
"text": "suggested insertion text",
"location": {
"index": 1
}
}
}
],
"writeControl": {
"writeMode": "SUGGEST"
}
}
建议模式下不受支持的请求
使用 WriteMode.SUGGEST 时，系统不支持以下请求类型，执行时会返回错误：
AddDocumentTabCreateNamedRangeDeleteFooterDeleteHeaderDeleteNamedRangeDeleteTabUpdateDocumentTabPropertiesUpdateTableColumnProperties
此外，您无法建议更改文档格式或页眉和页脚设置。在 UpdateDocumentStyle 中，不支持以下样式类型的建议：
documentFormatuseEvenPageHeaderFooteruseFirstPageHeaderFooter
接受、拒绝或删除建议对话串
您可以使用以下请求管理建议线程：
- 接受建议：使用
AcceptSuggestionRequest接受建议。您需要拥有该文档的编辑权限。 - 拒绝建议：使用
RejectSuggestionRequest拒绝建议。您需要对文档拥有编辑权限，或者成为建议的作者。 - 删除建议：使用
DeleteSuggestionRequest删除建议。这需要您是建议的作者。
以下示例接受建议线程：
{
"requests": [
{
"acceptSuggestion": {
"suggestionId": "suggestion_thread_id"
}
}
]
}
评论和建议更新状态
需要保存评论或建议串（例如插入评论、添加回复或提出建议）的请求可能会出现部分失败。在这些情况下，文档模型更改（例如文本插入或删除）可能已成功提交到 Google 文档模型，但关联的评论或建议可能无法保存。
您可以通过检查 BatchUpdateDocumentResponse 中的 commentUpdateState 字段来验证评论或建议更新是否已成功应用。
CommentUpdateState 中会返回以下状态：
NO_UPDATES_REQUESTED：批量操作中未请求任何评论或建议更新。ALL_SAVED：所有请求的评论或建议更新均已成功应用。ALL_FAILED_UNKNOWN_REASON：所有请求的评论或建议更新均未能保存，即使文档模型更改可能已提交。