Web SDK

批註

批註功能允許使用者在電子表格的單元格中新增註釋，以便記錄額外資訊或提供上下文。它支援多種註釋樣式和操作，幫助使用者更好地理解和協作處理資料。

外掛模式

安裝

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 SheetsNoteUIZhTW from '@univerjs/sheets-note-ui/locale/zh-TW'import '@univerjs/sheets-note-ui/lib/index.css'import '@univerjs/sheets-note/facade'const univer = new Univer({  locale: LocaleType.ZH_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      SheetsNoteUIZhTW,     ),  },})univer.registerPlugin(UniverSheetsNotePlugin)univer.registerPlugin(UniverSheetsNoteUIPlugin)

預設模式

安裝

Shell
pnpm add @univerjs/preset-sheets-note

使用

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'import { UniverSheetsNotePreset } from '@univerjs/preset-sheets-note'import UniverPresetSheetsNoteZhTW from '@univerjs/preset-sheets-note/locales/zh-TW'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_TW,  locales: {    [LocaleType.ZH_TW]: mergeLocales(      UniverPresetSheetsCoreZhTW,      UniverPresetSheetsNoteZhTW,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsNotePreset(),   ],})

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.