处理建议

在 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 的样式特征才会包含在建议中。