Skip to Content
🎉 Univer 0.6.0 版本已发布。查看详情 →
GuidesUniver Sheets功能核心功能范围、选区、单元格

范围 & 选区 & 单元格

范围Range

范围指工作表中的一块矩形区域,有起始行号、起始列号、长宽或者结束行号、结束列号来确定。

表格中的大部分操作都可以通过范围 API 来操作,如设置值、获取值、设置样式、获取样式等。

Facade API

创建范围

获得一个范围需要知道起始行号、起始列号、长宽。

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); // 获取 A1 单元格的范围: const range = sheet.getRange(0, 0, 1, 1); // 获取 A1:B2 的范围: const range2 = sheet.getRange(0, 0, 2, 2);

0.2.15 开始 getRange 支持用 A1 表示法获取范围。

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); // 获取名称是 Sheet1 的工作表的 A1:B2 范围 const range1 = sheet.getRange('Sheet1!A1:B2'); // 获取单个单元格 A1 const range2 = sheet.getRange('A1'); // 获取 A1:B2 范围 const range3 = sheet.getRange('A1:B2'); // 获取 A 列的范围 const range4 = sheet.getRange('A:A'); // 获取第 1 行的范围 const range5 = sheet.getRange('1:1');

获取范围数据

获取范围第一个单元格的值

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); const value = range.getValue();

获取范围的所有值

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); range.forEach((row, column, cell) => { console.log(row, column, cell); });

获取范围的所有公式

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); console.log(range.getFormulas());

设置范围数据

设置单一值

传入一个值或者单元格对象,将会覆盖范围内所有单元格,如果以 = 开头,将被解释为公式。

比如,设置 A1:B2 的值为 Hello, Univer

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); range.setValue('Hello, Univer');

设置 A1+B1 的值为公式:

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); range.setValue('=A1+B1');

设置 A1:B2 的值为单元格对象:

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); range.setValue({ v: 'Hello, Univer', custom: { key: 'value', }, });
通过数组设置多个值

数组的长度和宽度必须和范围的长宽一致。

可以传入单元格值也可以传入单元格对象。

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); range.setValues([ ['A1', 'B1'], ['A2', 'B2'], ]); range.setValues([ [{ v: 'A1' }, { v: 'B1' }], [{ v: 'A2' }, { v: 'B2' }], ]);
通过对象设置多个值

则对象的一级索引代表行号,二级索引代表列号,与范围的长宽无需一致。

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); range.setValues({ 0: { 0: 'A1', 1: 'B1', }, 1: { 0: 'A2', 1: 'B2', }, });

获取范围样式

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); const style = range.getCellStyleData();

设置范围样式

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); range .setFontWeight('bold') .setFontLine('underline') .setFontFamily('Arial') .setFontSize(24) .setFontColor('red');

清理范围样式

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); range .setFontWeight(null) .setFontLine(null) .setFontFamily(null) .setFontSize(null) .setFontColor(null);

是否合并

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); const isMerged = range.isMerged();

