title: “添加工作表注释” description: “使用 Aspose.Cells Cloud REST API（PUT /v3.0/cells/{name}/worksheets/{sheetName}/comments/{cellName}）向 Excel 工作表中的特定单元格添加注释。” keywords: “Aspose.Cells, 云 API, 添加工作表注释, Excel, 电子表格, 单元格注释” weight: 20 api_version: “v3.0”

添加工作表注释

使用 Aspose.Cells Cloud REST API 向 Excel 工作簿中工作表的特定单元格添加注释。

前提条件 / 身份验证

Authorization: Bearer <jwt token>

HTTP 请求

PUT https://api.aspose.cloud/v3.0/cells/{name}/worksheets/{sheetName}/comments/{cellName}

路径参数

名称 类型 是否必需 描述
name 字符串 ✔️ 工作簿文件名（例如：test.xlsx）。
sheetName 字符串 ✔️ 工作表名称（例如：Sheet1）。
cellName 字符串 ✔️ 目标单元格地址（例如：A1）。

查询参数

名称 类型 是否必需 描述
folder 字符串 可选 包含工作簿的文件夹路径。
storageName 字符串 可选 文件所在的存储服务名称。

请求体

请求体必须包含一个 Comment（注释） 对象，以 JSON 格式表示。

{
  "CellName": "A1",
  "Author": "string",
  "HtmlNote": "string",
  "Note": "string",
  "AutoSize": true,
  "IsVisible": true,
  "Width": 10,
  "Height": 10,
  "TextHorizontalAlignment": "Left",
  "TextOrientationType": "NoRotation",
  "TextVerticalAlignment": "Top"
}

Comment 对象字段说明

字段 类型 是否必需 描述
CellName 字符串 ✔️ 单元格地址（必须与路径参数 {cellName} 的值一致）。
Author 字符串 可选 注释作者姓名。
HtmlNote 字符串 可选 HTML 格式的注释文本。
Note 字符串 可选 纯文本注释内容。
AutoSize 布尔值 可选 是否自动调整注释框大小。
IsVisible 布尔值 可选 默认是否显示注释。
Width / Height 数值 可选 注释框尺寸（单位：点）。
TextHorizontalAlignment 字符串 可选 水平对齐方式（Left、Center、Right）。
TextOrientationType 字符串 可选 文本方向（NoRotation、Rotate90 等）。
TextVerticalAlignment 字符串 可选 垂直对齐方式（Top、Center、Bottom）。

cURL 示例

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/comments/A1" \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt token>" \
  -d '{
        "CellName": "A1",
        "Author": "test",
        "HtmlNote": "<font style=\"font-weight:bold;font-family:Tahoma;font-size:9pt;color:#000000;text-align:left;\">this is a comment</font>",
        "Note": "this is a comment",
        "AutoSize": true,
        "IsVisible": true,
        "Width": 10,
        "Height": 10,
        "TextHorizontalAlignment": "Left",
        "TextOrientationType": "NoRotation",
        "TextVerticalAlignment": "Top"
      }'

响应架构

字段 类型 描述
Comment 对象 创建的注释对象（参见上方 Comment 对象字段说明，以及链接元数据）。
Code 整数 API 返回的 HTTP 状态码（例如：200）。
Status 字符串 文本形式的状态消息（例如："OK"）。

Comment 对象还包含一个 link（链接） 子对象：

子字段 类型 描述
Href 字符串 注释资源的自引用 URL。
Rel 字符串 关系类型（self）。
Title 字符串 可选标题（可能为 null）。
Type 字符串 可选 MIME 类型（可能为 null）。

成功响应示例

{
  "Comment": {
    "CellName": "A1",
    "Author": "test",
    "HtmlNote": "<Font Style=\"FONT-WEIGHT: bold;FONT-FAMILY: Tahoma;FONT-SIZE: 9pt;COLOR: #000000;TEXT-ALIGN: left;\">this is a comment</Font>",
    "Note": "this is a comment",
    "AutoSize": true,
    "IsVisible": true,
    "Width": 10,
    "Height": 10,
    "TextHorizontalAlignment": "Left",
    "TextOrientationType": "NoRotation",
    "TextVerticalAlignment": "Top",
    "link": {
      "Href": "/test.xlsx/worksheets/Sheet1/comments/A1",
      "Rel": "self",
      "Title": null,
      "Type": null
    }
  },
  "Code": 200,
  "Status": "OK"
}

错误响应

HTTP 状态码 描述 示例
400 请求错误 — 缺少或无效参数。 { "Error": { "Code": "InvalidParameter", "Message": "The 'cellName' parameter is missing or malformed." }, "Code": 400, "Status": "Bad Request" }
401 未授权 — 缺少或无效的令牌。 { "Error": { "Code": "InvalidToken", "Message": "Authentication failed." }, "Code": 401, "Status": "Unauthorized" }
404 未找到 — 工作簿、工作表或单元格不存在。 { "Error": { "Code": "FileNotFound", "Message": "Workbook 'test.xlsx' not found." }, "Code": 404, "Status": "Not Found" }
500 服务器内部错误 — 服务器上发生意外情况。 { "Error": { "Code": "ServerError", "Message": "An unexpected error occurred." }, "Code": 500, "Status": "Internal Server Error" }

SDK 示例

以下 SDK 提供了该操作的现成封装。请将占位符值（<YOUR_TOKEN>、<FILE_NAME> 等）替换为实际数据。

参见

附加说明