范围 & 选区 & 单元格
范围Range
范围指工作表中的一块矩形区域,有起始行号、起始列号、长宽或者结束行号、结束列号来确定。
表格中的大部分操作都可以通过范围 API 来操作,如设置值、获取值、设置样式、获取样式等。
创建范围
获得一个范围需要知道起始行号、起始列号、长宽。
获取 A1 单元格的范围:
const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
const range = sheet.getRange(0, 0, 1, 1);
获取 A1:B2 的范围:
const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
const range = 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 来获取当前选区、设置选区和监听选区变化。
获取激活选区的范围
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);
})
单元格进入编辑
univerAPI.onCommandExecuted((command) => {
if(command.id === 'sheet.operation.set-cell-edit-visible' && command.params.visible){
console.log('Cell edit visible')
}
})
单元格退出编辑
univerAPI.onCommandExecuted((command) => {
if(command.id === 'sheet.operation.set-cell-edit-visible' && !command.params.visible){
console.log('Cell edit invisible')
}
})