获取坐标

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); univerAPI.getHooks().onRendered(() => { const rect = range.getCellRect(); // width、heigh、left、right、top、bottom、x、y console.log(rect); });

同时获取范围的合并信息和坐标

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); const range = sheet.getRange(0, 0, 2, 2); univerAPI.getHooks().onRendered(() => { const cell = range.getCell(); console.log(cell); });

选区Selection

Univer 表格支持多选区,所以选区是一个范围数组,可以通过范围 API 来操作选区数据。

我们还提供 API 来获取当前选区、设置选区和监听选区变化。

Facade API

获取激活选区的范围

const sheet = univerAPI.getActiveWorkbook().getActiveSheet(); univerAPI.getHooks().onRendered(() => { const selection = sheet.getSelection(); console.log(selection); const range = selection.getActiveRange(); console.log(range); });

设置选区

设置 A1:B2 为选区

import { SetSelectionsOperation } from '@univerjs/sheets' univerAPI.executeCommand(SetSelectionsOperation.id, { unitId, subUnitId, selections: [{ range: { startRow: 0, startColumn: 0, endRow: 1, endColumn: 1, rangeType: 0, }, }], type: 2, })

监听选区变化

const activeWorkbook = univerAPI.getActiveWorkbook(); activeWorkbook.onSelectionChange((selection) => { console.log(selection); });

单元格Cell

单元格数据以二维 Map 的形式存储在工作表中,一二级索引分别代表行号和列号。

以下是一个典型的单元格对象:

{ v: 'Hello, Univer', s: 'styleId', t: CellValueType.STRING }

详细的字段说明请参考 单元格信息

ℹ️

对单元格的操作可以看作对行高 1 、列宽 1 的范围进行操作,操作范围请阅读 范围-range

ℹ️

插件还会将拓展的单元格属性存储在 Workbookresources 属性中,详细请阅读 插件自定义模型

事件列表

以下是可用的单元格相关事件列表:

事件名称描述参数类型示例
CellPointerMove鼠标移动到单元格上时触发ICellEventParamconst { worksheet, workbook, row, column } = params
CellPointerDown鼠标按下时触发ICellEventParamconst { worksheet, workbook, row, column } = params
CellPointerUp鼠标释放时触发ICellEventParamconst { worksheet, workbook, row, column } = params
CellHover鼠标悬停在单元格上时触发ICellEventParamconst { worksheet, workbook, row, column } = params
DragOver拖动元素经过单元格时触发ICellEventParamconst { worksheet, workbook, row, column } = params
Drop拖动元素放置到单元格时触发ICellEventParamconst { worksheet, workbook, row, column } = params
CellClicked点击单元格时触发ICellEventParamconst { worksheet, workbook, row, column } = params
BeforeSheetEditStart单元格开始编辑前触发IBeforeSheetEditStartEventParamsconst { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params
SheetEditStarted单元格开始编辑时触发ISheetEditStartedEventParamsconst { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params
SheetEditChanging单元格编辑内容变化时触发ISheetEditChangingEventParamsconst { worksheet, workbook, row, column, value, isZenEditor } = params
BeforeSheetEditEnd单元格结束编辑前触发IBeforeSheetEditEndEventParamsconst { worksheet, workbook, row, column, value, eventType, keycode, isZenEditor, isConfirm } = params
SheetEditEnded单元格结束编辑后触发ISheetEditEndedEventParamsconst { worksheet, workbook, row, column, eventType, keycode, isZenEditor, isConfirm } = params

使用示例

所有事件都可以通过 addEvent 方法进行监听。基本格式如下:

univerAPI.addEvent(univerAPI.Event.事件名称, (params) => { // 事件处理逻辑 });

单元格 PointerMove 事件

CellPointerMove 事件在鼠标移动到单元格上时触发。通过此事件可以获取当前鼠标指向的单元格信息。

univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => { // 获取事件参数 const { worksheet, workbook, row, column } = params; console.log('当前单元格位置:', row, column); })

单元格 PointerDown 事件

CellPointerDown 事件在鼠标按下时触发。

univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => { const { worksheet, workbook, row, column } = params; console.log('鼠标按下的单元格:', row, column); })

单元格 PointerUp 事件

CellPointerUp 事件在鼠标释放时触发。

univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => { const { worksheet, workbook, row, column } = params; console.log('鼠标释放的单元格:', row, column); })

单元格 Hover 事件

CellHover 事件在鼠标悬停在单元格上时触发。

univerAPI.addEvent(univerAPI.Event.CellHover, (params) => { const { worksheet, workbook, row, column } = params; console.log('悬停的单元格:', row, column); })

单元格 DragOver 事件

DragOver 事件在拖动元素经过单元格时触发。

univerAPI.addEvent(univerAPI.Event.DragOver, (params) => { const { worksheet, workbook, row, column } = params; console.log('拖动经过的单元格:', row, column); })

单元格 Drop 事件

Drop 事件在拖动元素放置到单元格时触发。

univerAPI.addEvent(univerAPI.Event.Drop, (params) => { const { worksheet, workbook, row, column } = params; console.log('放置的单元格:', row, column); })

单元格 Click 事件

CellClicked 事件在点击单元格时触发。

univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => { const { worksheet, workbook, row, column } = params; console.log('点击的单元格:', row, column); })

单元格渲染事件

onCellRender 事件在单元格渲染时触发,可用于自定义单元格渲染。

案例 1:固定位置渲染,添加行不会影响渲染位置

// 固定位置渲染 univerAPI.getSheetHooks().onCellRender([{ drawWith: (ctx, info, skeleton, spreadsheets) => { const { row, col } = info; // 在指定位置(1,1)渲染勾选标记 if (row === 1 && col === 1) { const { primaryWithCoord } = info; const { startX, startY } = primaryWithCoord; ctx.fillText('✅', startX, startY + 10); } } }]); // 刷新画布以应用渲染 univerAPI.getActiveWorkbook().getActiveSheet().refreshCanvas();

案例 2:按标记渲染,标记位置会随着行列变化而变化

// 设置标记 univerAPI.getActiveWorkbook().getActiveSheet().getRange('B2').setValue({ custom: { key: 'needCheck' } }); // 按标记渲染 univerAPI.getSheetHooks().onCellRender([{ drawWith: (ctx, info, skeleton, spreadsheets) => { const { row, col, data } = info; // 在标记的位置渲染勾选标记 if (data?.custom?.key === 'needCheck') { const { primaryWithCoord } = info; const { startX, startY } = primaryWithCoord; ctx.fillText('✅', startX, startY + 10); } } }]); // 刷新画布以应用渲染 univerAPI.getActiveWorkbook().getActiveSheet().refreshCanvas();

单元格编辑事件

开始编辑

const workbook = univerAPI.getActiveWorkbook(); // 在渲染完成后开始编辑 univerAPI.addEvent(univerAPI.Event.Rendered, () => { workbook.startEditing(); });

结束编辑

// 传入 true 表示提交编辑,false 表示取消编辑 // 这是一个异步函数,需要使用 await await workbook.endEditing(true);

编辑前事件

BeforeSheetEditStart 事件在单元格开始编辑前触发。

univerAPI.addEvent(univerAPI.Event.BeforeSheetEditStart, (params) => { const { worksheet, workbook, row, column, eventType, keycode, isZenEditor } = params; console.log('单元格编辑前:', params); })

编辑后事件

SheetEditEnded 事件在单元格编辑完成后触发。

univerAPI.addEvent(univerAPI.Event.SheetEditEnded, (params) => { const { worksheet, workbook, row, column, eventType, keycode, isZenEditor, isConfirm } = params; console.log('单元格编辑后:', params); })

剪贴板事件

BeforeClipboardChange

BeforeClipboardChange 事件在剪贴板内容改变之前触发。您可以使用此事件在内容改变之前监控或修改剪贴板内容。

univerAPI.addEvent(univerAPI.Event.BeforeClipboardChange, (param) => { const {text, html} = param; console.log('剪贴板内容:', text, html); // 如果想取消剪贴板内容的改变 // param.cancel = true; });

BeforeClipboardPaste

BeforeClipboardPaste 事件在内容粘贴之前触发。您可以使用此事件在粘贴之前监控或修改内容。

univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (param) => { const {text, html} = param; console.log('待粘贴内容:', text, html); // 如果想取消粘贴操作 // param.cancel = true; });

ClipboardChanged

ClipboardChanged 事件在剪贴板内容改变之后触发。

univerAPI.addEvent(univerAPI.Event.ClipboardChanged, (param) => { const {text, html} = param; console.log('新的剪贴板内容:', text, html); });

ClipboardPasted

ClipboardPasted 事件在内容粘贴完成后触发。

univerAPI.addEvent(univerAPI.Event.ClipboardPasted, (param) => { const {text, html} = param; console.log('已粘贴的内容:', text, html); });

这个页面对您有帮助吗?
Last updated on