使用註解和建議

協作者可以在 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 時，系統不支援下列要求類型，且會傳回錯誤：

  • AddDocumentTab
  • CreateNamedRange
  • DeleteFooter
  • DeleteHeader
  • DeleteNamedRange
  • DeleteTab
  • UpdateDocumentTabProperties
  • UpdateTableColumnProperties

此外，您無法建議變更文件格式或頁首/頁尾設定。UpdateDocumentStyle 不支援下列樣式類型的建議：

  • documentFormat
  • useEvenPageHeaderFooter
  • useFirstPageHeaderFooter

接受、拒絕或刪除建議討論串

您可以使用下列要求管理建議主題：

  • 接受建議：使用 AcceptSuggestionRequest 接受建議。您必須具備文件的編輯權限。
  • 拒絕建議：使用 RejectSuggestionRequest 拒絕建議。您必須擁有文件的編輯權限，或是修訂建議的作者，才能執行這項操作。
  • 刪除建議：使用 DeleteSuggestionRequest 刪除建議。你必須是建議的作者，才能執行這項操作。

以下範例接受建議討論串：

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

註解和建議更新狀態

如果要求需要儲存留言或建議討論串 (例如插入留言、新增回覆或提出建議)，可能會部分失敗。在這些情況下，文件模型變更 (例如插入或刪除文字) 可能會成功提交至 Google 文件模型，但相關聯的註解或建議可能無法儲存。

如要確認留言或建議更新是否已順利套用，請檢查 BatchUpdateDocumentResponse 中的 commentUpdateState 欄位。

CommentUpdateState 會傳回下列狀態：

  • NO_UPDATES_REQUESTED：批次作業未要求更新任何註解或建議。
  • ALL_SAVED：所有要求更新的註解或建議都已成功套用。
  • ALL_FAILED_UNKNOWN_REASON：所有要求更新的註解或建議都無法儲存，即使文件模型變更可能已提交。