Handsontable 单元格注释(Comments)插件完全指南:配置、快捷键与源码实现解析

原创2026-09-19 17:32:041,889 阅读
文章标签:前端UI组件企业应用

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)逐一查阅。

登录后查看全文
handsontable