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。

ℹ️

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

事件列表

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

事件名称描述参数类型示例
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
行列冻结