Working with Comments

使用评论

使用批注

Aspose.Cells FOSS for Java 允许您在 XLSX 工作簿中添加、读取、修改和删除单元格批注（备注）。批注通过工作表上的 CommentCollection 访问，并表示为 Comment 对象，携带批注文本、作者姓名和显示尺寸。

概述

每个工作表通过 Worksheet.getComments() 公开其批注，该方法返回一个 CommentCollection。您可以通过单元格地址或行/列索引添加批注，按索引或单元格名称检索现有批注，并在不再需要时将其删除。

一个 Comment 存储批注文本（getNote()/setNote()），作者（getAuthor()/setAuthor()），其锚点位置（getRow()，getColumn()），显示尺寸（getWidth()，getHeight()），以及默认是否可见（isVisible()/setVisible()）。

在工作表上访问批注

通过 Worksheet.getComments() 从任意 Worksheet 中检索 CommentCollection。使用 CommentCollection.getCount() 确定当前存在的批注数量。单个批注可通过 CommentCollection.get(index) 的零基索引或通过 CommentCollection.get(cellName) 的单元格名称访问。

添加批注

使用 CommentCollection.add(cellName) 或 CommentCollection.add(row, column) 插入新评论。两者的重载都返回一个 Comment 对象。在保存之前，在返回的实例上设置注释文本和作者。

// Add a comment to cell B2 and configure it
Comment comment = ws.getComments().add("B2");
comment.setNote("Review this value before submission.");
comment.setAuthor("Analyst");
comment.setVisible(false);
comment.setWidth(180);
comment.setHeight(60);

读取评论内容

使用计数遍历所有评论：

CommentCollection comments = ws.getComments();
for (int i = 0; i < comments.getCount(); i++) {
    Comment c = comments.get(i);
    System.out.printf("Cell [%d,%d] author=%s note=%s%n",
        c.getRow(), c.getColumn(), c.getAuthor(), c.getNote());
}

修改现有评论

通过单元格地址检索评论并直接更新其字段：

Comment c = ws.getComments().get("B2");
if (c != null) {
    c.setNote("Updated note text.");
    c.setVisible(true);
}

删除评论

使用 CommentCollection.removeAt(index) 或 CommentCollection.removeAt(cellName) 删除评论：

ws.getComments().removeAt("B2");

技巧与最佳实践

始终检查 CommentCollection.get(cellName) 在修改评论之前不会返回 null ——该单元格可能没有附加评论。
为仅在悬停时显示的批注设置 Comment.setVisible(false)，这符合标准的 Excel 行为。
使用 Comment.setWidth() 和 Comment.setHeight()（以像素为单位），确保注释框足够大以容纳多行文本。
作者名称以纯字符串形式存储；不会根据工作簿的用户列表进行验证。
当未对 CommentCollection 进行任何修改时，评论在通过 XLSX 的加载/保存往返过程中仍然保留。

常见问题

问题	原因	修复
`get(cellName)` 返回 `null`	该地址没有评论	检查单元格地址或按索引遍历
保存后评论备注为空	`setNote()` 未在保存前调用	在保存工作簿之前，对返回的 `Comment` 调用 `setNote()`
在 Excel 中不可见的批注	`setVisible(false)` 已设置	更改为 `setVisible(true)` 或在 Excel 中将鼠标悬停在单元格上

FAQ

如何在特定的行和列添加评论？

使用 CommentCollection.add(row, column)，其中两个值都是从零开始的索引。这等同于使用 add(cellName) 并配合相应的单元格地址。

我可以更改已有评论的作者吗？

是的。通过 get(cellName) 检索 Comment，并使用新的作者字符串调用 setAuthor(name)。

我如何检查评论当前是否可见？

调用 Comment.isVisible()。如果评论框始终显示，则返回 true；如果仅在悬停时出现，则返回 false。

在转换为其他格式时，评论会被保留吗？

在 XLSX 循环往返时，评论会被保留。其他格式的保留行为取决于目标输出对该格式的支持。

我如何统计工作表中的评论数量？

使用 Worksheet.getComments().getCount()。

API Reference 摘要

Comment

方法	返回类型	描述
`getRow()`	`int`	锚点单元格的零基行索引。
`getColumn()`	`int`	锚点单元格的零基列索引。
`getNote()`	`String`	注释文本。
`setNote(note)`	`void`	设置注释文本。
`getAuthor()`	`String`	作者姓名。
`setAuthor(author)`	`void`	设置作者名称。
`isVisible()`	`boolean`	评论框是否始终可见。
`setVisible(visible)`	`void`	设置评论框的可见性。
`getWidth()`	`int`	评论框的宽度（像素）.
`setWidth(width)`	`void`	设置评论框的宽度。
`getHeight()`	`int`	评论框的高度（像素）。
`setHeight(height)`	`void`	设置评论框的高度。

CommentCollection

方法	返回类型	描述
`getCount()`	`int`	工作表中的评论数量。
`get(index)`	`Comment`	返回零基索引处的评论。
`get(cellName)`	`Comment`	返回指定单元格地址的注释。
`add(row, column)`	`Comment`	在行/列位置添加新注释。
`add(cellName)`	`Comment`	在单元格地址添加新注释。
`removeAt(index)`	`void`	删除零基索引处的注释。
`removeAt(cellName)`	`void`	删除单元格地址处的注释。

另请参阅

Aspose.Cells for Java — Enterprise Documentation