「註解」是使用者對檔案的意見回饋,例如讀者 文書處理文件,提供如何改寫句子的資訊。這裡共有兩個 留言類型:錨定註解和未錨定註解。錨點 評論與特定位置相關聯,例如 文件特定版本的文書處理文件。相反地 未錨定註解只會與文件建立關聯。
回覆會附加到留言中,代表使用者對 留言。Drive API 可讓使用者在當中新增註解和回覆 所建立的文件共通則有回覆的留言稱為 討論。
新增未錨定註解
如要在文件中加入未錨定註解,請呼叫 comments.create
方法,並使用 fileId
參數和
包含註解的 comments
資源。
註解會以純文字格式插入,但回應內文會提供
htmlContent
欄位包含可顯示的內容格式化。
在註解中新增回覆
如要在註解中新增回覆,請呼叫
replies.create
方法搭配註解。
fileId
參數和 replies
資源
包含回覆內容
系統會以純文字形式插入回覆,但回應主體提供
htmlContent
欄位包含可顯示的內容格式化。
在文件的最新修訂版本中加入錨定註解
新增註解時,建議錨定至檔案中的一個區域。一個
Anchor:定義註解中的檔案修訂版本和區域
參照。comments
資源會定義要使用的
anchor
欄位做為 JSON 字串。
如何新增錨定註解:
(選用) 呼叫
revisions.list
方法,藉此列出文件的所有revisionID
。建議您只在符合以下情況時執行這個步驟: 將註解固定到最新修訂版本以外的任何修訂版本。 如要使用最新修訂版本,請針對revisionID
使用head
。呼叫
comments.create
方法 搭配fileID
參數、comments
包含註解的資源,以及 JSON 錨定字串 (含有revisionID
(r
) 和區域 (a
)。
區域的定義方式取決於您處理的文件內容類型 。詳情請參閱「定義區域」。
定義區域
如前所述,JSON 錨定字串包含 revisionID
(r
) 和
區域 (a
)。區域 (a
) 是包含區域分類器的 JSON 陣列
指定註解錨定的格式和位置。分類器
可以是 2D 矩形圖片、文件中一行文字
或影片長度如要定義區域,請選取「region」(區域)
分類器,以便比對您要錨定的目標內容類型。適用對象
舉例來說,如果您的內容是文字,建議使用 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
時,UI 應會指出
是否已回覆留言舉例來說,應用程式可能會:
- 不允許進一步回覆,以及將先前的所有回覆和原始回覆調暗 留言。
- 隱藏已解決的註解。
刪除留言
使用 comments.delete
方法:
刪除留言。刪除註解時,雲端硬碟會標記
加註資源:"deleted": "true"
。
列出註解
使用 comments.list
方法列出
留言。如要在結果中包含已刪除的註解,請設定
includedDeleted
欄位改為 true
。