Univer Sheets API

概念

Univer 表格相关概念会尽可能与 Excel 保持一致。

工作簿 Workbook

一个工作簿里包含多个工作表，可以看作是一个 Excel 文件。

unitId 可用作工作簿的唯一标识。

创建工作簿

univer.createUnit(UniverInstanceType.UNIVER_SHEET, workbookData) 方法会创建并返回 Workbook 对象。

workbookData 是一个对象，包含了工作簿的配置信息。

const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: zhCN,
  },
});
 
univer.registerPlugin(UniverRenderEnginePlugin);
univer.registerPlugin(UniverFormulaEnginePlugin);
univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
});
 
univer.registerPlugin(UniverDocsPlugin);
univer.registerPlugin(UniverDocsUIPlugin);
 
univer.registerPlugin(UniverSheetsPlugin);
univer.registerPlugin(UniverSheetsUIPlugin);
univer.registerPlugin(UniverSheetsFormulaPlugin);
 
// 传入空对象会自动初始化工作簿
univer.createUnit(UniverInstanceType.UNIVER_SHEET, {});

获取工作簿数据

const univerAPI = FUniver.newAPI(univer);
const activeWorkbook = univerAPI.getActiveWorkbook()
const saveData = activeWorkbook.save();

销毁工作簿

当我们不再需要工作簿时，可以调用 FUniver 的 disposeUniverSheet 方法来销毁实例。

const activeWorkbook = univerAPI.getActiveWorkbook()
const unitId = activeWorkbook && activeWorkbook.getId()
if(unitId){
  univerAPI.disposeUnit(unitId)
}

工作表 Worksheet

工作表中存储着表格数据，工作表属于工作薄，

一个工作薄可以包含多个工作表，同一个工作薄中工作表的名称不能重复。

subUnitId 可用作在工作薄中工作表的唯一标识。

获取工作表

获取工作薄中所有工作表

const activeWorkbook = univerAPI.getActiveWorkbook();
const sheets = activeWorkbook.save().sheets;

获取工作薄中当前激活的工作表

const sheet = univerAPI.getActiveWorkbook().getActiveSheet();

获取工作表数据

const activeWorkbook = univerAPI.getActiveWorkbook();
const snapshot = activeWorkbook.save()
const sheet1 = Object.values(snapshot.sheets).find((sheet) => {
  return sheet.name === 'Sheet1'
})

创建工作表

在创建工作薄时，如果不传入参数，会自动创建一个工作表。

下面例子展示通过 Workbook.create 方法创建一个工作表。

const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: zhCN,
  },
});
 
univer.registerPlugin(UniverRenderEnginePlugin);
univer.registerPlugin(UniverFormulaEnginePlugin);
univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
});
 
univer.registerPlugin(UniverDocsPlugin);
univer.registerPlugin(UniverDocsUIPlugin);
 
univer.registerPlugin(UniverSheetsPlugin);
univer.registerPlugin(UniverSheetsUIPlugin);
univer.registerPlugin(UniverSheetsFormulaPlugin);
 
// 传入空对象会自动初始化工作簿
univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})
 
const univerAPI = FUniver.newAPI(univer);
const activeWorkbook = univerAPI.getActiveWorkbook();
 
// 创建一个名为 'Sheet2' 的工作表，包含 10 行和 10 列
const sheet2 = activeWorkbook.create('Sheet2', 10, 10)

删除工作表

删除工作表需要知道工作表的 Id。

import { RemoveSheetCommand } from '@univerjs/sheets'
 
const sheetId = 'SheetId';
univerAPI.executeCommand(RemoveSheetCommand.id, { subUnitId: sheetId });

激活工作表

激活工作表需要知道工作薄的 Id 和工作表的 Id。

import { SetWorksheetActiveOperation } from '@univerjs/sheets'
 
const workbookId = 'WorkbookId';
const sheetId = 'SheetId';
univerAPI.executeCommand(SetWorksheetActiveOperation.id, { unitId: workbookId, subUnitId: sheetId });

核心功能

权限控制

公式

行列操作

范围Range

选区Selection

单元格Cell

冻结

集成自定义组件

与服务端交互的功能

💻

本功能依赖 Univer 后端服务，在使用前请先确保你已经阅读了相关文档，并完成了部署。

导入 XLSX

导入 API 需要使用服务端版本 Facade API 调用导入导出插件提供的功能，使用前确保已经引入对应的依赖。

导入 XLSX 并获取 `unitId`

在协同环境下，每个工作簿都有一个唯一的 unitId。使用 API importXLSXToUnitId 传入 file 参数会返回 unitId，可以通过该 unitId 来访问工作簿。 file 参数可以是一个 File 对象，或者远程文件的 URL。

univerAPI.importXLSXToUnitId(file).then((id)=>{
  console.log(id)
})

导入 XLSX 并获取 Workbook 数据

非协同环境中单独使用导入 XLSX 能力，可使用 API importXLSXToSnapshot 返回 IWorkbookData 格式的工作簿数据。

univerAPI.importXLSXToSnapshot(file).then((data)=>{
  console.log(data)
})

导出 XLSX

导出 API 需要使用服务端版本 Facade API 调用导入导出插件提供的功能，使用前确保已经引入对应的依赖。

通过 `unitId` 导出 XLSX

使用 API exportXLSXByUnitId 传入 unitId 参数，返回一个 File 对象，可以使用 downloadFile 下载文件或进一步处理。

import { downloadFile } from '@univerjs-pro/exchange-client';
univerAPI.exportXLSXByUnitId(unitId).then((file)=>{
  console.log(file);
  downloadFile(file, 'univer', 'xlsx'); // 下载文件
})

通过 Workbook 数据导出 XLSX

使用 API exportXLSXBySnapshot 传入 IWorkbookData 格式的表格数据, 返回一个 File 对象。

可参考获取工作簿数据获取 IWorkbookData 格式的数据。

univerAPI.exportXLSXBySnapshot(snapshot).then((file)=>{
  console.log(file)
})

参考

更多 API 请查看：

基础 API 权限控制