協作者可以在 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"
}
}
]
}
撰寫建議和管理建議討論串
您可以將編輯內容寫成建議，而非直接編輯，並以程式輔助方式接受、拒絕或刪除建議討論串。
執行涉及建議的批次更新時，請監控可能發生的部分失敗。詳情請參閱「留言和建議更新狀態」。
使用建議模式建立建議
如要將編輯內容套用為建議，請在批次更新要求中，將 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：所有要求更新的註解或建議都無法儲存，即使文件模型變更可能已提交。