Web SDK

批注

批注功能允许用户在电子表格的单元格中添加注释，以便记录额外信息或提供上下文。它支持多种注释样式和操作，帮助用户更好地理解和协作处理数据。

预览

预设模式

安装

Shell
pnpm add @univerjs/preset-sheets-note

使用

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { UniverSheetsNotePreset } from '@univerjs/preset-sheets-note'import UniverPresetSheetsNoteZhCN from '@univerjs/preset-sheets-note/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-note/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,      UniverPresetSheetsNoteZhCN,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsNotePreset(),   ],})

插件模式

安装

Shell
pnpm add @univerjs/sheets-note @univerjs/sheets-note-ui

使用

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverSheetsNotePlugin } from '@univerjs/sheets-note'import { UniverSheetsNoteUIPlugin } from '@univerjs/sheets-note-ui'import SheetsNoteUIZhCN from '@univerjs/sheets-note-ui/locale/zh-CN'import '@univerjs/sheets-note-ui/lib/index.css'import '@univerjs/sheets-note/facade'const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      SheetsNoteUIZhCN,     ),  },})univer.registerPlugin(UniverSheetsNotePlugin)univer.registerPlugin(UniverSheetsNoteUIPlugin)

Facade API

完整 Facade API 类型定义，请查看 FacadeAPI。

引入

插件模式提示

仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包，无需额外导入。

TypeScript
import '@univerjs/sheets-note/facade'

获取批注

FWorksheet.getNotes：获取工作表的所有批注

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const notes = fWorksheet.getNotes()notes.forEach((item) => {  const { row, col, note } = item  console.log(`单元格 ${fWorksheet.getRange(row, col).getA1Notation()} 的批注为: ${note}`)})

FRange.getNote：获取范围内左上角单元格的批注

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:D10')const note = fRange.getNote()

添加或更新批注

FRange.createOrUpdateNote：创建或更新范围内左上角单元格的批注

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1')fRange.createOrUpdateNote({  note: '这是一个批注',  width: 160,  height: 100,  show: true,})

删除批注

FRange.deleteNote：删除范围内左上角单元格的批注

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const notes = fWorksheet.getNotes()if (notes.length > 0) {  // 删除工作表中第一个批注  const { row, col } = notes[0]  fWorksheet.getRange(row, col).deleteNote()}// 删除 C1 单元格批注const fRange = fWorksheet.getRange('C1')fRange.deleteNote()

事件监听

完整事件类型定义，请查看 Events。

事件名称说明
SheetNoteAdd添加批注后触发
SheetNoteDelete删除批注后触发
SheetNoteUpdate更新批注后触发
SheetNoteShow显示批注时触发
SheetNoteHide隐藏批注时触发
BeforeSheetNoteAdd添加批注前触发
BeforeSheetNoteDelete删除批注前触发
BeforeSheetNoteUpdate更新批注前触发
BeforeSheetNoteShow显示批注前触发
BeforeSheetNoteHide隐藏批注前触发

事件监听示例

TypeScript
// 添加批注后事件const disposable = univerAPI.addEvent(univerAPI.Event.SheetNoteAdd, (params) => {  const { workbook, worksheet, row, col, note } = params})// 移除事件监听，使用 `disposable.dispose()`
TypeScript
// 删除批注前事件，可取消const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetNoteDelete, (params) => {  const { workbook, worksheet, row, col, oldNote } = params  // 取消批注删除操作  params.cancel = true})// 移除事件监听，使用 `disposable.dispose()`

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.