🎉 v0.5.0 is released. Read more →
GuidesUniver SheetsFeaturesCoreSheet API

Univer Sheets API

Concepts

Univer table-related concepts are designed to be as consistent as possible with Excel.

Workbook

A workbook contains multiple worksheets and can be thought of as an Excel file.

The unitId can be used as a unique identifier for the workbook.

Create a Workbook

The univer.createUnit(UniverInstanceType.UNIVER_SHEET, {}) method creates and returns the Workbook object.

Getting Workbook Data

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

Unload Workbook

When you no longer need a Workbook, you can call the disposeUnit method on the API instance to unload it.

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

Worksheet

Worksheets store table data, worksheets belong to the workbook.

A workbook can contain multiple worksheets, and the names of worksheets in the same workbook cannot be duplicated.

The subUnitId can be used to uniquely identify a sheet in a workbook.

Get Worksheets

Get all sheets in a sheet

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

Get Active Worksheet

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

Get Worksheet Data

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

Create a Worksheet

When creating a workbook, if no parameters are passed, a worksheet will be automatically created.

The following example shows how to create a worksheet using the Workbook.create method.

Remove Worksheet

Remove Worksheet by worksheet id

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

Activate Worksheet

To activate a worksheet, you need to know the workbook id and the sheet id.

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

Core Features

Permission

Formula

Row and Column

Range

Selection

Cell

Freeze

Integrating Custom Components into Univer

Server-Related Features

💻
This feature depends on the Univer backend service. Please make sure you have read the related documentation and completed the deployment before using it.

Import XLSX

To import via API, use the Server Version of the Facade API to call the features provided by the import/export plugin. Make sure to include the necessary dependencies before use.

Import XLSX and Get unitId

In a collaborative environment, each workbook has a unique unitId. Use the API importXLSXToUnitId to pass in the file parameter and return unitId, which can be used to access the workbook. The file parameter can be a File object or a URL to a remote file.

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

Import XLSX and Get Workbook Data

When using the import XLSX capability separately in a non-collaborative environment, you can use the API importXLSXToSnapshot to return the workbook data in the IWorkbookData format.

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

Export XLSX

To export via API, use the Server Version of the Facade API to call the features provided by the import/export plugin. Make sure to include the necessary dependencies before use.

Export XLSX via unitId

Use the API exportXLSXByUnitId to pass in the unitId parameter and return an File object. You can use downloadFile to download the file or process it further.

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

Export XLSX via Workbook Data

Use the API exportXLSXBySnapshot to pass in the table data in the IWorkbookData format and return a File object.

You can refer to Getting Workbook Data to get the data in the IWorkbookData format.

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

Reference

Please refer to the following API documentation for more information:

Basic APIPermission