「註解」是使用者提供針對檔案的意見回饋,例如文字處理文件的讀取者,建議如何改寫句子。註解分為兩種類型:「錨定註解」和「未錨定註解」。錨定註解會與特定文件版本中的特定位置相關聯,例如文書處理文件中的句子。相反地,未錨定的註解只會與文件建立關聯。
回覆會附加到留言中,代表使用者對留言的回應。Drive API 可讓使用者在由應用程式建立的文件中新增註解和回覆。含有回覆的註解統稱為「討論」。
新增非錨定註解
如要在文件中加入未錨定的註解,請使用 fileId
參數呼叫 comments.create
方法,以及包含註解的 comments
資源。
註解會以純文字形式插入,但回應主體會提供 htmlContent
欄位,其中包含要顯示的內容格式。
在註解中新增回覆
如要在註解中新增回覆,請使用註解、fileId
參數呼叫 replies.create
方法,以及包含回覆的 replies
資源。
回覆會以純文字形式插入,但回應主體會提供 htmlContent
欄位,其中包含顯示格式以便顯示的內容。
在文件的最新版本中新增錨定註解
新增註解時,您可能會想要將其固定在檔案中的一個區域。「錨點」定義了註解參照的檔案修訂版本和地區。comments
資源將 anchor
欄位定義為 JSON 字串。
如何新增錨定註解:
(選用) 呼叫
revisions.list
方法,列出文件的每個revisionID
。只有在您要將註解錨定至最新修訂版本以外的任何修訂版本時,才需要執行這個步驟。如要使用最新修訂版本,請為revisionID
使用head
。使用
fileID
參數呼叫comments.create
方法、包含留言的comments
資源,以及包含revisionID
(r
) 和區域 (a
) 的 JSON 錨點字串。
定義區域的方式取決於您使用的文件內容類型。詳情請參閱「定義區域」。
定義區域
如前文所述,JSON 錨定字串包含 revisionID
(r
) 和區域 (a
)。區域 (a
) 是包含區域分類器的 JSON 陣列,用於指定註解的錨定格式和位置。分類器可能是圖片的 2D 矩形、文件中的一行文字,或影片的時間長度。如要定義區域,請選取與您嘗試錨定內容類型相符的區域分類器。舉例來說,如果內容是文字,就可以使用 txt
或 line
區域分類器。
如需 Drive API 中的區域分類器清單,請參閱區域分類器。
以下範例顯示 JSON 錨定字串,可將註解錨定在文件的兩個不同區域的行:
- 第一個區域從第 12 行 (
'n':12
) 開始,三行 ('l':3
) 延伸。 - 第二個區域僅涵蓋第 18 行 (
'n':18, 'l':1
)。
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
將 REVISION_ID 替換為 head
或特定修訂版本的 ID。
解決註解
註解獲得處理時,請使用 comment.update
方法,將 comments
資源中的 resolved
屬性設為 true
。
當應用程式將 resolved
屬性設為 true
時,使用者介面應會顯示註解已經處理。舉例來說,您的應用程式可能會:
- 禁止進一步回覆,並調暗先前所有回覆再加上原始註解。
- 隱藏已解決的註解。
刪除留言
使用 comments.delete
方法刪除註解。如果註解遭到刪除,雲端硬碟會將註解資源標示為 "deleted": "true"
。
清單註解
使用 comments.list
方法列出註解。如要在結果中納入已刪除的註解,請將 includedDeleted
欄位設為 true
。