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.

The workbookData is an object that contains the configuration information of the workbook.


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);
 
// Passing in an empty object will automatically initialize the workbook
univer.createUnit(UniverInstanceType.UNIVER_SHEET, {});

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)
}

⚠️

When the entire page hosting the Univer instance is destroyed or the route is unloaded, make sure to call the univer.dispose() method for cleanup, rather than using univerAPI.disposeUnit.
Also, please note that univer and univerAPI are different instances. For instructions on how to obtain these instances, refer to the Installation & Basic Usage.

Getting Workbook ID


const activeWorkbook = univerAPI.getActiveWorkbook()
const unitId = activeWorkbook && activeWorkbook.getId()

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.


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);
 
// Passing in an empty object will automatically initialize the workbook
univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})
 
const univerAPI = FUniver.newAPI(univer);
const activeWorkbook = univerAPI.getActiveWorkbook();
 
// Create a worksheet named 'Sheet2' with 10 rows and 10 columns
const sheet2 = activeWorkbook.create('Sheet2', 10, 10)

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 });

Getting Worksheet ID


const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
const sheetId = sheet && sheet.getSheetId();

Reference

Please refer to the following API documentation for more information:

Univer Sheets API

Concepts

Workbook

Create a Workbook

Getting Workbook Data

Unload Workbook

Getting Workbook ID

Worksheet

Get Worksheets

Get Worksheet Data

Create a Worksheet

Remove Worksheet

Activate Worksheet

Getting Worksheet ID

Core Features

Permission

Formula

Row and Column

Range

Selection

Cell

Freeze

Integrating Custom Components into Univer

Reference