Handsontable 单元格注释(Comments)插件完全指南:配置、快捷键与源码实现解析
Handsontable 单元格注释(Comments)插件完全指南:配置、快捷键与源码实现解析
单元格注释(Comments)是 Handsontable 内置插件之一,它允许用户像在 Excel 中一样为单元格附加文本批注,用于审阅、数据说明与协作场景,而不会改动单元格本身的值。本文以官方指南 comments.md 为骨架,结合 Comments 插件源码 与全部可运行的示例代码,系统讲解如何启用插件、通过右键菜单与 API 增删改注释、设置只读注释、控制注释框尺寸与显示延迟、用注释标记校验失败的单元格,以及如何程序化地读取全表注释。读完本文,你将掌握 Comments 插件的完整配置面,并理解其底层元数据存储与事件驱动机制。
Comments 插件能做什么
Comments 插件让数据网格具备"单元格级批注"能力。它的典型用途包括:
- 审阅者在不修改单元格值的前提下对数据做说明;
- 在表格加载时预置提示信息,引导用户理解特殊数据;
- 与校验逻辑联动,把校验错误信息直接"贴"在出错的单元格上;
- 通过 API 批量管理注释,实现导入导出、审计或报表生成。
从源码结构看,插件由四部分协作完成:comments.ts(插件主类)、commentEditor.ts(悬浮文本框编辑器)、displaySwitch.ts(显示/隐藏的防抖控制)、以及 contextMenuItem/ 下的三个右键菜单项。整个功能以 comments 配置项为开关,注释数据则存储在单元格元数据(cell meta)中。
启用插件
将 comments 配置项设为 true,即可启用插件并自动向上下文菜单注入全部相关菜单项。四种框架下的最小配置如下:
JavaScript
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';
registerAllModules();
const container = document.querySelector('#example1');
new Handsontable(container, {
data: [
['Update API docs', 'Ana García', 'In progress'],
['Deploy hotfix', 'James Okafor', 'Blocked'],
],
comments: true,
autoWrapRow: true,
autoWrapCol: true
});
React
<HotTable
data={[
['Update API docs', 'Ana García', 'In progress'],
['Deploy hotfix', 'James Okafor', 'Blocked'],
]}
comments={true}
/>
Angular
data = [
["Update API docs", "Ana García", "In progress"],
["Deploy hotfix", "James Okafor", "Blocked"],
];
settings = {
comments: true,
};
<hot-table [data]="data" [settings]="settings" />
Vue 3
const hotSettings = {
data: [
['Update API docs', 'Ana García', 'In progress'],
['Deploy hotfix', 'James Okafor', 'Blocked'],
],
comments: true,
autoWrapRow: true,
autoWrapCol: true,
licenseKey: 'non-commercial-and-evaluation',
};
除了布尔值,comments 还支持传入一个配置对象,用于一次性设置插件级的默认行为(详见下文"显示延迟"小节)。官方基础示例见 example1.js(及对应的 example1.ts)。
从源码看,启用逻辑非常直接:isEnabled() 读取 hot.getSettings()<a href="https://link.gitcode.com/i/3dd3c9a2ca69568c34c21a8c8c2588f2" target="_blank">'comments'] 的布尔值,返回 true 时 enablePlugin() 会创建注释编辑器实例与 DisplaySwitch 实例,并注册 afterContextMenuDefaultOptions、afterRenderer、afterScroll、afterBeginEditing、afterDocumentKeyDown 等钩子(见 [comments.ts)。这意味着插件启用与否完全取决于该配置项,关闭后相关钩子与快捷键会一并注销。
通过右键菜单添加、编辑与删除注释
启用插件后,上下文菜单会新增三个条目:
- Add/Edit comment:为当前选中单元格添加注释,若该单元格已有注释则变为编辑模式;
- Delete comment:删除当前单元格的注释;
- Read-only comment:切换注释的只读状态。
这三个菜单项由 addToContextMenu() 在 afterContextMenuDefaultOptions 钩子中注入,依次为分隔符和三个预置菜单项。以 addEditComment.ts 为例,它的名称是动态的:当高亮单元格已存在注释时显示 "Edit comment",否则显示 "Add comment";点击后调用 plugin.setRange() + plugin.show() + plugin.focusEditor(),即打开悬浮在单元格旁的文本编辑器并聚焦输入框。当选中区域为表头、整行整列,或没有可渲染行列时,该菜单项会被禁用。
预置注释:通过 cell 配置初始化
注释内容存储在单元格的元数据对象中,因此你可以在初始化表格时通过 cell 配置数组预置注释。预置时注释对象使用 value 字段承载文本:
JavaScript / Vue
cell: [
{ row: 1, col: 1, comment: { value: 'Hello world!' } }
]
React
cell={[
{ row: 1, col: 1, comment: { value: 'Hello world!' } }
]}
Angular
settings = {
cell: [{ row: 1, col: 1, comment: { value: "Hello world!" } }],
};
以上配置会在 (1,1) 单元格(第 1 行第 1 列)预置一条 "Hello world!" 注释。官方示例 example1.js 演示了预置两条注释的效果,加载表格后注释角标立即出现。
在源码层面,注释的元数据结构由 CommentMeta 接口定义(见 comments.ts):
interface CommentMeta {
value?: string; // 注释正文
style?: { width: number; height: number }; // 注释框尺寸
readOnly?: boolean; // 是否只读
}
插件通过常量 META_COMMENT = 'comment' 作为单元格元数据中的键名,因此你可以直接用 hot.getCellMeta(row, col).comment 读取或修改某条注释。写入时建议优先使用插件封装的 updateCommentMeta()(见 comments.ts):它会在已有注释对象上做深拷贝合并,避免覆盖 style、readOnly 等其他字段。
让注释只读
默认情况下所有注释都可以编辑。要禁止用户修改某条注释,在添加注释时把 readOnly 设为 true:
cell: [
{
row: 0,
col: 1,
comment: { value: 'A read-only comment.', readOnly: true },
},
{ row: 0, col: 3, comment: { value: 'You can edit this comment' } },
]
完整示例见 example2.js:(0,1) 单元格的 "A read-only comment." 注释不可编辑,而 (0,3) 单元格的注释仍可自由修改。另外,comments 配置对象本身也支持顶层 readOnly: true,可以对整张表格的注释做全局只读限制(见 comments.ts 的 JSDoc 示例)。
渲染时,refreshEditor() 会读取该单元格的 readOnly 元数据并调用 editor.setReadOnlyState()(见 comments.ts),从而让编辑器的 textarea 进入只读状态。
设置注释框的尺寸
通过注释元数据中的 style 字段可以精确控制注释框的宽高(单位 px):
cell: [
{ row: 1, col: 1, comment: { value: 'Some comment' } },
{
row: 2,
col: 2,
comment: {
value: 'Comment 200x50 px',
style: { width: 200, height: 50 },
},
},
]
完整示例见 example3.js,其中 (2,2) 单元格的注释框被固定为 200×50 像素。
这一配置在源码中的落点是 META_STYLE = 'style'。refreshEditor() 在每次显示注释前都会读取 style 元数据并调用 editor.setSize(width, height),没有配置时则 resetSize() 回退到默认尺寸(见 comments.ts)。有趣的是,用户拖动编辑器右下角调整大小时,#onEditorResize() 会把新尺寸回写进单元格元数据(见 comments.ts),因此手动调整过尺寸的注释,其大小会被持久化保存。
设置注释的显示延迟
注释默认在鼠标悬停后延迟 250ms 显示(DEFAULT_SETTINGS.displayDelay = 250,见 comments.ts)。要自定义延迟,用对象形式配置 comments:
comments: {
// 鼠标悬停后等待 2 秒再显示注释框
displayDelay: 2000,
},
完整示例见 example4.js。displayDelay 也可与 style、readOnly 一起作为插件级默认值传入。
延迟机制由 displaySwitch.ts 实现。它内部维护一个 debounce 化的 show 函数与一个 setTimeout 化的隐藏计时器:
show(range):将wasLastActionShow置为true,调用防抖后的显示函数,只有连续悬停超过displayDelay毫秒才真正弹出注释框(displaySwitch.ts);hide():置为false并启动 250ms 的隐藏计时器(DEFAULT_HIDE_DELAY),鼠标离开后注释框延迟收起(displaySwitch.ts);cancelHiding()/keepVisible():当指针停留在编辑器上时取消隐藏,保证正在编辑的注释不会意外消失;updateDelay():在每次updateSettings()时被updatePlugin()调用,动态更新防抖延迟(displaySwitch.ts)。
鼠标悬停事件由主插件在 #onMouseOver 中监听:命中带注释的单元格(htCommentCell 类)就触发 displaySwitch.show(),否则触发 hide()(见 comments.ts)。滚动视图时注释框会自动隐藏(afterScroll 钩子),避免注释停留在错误的单元格上。
用注释标记校验失败的单元格
注释与校验器组合,可以构建"出错即标注、修复即清除"的交互。核心思路:在 afterValidate 钩子中判断校验结果,失败时用 setCommentAtCell() 写入提示,成功时用 removeCommentAtCell() 移除提示。
new Handsontable(container, {
data: [
['Wireless mouse', 142],
['USB-C cable', 67],
['Mechanical keyboard', -5],
['Laptop stand', 38],
['HDMI adapter', 210],
],
colHeaders: ['Product', 'Stock'],
rowHeaders: true,
comments: true,
columns: [
{},
{
type: 'numeric',
validator(value, callback) {
callback(Number.isInteger(value) && value >= 0);
},
},
],
// 校验失败时附加注释,通过后移除注释
afterValidate(isValid, value, row, prop) {
const column = this.propToCol(prop);
const comments = this.getPlugin('comments');
if (!isValid) {
comments.setCommentAtCell(row, column, `"${value}" is not valid. Enter a whole number of 0 or more.`);
} else {
comments.removeCommentAtCell(row, column);
}
},
// 加载时校验全部单元格,让已存在的非法值立即被标注
afterInit() {
this.validateCells();
},
});
完整示例见 example5.js。由于表格在 afterInit 中调用了 validateCells(),"Mechanical keyboard" 行的 -5 在加载瞬间就会被标注;此后编辑任一 Stock 单元格,输入负数或文本会立刻挂上注释,输入合法整数则注释消失。
这一示例用到的两个 API 都封装在插件主类中:
setCommentAtCell(row, column, value):先setRange()定位单元格,再写入注释并重渲染(comments.ts);removeCommentAtCell(row, column, forceRender = true):将comment元数据置为undefined并隐藏编辑器(comments.ts)。
配套的还有面向"先设置范围、再批量操作"的用法:setRange({ from: { row, col } }) 之后调用 setComment(value)、removeComment()、show()、getComment() 等通用方法(见 comments.ts 的 JSDoc 示例),适合对同一单元格执行多步操作。
程序化读取所有注释
要收集表格中的全部注释,可以遍历行并借助 getCellMetaAtRow() 读取每行的单元格元数据;返回的每个 cell-meta 对象都带有 comment 键。
const hot = new Handsontable(container, { /* ... comments: true, cell: [...] */ });
const button = document.querySelector('#list-comments');
const output = document.querySelector('#comments-output');
button.addEventListener('click', () => {
const found = [];
// getCellMetaAtRow() 接收物理行索引(无排序/裁剪时与可视索引一致)
for (let row = 0; row < hot.countRows(); row += 1) {
hot.getCellMetaAtRow(row).forEach((cellMeta, col) => {
const comment = cellMeta.comment;
if (comment?.value !== undefined) {
found.push(`Row ${row + 1}, "${hot.getColHeader(col)}": ${comment.value}`);
}
});
}
output.textContent = found.length > 0 ? found.join('\n') : 'No comments found.';
});
完整示例见 example6.js(含 example6.html 与 example6.ts)。示例预置了三条注释,点击 "List all comments" 按钮会把注释按 "行号 + 列表头 + 注释内容" 的格式打印到表格下方。
除了遍历,插件还提供按单元格读取的 API:getCommentAtCell(row, column) 返回指定单元格的注释正文,getCommentMeta(row, column, property) 可读取 value、style、readOnly 任一字段(comments.ts)。
源码视角:角标渲染与快捷键
角标(indicator)渲染。 带注释的单元格会在右上角显示一个小三角标记。这一效果通过 afterRenderer 钩子实现:#onAfterRenderer() 检查单元格元数据中是否有注释,若存在则为 TD 元素追加 commentedCellClassName 指定的样式类(默认 htCommentCell,见 comments.ts)。该标记在表格加载时即渲染完毕,与注释是否被查看过无关。禁用插件时 disablePlugin() 会调用 hot.markAllCellsChanged() 强制重绘,确保角标被清除。
快捷键。 插件在 registerShortcuts() 中注册了完整的键盘操作(见 comments.ts),并维护一个独立的 plugin:comments 快捷键上下文,保证输入注释时网格快捷键不会抢占按键:
| Windows | macOS | 操作 | Excel | Sheets |
|---|---|---|---|---|
| Ctrl+Alt+M | ⌃+⌥+M | 添加或编辑注释 | ✕ | ✓ |
| Ctrl+Enter | ⌘+Enter | 保存并退出当前注释 | ✕ | ✓ |
| Escape | Escape | 不保存退出当前注释 | ✕ | ✕ |
实现细节:Ctrl+Alt+M 会滚动到当前聚焦单元格并打开编辑器(仅当选中区域是普通单元格时可用);Ctrl+Enter 保存后切回网格上下文;Escape 先恢复注释的原始值(#commentValueBeforeSave)再关闭编辑器。此外,Tab / Shift+Tab 会把当前注释写入元数据并关闭,然后转发给网格上下文继续移动光标。注释编辑器失去焦点时(blur 事件)也会自动调用 setComment() 保存内容。
相关配置选项与钩子
围绕 Comments 插件,官方还提供了以下配置项与钩子(详见 API 参考 与插件源码 comments.ts):
配置选项
comments:插件开关,可传true或含displayDelay、readOnly、style的配置对象;commentedCellClassName:带注释单元格的角标样式类名,默认htCommentCell。
钩子
afterSetCellMeta/beforeSetCellMeta:单元格元数据(含注释)写入前后触发;afterRemoveCellMeta/beforeRemoveCellMeta:单元格元数据(含注释)移除前后触发;afterValidate:校验完成后触发,常与注释 API 组合实现"错误提示贴片"(见上文示例 5)。
插件 API(通过 hot.getPlugin('comments') 获取实例)
setCommentAtCell(row, col, value)/removeCommentAtCell(row, col)/getCommentAtCell(row, col)showAtCell(row, col)/show()/hide()/focusEditor()setRange({ from: { row, col } })/setComment(value)/removeComment()/getComment()updateCommentMeta(row, col, metaObject)/getCommentMeta(row, col, property)
小结
Comments 插件以"单元格元数据 + 事件驱动"为核心:注释正文、尺寸、只读状态全部落在 cell meta 的 comment 键下,右键菜单与 API 只是操作这份元数据的两种入口,DisplaySwitch 负责悬停显示/隐藏的防抖调度,afterRenderer 负责角标绘制。实际项目中,你可以先用 comments: true 快速获得 Excel 式的批注体验,再按需组合 cell 预置、readOnly 权限控制、style 尺寸与 displayDelay 延迟,最后借助 afterValidate 钩子和 setCommentAtCell() / getCellMetaAtRow() 等 API 构建"错误标注、审计导出"等高级场景。所有示例源码均可在 docs/content/guides/cell-features/comments/ 目录下按框架(javascript / react / angular / vue)逐一查阅。