使用评论和建议

借助 Google 文档，协作者可以通过撰写 评论和提出 建议进行协作，这些评论和建议充当待审批的延迟修改。

您可以使用 API 在文档文本中内嵌查看建议的更改。 在开发者预览版中，您还可以以编程方式读取、创建、回复、更新或删除评论和建议串。

当您使用 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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

在上面的响应中，包含“Text following the suggestion”这一行的段落显示了使用 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， 它由 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 的样式功能才是建议的一部分。

创建和管理评论

您可以使用 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。 您必须指定串 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"
      }
    }
  ]
}

撰写建议和管理建议串

您可以将修改撰写为建议，而不是直接修改，并以编程方式接受、拒绝或删除建议串。

执行涉及建议的批量更新时，您应监控潜在的部分失败。如需了解详情，请参阅评论和建议更新状态。

使用建议模式创建建议

如需将修改作为建议应用，请在批量更新请求中将 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

接受、拒绝或删除建议串

您可以使用以下请求管理建议串：

以下示例接受了建议串：

{
  "requests": [
    {
      "acceptSuggestion": {
        "suggestionId": "suggestion_thread_id"
      }
    }
  ]
}

评论和建议更新状态

需要保存评论或建议串（例如插入评论、添加回复或提出建议）的请求可能会遇到部分失败。在这些情况下，文档模型更改（例如文本插入或删除）可能会成功提交到 Google 文档模型，但关联的评论或建议可能无法保存。

您可以通过检查 commentUpdateState 中的 BatchUpdateDocumentResponse 字段，验证评论或建议更新是否已成功应用。

CommentUpdateState 中会返回以下状态：

  • NO_UPDATES_REQUESTED：批量操作中未请求任何评论或建议更新。
  • ALL_SAVED：所有请求的评论或建议更新都已成功应用。
  • ALL_FAILED_UNKNOWN_REASON：所有请求的评论或建议更新都未能保存，即使 Google 文档模型更改可能已提交。