范围 & 选区 & 单元格

范围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);
const rect = range.getCellRect(); // width、heigh、left、right、top、bottom、x、y

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

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

选区Selection

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

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

Facade API

获取激活选区的范围

const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
 
const selection = sheet.getSelection();
const range = selection.getActiveRange();

设置选区

设置 A1:B2 为选区

import { SetSelectionsOperation } from '@univerjs/sheets'
 
const sheetId = 'SheetId';
univerAPI.executeCommand(SetSelectionsOperation.id, {
  selections: [{
    range: {
      startRow: 0,
      startColumn: 0,
      endRow: 1,
      endColumn: 1,
      rangeType: 0,
    },
  }],
  subUnitId,
  unitId: activeWorkbook.getId(),
  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 属性中，详细请阅读插件自定义模型。

单元格 PointerMove

onCellPointerMove 事件在鼠标更改坐标时触发

univerAPI.getSheetHooks().onCellPointerMove((cell) => {
  // 拿到当前鼠标指向的单元格
  console.log(cell);
})

单元格 PointerOver 事件

onCellPointerOver 事件在鼠标移动到单元格的边界时触发

univerAPI.getSheetHooks().onCellPointerOver((cell) => {
  // 拿到当前鼠标指向的单元格
  console.log(cell);
})

单元格 DragOver 事件

onCellDragOver 事件在拖动元素或文本到单元格的边界时触发

univerAPI.getSheetHooks().onCellDragOver((cell) => {
  // 拿到当前鼠标指向的单元格
  console.log(cell);
})

单元格 Drop 事件

onCellDrop 事件在拖动元素或文本到单元格上释放时触发

univerAPI.getSheetHooks().onCellDrop((cell) => {
  // 拿到当前鼠标指向的单元格
  console.log(cell);
})

单元格 Hover 事件

onCellHover 事件在鼠标移动到单元格上时触发

univerAPI.getActiveWorkbook().onCellHover((cell) => {
  // 拿到当前鼠标指向的单元格
  console.log(cell);
})

单元格 Click 事件

onCellClick 事件在鼠标点击单元格时触发

univerAPI.getActiveWorkbook().onCellClick((cell) => {
  // 拿到当前鼠标点击的单元格
  console.log(cell);
})

开始编辑单元格

const workbook = univerAPI.getActiveWorkbook();
workbook.startEditing();

结束编辑单元格

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

行列冻结