在 Google 文档中，协作者可以提出建议，这些建议实际上是等待批准的延迟修改。
当您使用 documents.get 方法提取文档内容时，内容可能包含未解决的建议。如需控制 documents.get 如何表示建议，请使用可选的 SuggestionsViewMode 参数。此参数支持以下过滤条件：
- 使用
SUGGESTIONS_INLINE获取内容，以便文档中显示待删除或待插入的文本。 - 接受所有建议，以预览形式获取内容。
- 以预览形式获取内容，不显示建议，并拒绝所有建议。
如果您未提供 SuggestionsViewMode，Google 文档 API 会使用与当前用户的权限相符的默认设置。
建议和索引
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，它由 2 部分组成：
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 的样式特征才会包含在建议中。