批注 - Office Open

#添加批注

为工作表中的单元格添加批注（Excel 中的传统注释）：

JSON

{
  "worksheets": [
    {
      "name": "With Comments",
      "rows": [
        { "cells": [{ "value": "Product" }, { "value": "Price" }, { "value": "Stock" }] },
        { "cells": [{ "value": "Widget A" }, { "value": 9.99 }, { "value": 150 }] },
        { "cells": [{ "value": "Widget B" }, { "value": 14.99 }, { "value": 75 }] },
        { "cells": [{ "value": "Widget C" }, { "value": 24.99 }, { "value": 0 }] }
      ],
      "comments": [
        { "cell": "B2", "author": "Alice", "text": "Discounted from 12.99" },
        { "cell": "C3", "author": "Bob", "text": "Reorder soon" },
        { "cell": "C4", "author": "Alice", "text": "Out of stock!" }
      ]
    }
  ]
}

TypeScript

{
  name: "With Comments",
  rows: [
    { cells: [{ value: "Product" }, { value: "Price" }, { value: "Stock" }] },
    { cells: [{ value: "Widget A" }, { value: 9.99 }, { value: 150 }] },
    { cells: [{ value: "Widget B" }, { value: 14.99 }, { value: 75 }] },
    { cells: [{ value: "Widget C" }, { value: 24.99 }, { value: 0 }] },
  ],
  comments: [
    { cell: "B2", author: "Alice", text: "Discounted from 12.99" },
    { cell: "C3", author: "Bob", text: "Reorder soon" },
    { cell: "C4", author: "Alice", text: "Out of stock!" },
  ],
}

#批注选项参考

选项	类型	说明
`cell`	`string`	单元格引用，如 `"B2"`
`author`	`string`	批注作者
`text`	`string` 或 `object`	纯文本字符串，或包含 `runs` 的富文本对象
`properties`	`object`	批注属性（锚点、锁定、对齐）

#富文本批注

批注支持通过 runs 属性实现富文本格式。每个文本段落包含 text 字符串和可选的 properties 格式设置：

json

{
  "comments": [
    {
      "cell": "B2",
      "author": "Alice",
      "text": {
        "runs": [
          {
            "text": "Note: ",
            "properties": {
              "bold": true
            }
          },
          {
            "text": "Premium grade material"
          }
        ]
      }
    },
    {
      "cell": "B3",
      "author": "Bob",
      "text": {
        "runs": [
          {
            "text": "Best seller! ",
            "properties": {
              "color": { "rgb": "FF008000" },
              "bold": true
            }
          },
          {
            "text": "Consider bulk discount."
          }
        ]
      }
    }
  ]
}

#富文本段落属性

属性	类型	说明
`font`	`string`	字体名称
`charset`	`number`	字符集
`family`	`number`	字体族
`bold`	`boolean`	加粗文本
`italic`	`boolean`	斜体文本
`strike`	`boolean`	删除线
`outline`	`boolean`	轮廓文本
`shadow`	`boolean`	阴影文本
`condense`	`boolean`	压缩文本
`extend`	`boolean`	扩展文本
`color`	`string`	文字颜色十六进制值，如 `"FF0000"`
`size`	`number`	字号（磅）
`underline`	`"single"` \| `"double"` \| `"singleAccounting"` \| `"doubleAccounting"` \| `"none"`	下划线样式
`vertAlign`	`"superscript"` \| `"subscript"` \| `"baseline"`	垂直对齐
`scheme`	`"major"` \| `"minor"` \| `"none"`	字体方案

#批注属性（CT_CommentPr）

批注可以通过 properties 选项设置锚点和锁定行为：

json

{
  "comments": [
    {
      "cell": "B2",
      "author": "Alice",
      "text": {
        "runs": [
          {
            "text": "Note: ",
            "properties": {
              "bold": true
            }
          },
          {
            "text": "Premium grade material"
          }
        ]
      },
      "properties": {
        "locked": false,
        "autoFill": true,
        "anchor": {
          "moveWithCells": true,
          "sizeWithCells": false
        }
      }
    }
  ]
}

CommentPr 选项

属性	类型	说明
`locked`	`boolean`	锁定
`defaultSize`	`boolean`	默认大小
`print`	`boolean`	随工作表打印
`disabled`	`boolean`	禁用
`autoFill`	`boolean`	自动填充
`autoLine`	`boolean`	自动换行
`altText`	`string`	替代文本
`textHAlign`	`"left"` \| `"center"` \| `"right"` \| `"justify"` \| `"distributed"`	文本水平对齐
`textVAlign`	`"top"` \| `"center"` \| `"bottom"` \| `"justify"` \| `"distributed"`	文本垂直对齐
`lockText`	`boolean`	锁定文本
`justLastX`	`boolean`	最后一行两端对齐
`autoScale`	`boolean`	自动缩放
`anchor`	`ObjectAnchorOptions`	对象锚点位置