Google 文档允许协作者提出建议,这些建议实际上是延迟等待审批的修改。
当您使用 documents.get
方法提取文档内容时,内容可能包含未解析的建议。如需控制 documents.get
表示建议的方式,请使用可选的 SuggestionsViewMode
参数。此参数可用于以下过滤条件:
- 使用
SUGGESTIONS_INLINE
获取内容,使待删除或插入的文本出现在文档中。 - 获取内容预览,其中包含接受的所有建议。
- 以预览形式获取内容(不含建议),所有建议都会被拒绝。
如果您未提供 SuggestionsViewMode
,Google 文档 API 会使用适合当前用户权限的默认设置。
建议和索引
SuggestionsViewMode
非常重要的一个原因是,响应中的索引可能会根据是否有建议而有所不同,如下所示。
包含建议的内容 | 不含建议的内容 |
---|---|
{ "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" } } }, |
{ "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" } } }, |
在上面的响应中,包含“Text 遵循建议的文本”行的段落显示了使用 SuggestionsViewMode
时的差异。将该值设置为 SUGGESTIONS_INLINE
后,ParagraphElement
的 startIndex
从 51 开始,endIndex
从 81 开始。如果没有建议,则 startIndex
和 endIndex
的范围为 32-62。
在没有建议的情况下获取内容
以下部分代码示例展示了如何通过将 SuggestionsViewMode
参数设置为 PREVIEW_WITHOUT_SUGGESTIONS
来获得拒绝所有建议(如果有)的预览文档。
Java
最终字符串 SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS"; 文档 doc = service.documents().get(DOCUMENT_ID).setSuggestionsViewMode(SUGGEST_MODE).execute);
Python
SUGGEST_MODE="PREVIEW_WITHOUT_SUGGESTIONS" result = service.documents().get(documentId=DOCUMENT_ID, 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
的样式地图项。