Workbook
| Packages | @univerjs/sheets-ui, @univerjs-pro/sheets-pivot, @univerjs/sheets, @univerjs/sheets-table, @univerjs/sheets-thread-comment, @univerjs-pro/sheets-print, @univerjs-pro/range-preprocess, @univerjs/sheets-data-validation, @univerjs/sheets-formula, @univerjs/sheets-hyper-link-ui, @univerjs/sheets-hyper-link, @univerjs/sheets-numfmt |
|---|
Facade API object bounded to a workbook. It provides a set of methods to interact with the workbook.
This class should not be instantiated directly. Use factory methods on
univerAPIinstead.
Overview
@univerjs/sheets
| Method | Description |
|---|---|
addStyles | Add styles to the workbook styles |
create | Create a new worksheet and returns a handle to it |
createRangeThemeStyle | Create a range theme style |
deleteActiveSheet | Deletes the currently active sheet |
deleteDefinedName | Delete the defined name with the given name |
deleteSheet | Deletes the specified worksheet |
dispose | - |
duplicateActiveSheet | Duplicates the active sheet |
duplicateSheet | Duplicates the given worksheet |
getActiveCell | Returns the active cell in this spreadsheet |
getActiveRange | Returns the selected range in the active sheet, or null if there is no active range |
getActiveSheet | Get the active sheet of the workbook |
getCustomMetadata | Get custom metadata of workbook |
getDefinedName | Get the defined name by name |
getDefinedNames | Get all the defined names in the workbook |
getId | Get the id of the workbook |
getLocale | Get the locale of the workbook |
getName | Get the name of the workbook |
getNumSheets | Get the number of sheets in the workbook |
getRegisteredRangeThemes | Gets the registered range themes |
getSheetByName | Get a worksheet by sheet name |
getSheetBySheetId | Get a worksheet by sheet id |
getSheets | Gets all the worksheets in this workbook |
getSnapshot | - |
getUrl | Get the URL of the workbook |
getWorkbook | Get the Workbook instance |
getWorkbookPermission | Get the WorkbookPermission instance for managing workbook-level permissions |
id | - |
insertDefinedName | Insert a defined name |
insertDefinedNameBuilder | Insert a defined name by builder param |
insertSheet | Inserts a new worksheet into the workbook |
moveActiveSheet | Move the active sheet to the specified index |
moveSheet | Move the sheet to the specified index |
newDefinedNameBuilder | Create a new defined name builder |
onBeforeCommandExecute | Callback for command execution |
onCommandExecuted | Callback for command execution |
onSelectionChange | Callback for selection changes |
redo | Redo the last undone action |
registerRangeTheme | Register a custom range theme style |
removeStyles | Remove styles from the workbook styles |
save | Save workbook snapshot data, including conditional formatting, data validation, and other plugin data |
setActiveRange | Sets the selection region for active sheet |
setActiveSheet | Sets the given worksheet to be the active worksheet in the workbook |
setCustomMetadata | Set custom metadata of workbook |
setEditable | Used to modify the editing permissions of the workbook |
setLocale | - |
setName | Set the name of the workbook |
setSpreadsheetLocale | Set the locale of the workbook |
undo | Undo the last action |
unregisterRangeTheme | Unregister a custom range theme style |
updateDefinedNameBuilder | Update the defined name with the given name |
@univerjs/sheets-data-validation
@univerjs/sheets-formula
| Method | Description |
|---|---|
getAllFormulaError | Get all formula errors in the workbook |
@univerjs/sheets-hyper-link
| Method | Description |
|---|---|
getUrlOfDefineName | Create a hyperlink url for the defined name |
parseSheetHyperlink | Parse the hyperlink string to get the hyperlink info |
@univerjs/sheets-hyper-link-ui
| Method | Description |
|---|---|
navigateToSheetHyperlink | Navigate to the specified hyperlink |
@univerjs/sheets-numfmt
| Method | Description |
|---|---|
setNumfmtLocal | Set the locale for number format display |
@univerjs/sheets-table
| Method | Description |
|---|---|
addTable | - |
getTableInfo | - |
getTableInfoByName | - |
getTableList | - |
removeTable | - |
setTableFilter | - |
@univerjs/sheets-thread-comment
| Method | Description |
|---|---|
clearComments | - |
getComments | - |
@univerjs/sheets-ui
@univerjs-pro/sheets-pivot
| Method | Description |
|---|---|
addPivotTable | - |
getPivotTableByCell | - |
getPivotTableById | - |
@univerjs-pro/sheets-print
| Method | Description |
|---|---|
closePrintDialog | - |
openPrintDialog | - |
print | - |
saveScreenshotToClipboard | - |
updatePrintConfig | - |
updatePrintRenderConfig | - |
@univerjs-pro/range-preprocess
| Method | Description |
|---|---|
getPreprocessRanges | Get all preprocess range information |
APIs
Sheet Operations
create
Create a new worksheet and returns a handle to it.
Signature
create(name: string, rows: number, columns: number, options?: { index?: number; sheet?: Partial<IWorksheetData> }): FWorksheetParameters
namestring— No descriptionrowsnumber— No descriptioncolumnsnumber— No descriptionoptions{ index?: number; sheet?: Partial<IWorksheetData>; }(optional) — No description
Returns
FWorksheet— The new created sheet
Examples
const fWorkbook = univerAPI.getActiveWorkbook();// Create a new sheet named 'MyNewSheet' with 10 rows and 10 columnsconst newSheet = fWorkbook.create('MyNewSheet', 10, 10);console.log(newSheet);// Create a new sheet named 'MyNewSheetWithData' with 10 rows and 10 columns and some data, and set it as the first sheetconst sheetData = { // ... Omit other properties cellData: { 0: { 0: { v: 'Hello Univer!', } } }, // ... Omit other properties};const newSheetWithData = fWorkbook.create('MyNewSheetWithData', 10, 10, { index: 0, sheet: sheetData,});console.log(newSheetWithData);@univerjs/sheets
createRangeThemeStyle
Create a range theme style.
Signature
createRangeThemeStyle(themeName: string, themeStyleJson?: Omit<IRangeThemeStyleJSON, 'name'>): RangeThemeStyleParameters
themeNamestring— No descriptionthemeStyleJsonOmit<IRangeThemeStyleJSON, "name">(optional) — No description
Returns
RangeThemeStyle— - The created range theme style
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', { secondRowStyle: { bg: { rgb: 'rgb(214,231,241)', }, },});console.log(rangeThemeStyle);@univerjs/sheets
deleteActiveSheet
Deletes the currently active sheet.
Signature
deleteActiveSheet(): booleanReturns
boolean— true if the sheet was deleted, false otherwise
Examples
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.deleteActiveSheet();@univerjs/sheets
deleteDefinedName
Delete the defined name with the given name.
Signature
deleteDefinedName(name: string): booleanParameters
namestring— No description
Returns
boolean— true if the defined name was deleted, false otherwise
Examples
// The code below deletes the defined name with the given nameconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.deleteDefinedName('MyDefinedName');@univerjs/sheets
deleteSheet
Deletes the specified worksheet.
Signature
deleteSheet(sheet: FWorksheet | string): booleanParameters
sheetstring | FWorksheet— No description
Returns
boolean— True if the worksheet was deleted, false otherwise.
Examples
// The code below deletes the specified worksheetconst fWorkbook = univerAPI.getActiveWorkbook();const sheet = fWorkbook.getSheets()[1];fWorkbook.deleteSheet(sheet);// The code below deletes the specified worksheet by id// fWorkbook.deleteSheet(sheet.getSheetId());@univerjs/sheets
getActiveSheet
Get the active sheet of the workbook.
Signature
getActiveSheet(): FWorksheetReturns
FWorksheet— The active sheet of the workbook
Examples
// The code below gets the active sheet of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();console.log(fWorksheet);@univerjs/sheets
getSheetByName
Get a worksheet by sheet name.
Signature
getSheetByName(name: string): FWorksheet | nullParameters
namestring— No description
Returns
FWorksheet— The worksheet with given sheet name
Examples
// The code below gets a worksheet by sheet nameconst fWorkbook = univerAPI.getActiveWorkbook();const sheet = fWorkbook.getSheetByName('Sheet1');console.log(sheet);@univerjs/sheets
getSheetBySheetId
Get a worksheet by sheet id.
Signature
getSheetBySheetId(sheetId: string): FWorksheet | nullParameters
sheetIdstring— No description
Returns
FWorksheet— The worksheet with given sheet id
Examples
// The code below gets a worksheet by sheet idconst fWorkbook = univerAPI.getActiveWorkbook();const sheet = fWorkbook.getSheetBySheetId('sheetId');console.log(sheet);@univerjs/sheets
getSheets
Gets all the worksheets in this workbook
Signature
getSheets(): FWorksheet[]Returns
FWorksheet[]— An array of all the worksheets in the workbook
Examples
// The code below gets all the worksheets in the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const sheets = fWorkbook.getSheets();console.log(sheets);@univerjs/sheets
insertDefinedName
Insert a defined name.
Signature
insertDefinedName(name: string, formulaOrRefString: string): FWorkbookParameters
namestring— No descriptionformulaOrRefStringstring— No description
Returns
FWorkbook— The current FWorkbook instance
Examples
// The code below inserts a defined nameconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!$A$1');@univerjs/sheets
insertDefinedNameBuilder
Insert a defined name by builder param.
Signature
insertDefinedNameBuilder(param: ISetDefinedNameMutationParam): voidParameters
paramISetDefinedNameMutationParam— No description
Examples
// The code below inserts a defined name by builder paramconst fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder() .setRef('Sheet1!$A$1') .setName('MyDefinedName') .setComment('This is a comment') .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);@univerjs/sheets
newDefinedNameBuilder
Create a new defined name builder.
Signature
newDefinedNameBuilder(): FDefinedNameBuilderReturns
FDefinedNameBuilder— The defined name builder.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const definedNameParam = fWorkbook.newDefinedNameBuilder() .setRef('Sheet1!$A$1') .setName('MyDefinedName') .setComment('This is a comment') .build();console.log(definedNameParam);fWorkbook.insertDefinedNameBuilder(definedNameParam);@univerjs/sheets
insertSheet
Inserts a new worksheet into the workbook. Using a default sheet name. The new sheet becomes the active sheet
Signature
insertSheet(sheetName?: string, options?: { index?: number; sheet?: Partial<IWorksheetData> }): FWorksheetParameters
sheetNamestring(optional) — No descriptionoptions{ index?: number; sheet?: Partial<IWorksheetData>; }(optional) — No description
Returns
FWorksheet— The new sheet
Examples
const fWorkbook = univerAPI.getActiveWorkbook();// Create a new sheet with default configurationconst newSheet = fWorkbook.insertSheet();console.log(newSheet);// Create a new sheet with custom name and default configurationconst newSheetWithName = fWorkbook.insertSheet('MyNewSheet');console.log(newSheetWithName);// Create a new sheet with custom name and custom configurationconst sheetData = { // ... Omit other properties cellData: { 0: { 0: { v: 'Hello Univer!', } } }, // ... Omit other properties};const newSheetWithData = fWorkbook.insertSheet('MyNewSheetWithData', { index: 0, sheet: sheetData,});console.log(newSheetWithData);@univerjs/sheets
Defined Names
getDefinedName
Get the defined name by name.
Signature
getDefinedName(name: string): FDefinedName | nullParameters
namestring— No description
Returns
FDefinedName— The defined name with the given name
Examples
// The code below gets the defined name by nameconst fWorkbook = univerAPI.getActiveWorkbook();const definedName = fWorkbook.getDefinedName('MyDefinedName');console.log(definedName?.getFormulaOrRefString());@univerjs/sheets
getDefinedNames
Get all the defined names in the workbook.
Signature
getDefinedNames(): FDefinedName[]Returns
FDefinedName[]— All the defined names in the workbook
Examples
// The code below gets all the defined names in the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const definedNames = fWorkbook.getDefinedNames();console.log(definedNames, definedNames[0]?.getFormulaOrRefString());@univerjs/sheets
getName
Get the name of the workbook.
Signature
getName(): stringReturns
string— The name of the workbook.
Examples
// The code below gets the name of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const name = fWorkbook.getName();console.log(name);@univerjs/sheets
getTableInfoByName
Signature
getTableInfoByName(tableName: string): ITableInfoWithUnitId | undefinedParameters
tableNamestring— No description
Returns
any— See signature above.
@univerjs/sheets-table
setName
Set the name of the workbook.
Signature
setName(name: string): thisParameters
namestring— No description
Returns
this— See signature above.
Examples
// The code below sets the name of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setName('MyWorkbook');@univerjs/sheets
updateDefinedNameBuilder
Update the defined name with the given name.
Signature
updateDefinedNameBuilder(param: ISetDefinedNameMutationParam): voidParameters
paramISetDefinedNameMutationParam— No description
Examples
// The code below updates the defined name with the given nameconst fWorkbook = univerAPI.getActiveWorkbook();const definedName = fWorkbook.getDefinedName('MyDefinedName');console.log(definedName?.getFormulaOrRefString());// Update the defined nameif (definedName) { const newDefinedNameParam = definedName.toBuilder() .setName('NewDefinedName') .setRef('Sheet1!$A$2') .build(); fWorkbook.updateDefinedNameBuilder(newDefinedNameParam);}@univerjs/sheets
Range Themes
getRegisteredRangeThemes
Gets the registered range themes.
Signature
getRegisteredRangeThemes(): string[]Returns
string[]— The name list of registered range themes.
Examples
// The code below gets the registered range themesconst fWorkbook = univerAPI.getActiveWorkbook();const themes = fWorkbook.getRegisteredRangeThemes();console.log(themes);@univerjs/sheets
registerRangeTheme
Register a custom range theme style.
Signature
registerRangeTheme(rangeThemeStyle: RangeThemeStyle): voidParameters
rangeThemeStyleRangeThemeStyle— No description
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', { secondRowStyle: { bg: { rgb: 'rgb(214,231,241)', }, },});fWorkbook.registerRangeTheme(rangeThemeStyle);@univerjs/sheets
unregisterRangeTheme
Unregister a custom range theme style.
Signature
unregisterRangeTheme(themeName: string): voidParameters
themeNamestring— No description
Examples
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.unregisterRangeTheme('MyTheme');@univerjs/sheets
Range Preprocess
getPreprocessRanges
Get all preprocess range information.
Signature
getPreprocessRanges(responseDataMode?: string): Record<string, ITableJson[]>Parameters
responseDataModestring(optional) — The response data mode.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()const preprocessRanges = fWorkbook.getPreprocessRanges()@univerjs-pro/range-preprocess
Collaboration
getSnapshot
Signature
getSnapshot(): IWorkbookDataReturns
IWorkbookData— Workbook snapshot data
Tags
@memberof— FWorkbook
Examples
// The code below saves the workbook snapshot dataconst activeSpreadsheet = univerAPI.getActiveWorkbook();const snapshot = activeSpreadsheet.getSnapshot();@univerjs/sheets
Pivot Tables
addPivotTable
Signature
async addPivotTable(sourceInfo: IUnitRangeName & { subUnitId: string }, positionType: PositionType, anchorCellInfo: IPivotCellPositionInfo): Promise<FPivotTable | undefined>Parameters
sourceInfoany— No descriptionpositionTypePositionType— No descriptionanchorCellInfoIPivotCellPositionInfo— No description
Returns
Promise<FPivotTable>— See signature above.
@univerjs-pro/sheets-pivot
getPivotTableByCell
Signature
getPivotTableByCell(unitId: string, subUnitId: string, row: number, col: number): FPivotTable | undefinedParameters
unitIdstring— No descriptionsubUnitIdstring— No descriptionrownumber— No descriptioncolnumber— No description
Returns
FPivotTable— See signature above.
@univerjs-pro/sheets-pivot
getPivotTableById
Signature
getPivotTableById(pivotTableId: string): FPivotTable | undefinedParameters
pivotTableIdstring— No description
Returns
FPivotTable— See signature above.
@univerjs-pro/sheets-pivot
Miscellaneous
abortEditingAsync
Signature
abortEditingAsync(): Promise<boolean>Returns
Promise<boolean>— See signature above.
@univerjs/sheets-ui
addStyles
Add styles to the workbook styles.
Signature
addStyles(styles: Record<string, IStyleData>): voidParameters
stylesRecord<string, IStyleData>— No description
Examples
const fWorkbook = univerAPI.getActiveWorkbook();// Add styles to the workbook stylesconst styles = { 'custom-style-1': { bg: { rgb: 'rgb(255, 0, 0)', } }, 'custom-style-2': { fs: 20, n: { pattern: '@' } }};fWorkbook.addStyles(styles);// Set values with the new stylesconst fWorksheet = fWorkbook.getActiveSheet();const fRange = fWorksheet.getRange('A1:B2');fRange.setValues([ [{ v: 'Hello', s: 'custom-style-1' }, { v: 'Univer', s: 'custom-style-1' }], [{ v: 'To', s: 'custom-style-1' }, { v: '0001', s: 'custom-style-2' }],]);@univerjs/sheets
clearComments
Signature
clearComments(): Promise<boolean>Returns
Promise<boolean>— See signature above.
@univerjs/sheets-thread-comment
customizeColumnHeader
Signature
customizeColumnHeader(cfg: IColumnsHeaderCfgParam): voidParameters
cfgIColumnsHeaderCfgParam— No description
@univerjs/sheets-ui
customizeRowHeader
Signature
customizeRowHeader(cfg: IRowsHeaderCfgParam): voidParameters
cfgIRowsHeaderCfgParam— No description
@univerjs/sheets-ui
disableSelection
Signature
disableSelection(): FWorkbookReturns
FWorkbook— See signature above.
@univerjs/sheets-ui
dispose
Signature
dispose(): void@univerjs/sheets
duplicateActiveSheet
Duplicates the active sheet.
Signature
duplicateActiveSheet(): FWorksheetReturns
FWorksheet— The duplicated worksheet
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const duplicatedSheet = fWorkbook.duplicateActiveSheet();console.log(duplicatedSheet);@univerjs/sheets
duplicateSheet
Duplicates the given worksheet.
Signature
duplicateSheet(sheet: FWorksheet): FWorksheetParameters
sheetFWorksheet— No description
Returns
FWorksheet— The duplicated worksheet
Examples
// The code below duplicates the given worksheetconst fWorkbook = univerAPI.getActiveWorkbook();const activeSheet = fWorkbook.getActiveSheet();const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet);console.log(duplicatedSheet);@univerjs/sheets
enableSelection
Signature
enableSelection(): FWorkbookReturns
FWorkbook— See signature above.
@univerjs/sheets-ui
endEditing
Signature
async endEditing(save?: boolean): Promise<boolean>Parameters
saveboolean(optional) — No description
Returns
Promise<boolean>— See signature above.
@univerjs/sheets-ui
endEditingAsync
Signature
endEditingAsync(save = true): Promise<boolean>Parameters
saveboolean(optional) — No description
Returns
Promise<boolean>— See signature above.
@univerjs/sheets-ui
getActiveCell
Returns the active cell in this spreadsheet.
Signature
getActiveCell(): FRange | nullReturns
FRange— The active cell
Examples
const fWorkbook = univerAPI.getActiveWorkbook();console.log(fWorkbook.getActiveCell().getA1Notation());@univerjs/sheets
getActiveRange
Returns the selected range in the active sheet, or null if there is no active range.
Signature
getActiveRange(): FRange | nullReturns
FRange— The active range
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const activeRange = fWorkbook.getActiveRange();console.log(activeRange);@univerjs/sheets
getAllDataValidationErrorAsync
Signature
async getAllDataValidationErrorAsync(): Promise<IDataValidationError[]>Returns
Promise<IDataValidationError[]>— See signature above.
@univerjs/sheets-data-validation
getAllFormulaError
Get all formula errors in the workbook.
Signature
getAllFormulaError(): ISheetFormulaError[]Returns
ISheetFormulaError[]— Array of formula errors.
@univerjs/sheets-formula
getComments
Signature
getComments(): FThreadComment[]Returns
FThreadComment[]— See signature above.
@univerjs/sheets-thread-comment
getCustomMetadata
Get custom metadata of workbook
Signature
getCustomMetadata(): CustomData | undefinedReturns
CustomData— custom metadata
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const custom = fWorkbook.getCustomMetadata();console.log(custom);@univerjs/sheets
getId
Get the id of the workbook.
Signature
getId(): stringReturns
string— The id of the workbook.
Examples
// The code below gets the id of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const unitId = fWorkbook.getId();console.log(unitId);@univerjs/sheets
getLocale
Get the locale of the workbook.
Signature
getLocale(): LocaleTypeReturns
LocaleType— The locale of the workbook
Examples
// The code below gets the locale of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();console.log(fWorkbook.getLocale());@univerjs/sheets
getNumSheets
Get the number of sheets in the workbook.
Signature
getNumSheets(): numberReturns
number— The number of sheets in the workbook
Examples
// The code below gets the number of sheets in the workbookconst fWorkbook = univerAPI.getActiveWorkbook();console.log(fWorkbook.getNumSheets());@univerjs/sheets
getScrollStateBySheetId
Get scroll state of specified sheet.
Signature
getScrollStateBySheetId(sheetId: string): Nullable<IScrollState>Parameters
sheetIdstring— No description
Returns
any— scroll state
Examples
tsuniverAPI.getActiveWorkbook().getScrollStateBySheetId($sheetId)@univerjs/sheets-ui
getUrl
Get the URL of the workbook.
Signature
getUrl(): stringReturns
string— The URL of the workbook
Examples
// The code below gets the URL of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const url = fWorkbook.getUrl();console.log(url);@univerjs/sheets
getValidatorStatus
Signature
getValidatorStatus(): Promise<Record<string, ObjectMatrix<Nullable<DataValidationStatus>>>>Returns
Promise<Record<string, ObjectMatrix<Nullable<DataValidationStatus>>>>— See signature above.
@univerjs/sheets-data-validation
getWorkbook
Get the Workbook instance.
Signature
getWorkbook(): WorkbookReturns
Workbook— The Workbook instance.
Examples
// The code below gets the Workbook instanceconst fWorkbook = univerAPI.getActiveWorkbook();const workbook = fWorkbook.getWorkbook();console.log(workbook);@univerjs/sheets
getWorkbookPermission
Get the WorkbookPermission instance for managing workbook-level permissions. This is the new permission API that provides a more intuitive and type-safe interface.
Signature
getWorkbookPermission(): FWorkbookPermissionReturns
FWorkbookPermission— - The WorkbookPermission instance.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const permission = fWorkbook.getWorkbookPermission();// Set workbook to read-only modeawait permission.setMode('viewer');// Add a collaboratorawait permission.addCollaborator({ userId: 'user123', name: 'John Doe', role: 'editor'});// Subscribe to permission changespermission.permission$.subscribe(snapshot => { console.log('Permissions changed:', snapshot);});@univerjs/sheets
id
Signature
id: stringReturns
string— See signature above.
@univerjs/sheets
isCellEditing
Signature
isCellEditing(): booleanReturns
boolean— See signature above.
@univerjs/sheets-ui
moveActiveSheet
Move the active sheet to the specified index.
Signature
moveActiveSheet(index: number): FWorkbookParameters
indexnumber— No description
Returns
FWorkbook— This workbook, for chaining
Examples
// The code below moves the active sheet to the specified indexconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.moveActiveSheet(1);@univerjs/sheets
moveSheet
Move the sheet to the specified index.
Signature
moveSheet(sheet: FWorksheet, index: number): FWorkbookParameters
sheetFWorksheet— No descriptionindexnumber— No description
Returns
FWorkbook— This workbook, for chaining
Examples
// The code below moves the sheet to the specified indexconst fWorkbook = univerAPI.getActiveWorkbook();const sheet = fWorkbook.getActiveSheet();fWorkbook.moveSheet(sheet, 1);@univerjs/sheets
navigateToSheetHyperlink
Navigate to the specified hyperlink within the workbook.
Signature
navigateToSheetHyperlink(hyperlink: string): voidParameters
hyperlinkstring— The hyperlink string to navigate to.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.navigateToSheetHyperlink('#gid=sheet1&range=A1');@univerjs/sheets-hyper-link-ui
onBeforeAddDataValidation
Signature
onBeforeAddDataValidation(callback: (params: IAddSheetDataValidationCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposableParameters
callback(params: IAddSheetDataValidationCommandParams, options: IExecutionOptions) => false | void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-data-validation
onBeforeCommandExecute
Callback for command execution.
Signature
onBeforeCommandExecute(callback: CommandListener): IDisposableParameters
callbackCommandListener— No description
Returns
IDisposable— See signature above.
Tags
@callback— onBeforeCommandExecuteCallback
@univerjs/sheets
onBeforeDeleteAllDataValidation
Signature
onBeforeDeleteAllDataValidation(callback: (params: IRemoveSheetAllDataValidationCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposableParameters
callback(params: IRemoveSheetAllDataValidationCommandParams, options: IExecutionOptions) => false | void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-data-validation
onBeforeDeleteDataValidation
Signature
onBeforeDeleteDataValidation(callback: (params: IRemoveSheetDataValidationCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposableParameters
callback(params: IRemoveSheetDataValidationCommandParams, options: IExecutionOptions) => false | void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-data-validation
onBeforeUpdateDataValidationCriteria
Signature
onBeforeUpdateDataValidationCriteria(callback: (params: IUpdateSheetDataValidationSettingCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposableParameters
callback(params: IUpdateSheetDataValidationSettingCommandParams, options: IExecutionOptions) => false | void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-data-validation
onBeforeUpdateDataValidationOptions
Signature
onBeforeUpdateDataValidationOptions(callback: (params: IUpdateSheetDataValidationOptionsCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposableParameters
callback(params: IUpdateSheetDataValidationOptionsCommandParams, options: IExecutionOptions) => false | void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-data-validation
onBeforeUpdateDataValidationRange
Signature
onBeforeUpdateDataValidationRange(callback: (params: IUpdateSheetDataValidationRangeCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposableParameters
callback(params: IUpdateSheetDataValidationRangeCommandParams, options: IExecutionOptions) => false | void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-data-validation
onCellClick
Signature
onCellClick(callback: (cell: IHoverRichTextInfo) => void): IDisposableParameters
callback(cell: IHoverRichTextInfo) => void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-ui
onCellHover
Signature
onCellHover(callback: (cell: IHoverRichTextPosition) => void): IDisposableParameters
callback(cell: IHoverRichTextPosition) => void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-ui
onCellPointerDown
Signature
onCellPointerDown(callback: (cell: ICellPosWithEvent) => void): IDisposableParameters
callback(cell: ICellPosWithEvent) => void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-ui
onCellPointerMove
Signature
onCellPointerMove(callback: (cell: ICellPosWithEvent, event: IPointerEvent | IMouseEvent) => void): IDisposableParameters
callback(cell: ICellPosWithEvent, event: IPointerEvent | IMouseEvent) => void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-ui
onCellPointerUp
Signature
onCellPointerUp(callback: (cell: ICellPosWithEvent) => void): IDisposableParameters
callback(cell: ICellPosWithEvent) => void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-ui
onCommandExecuted
Callback for command execution.
Signature
onCommandExecuted(callback: CommandListener): IDisposableParameters
callbackCommandListener— No description
Returns
IDisposable— See signature above.
Tags
@callback— onCommandExecutedCallback
@univerjs/sheets
onDragOver
Signature
onDragOver(callback: (cell: IDragCellPosition) => void): IDisposableParameters
callback(cell: IDragCellPosition) => void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-ui
onDrop
Signature
onDrop(callback: (cell: IDragCellPosition) => void): IDisposableParameters
callback(cell: IDragCellPosition) => void— No description
Returns
IDisposable— See signature above.
@univerjs/sheets-ui
onSelectionChange
Callback for selection changes.
Signature
onSelectionChange(callback: (selections: IRange[]) => void): IDisposableParameters
callback(selections: IRange[]) => void— No description
Returns
IDisposable— See signature above.
Tags
@callback— onSelectionChangeCallback
@univerjs/sheets
parseSheetHyperlink
Parse the hyperlink string to get the hyperlink info.
Signature
parseSheetHyperlink(hyperlink: string): ISheetHyperLinkInfoParameters
hyperlinkstring— The hyperlink string to parse.
Returns
ISheetHyperLinkInfo— The parsed hyperlink info, including type, name, URL, and search parameters.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const info = fWorkbook.parseSheetHyperlink('#gid=sheet1&range=A1');console.log(info);@univerjs/sheets-hyper-link
getUrlOfDefineName
Create a hyperlink url for the defined name. The defined name must exist in the current workbook and must be a reference to a range, otherwise an error will be thrown.
Signature
getUrlOfDefineName(name: string): stringParameters
namestring— The name of the defined name.
Returns
string— The hyperlink url of the defined name.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();// Create a defined name "TestRange" for the range A1:B10 of the active sheetconst definedNameParam = fWorkbook.newDefinedNameBuilder() .setName('TestRange') .setRef('Sheet1!$A$1:$B$10') .build();fWorkbook.insertDefinedNameBuilder(definedNameParam);// Create a hyperlink to the defined name "TestRange" on cell C1const url = fWorkbook.getUrlOfDefineName('TestRange');console.log(url);const fRange = fWorksheet.getRange('C1');fRange.setHyperLink(url, 'Link to TestRange');// Create a hyperlink to the exiting defined name on cell C2const definedNames = fWorkbook.getDefinedNames();console.log(definedNames);const exitsDefinedNameUrl = fWorkbook.getUrlOfDefineName(definedNames[0].getName());console.log(exitsDefinedNameUrl);const fRange2 = fWorksheet.getRange('C2');fRange2.setHyperLink(exitsDefinedNameUrl, `Link to ${definedNames[0].getName()}`);@univerjs/sheets-hyper-link
redo
Redo the last undone action.
Signature
redo(): FWorkbookReturns
FWorkbook— A promise that resolves to true if the redo was successful, false otherwise.
Examples
// The code below redoes the last undone actionconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.redo();@univerjs/sheets
removeStyles
Remove styles from the workbook styles.
Signature
removeStyles(styleKeys: string[]): voidParameters
styleKeysstring[]— No description
Examples
const fWorkbook = univerAPI.getActiveWorkbook();// Add styles to the workbook stylesconst styles = { 'custom-style-1': { bg: { rgb: 'rgb(255, 0, 0)', } }, 'custom-style-2': { fs: 20, n: { pattern: '@' } }};fWorkbook.addStyles(styles);// Set values with the new stylesconst fWorksheet = fWorkbook.getActiveSheet();const fRange = fWorksheet.getRange('A1:B2');fRange.setValues([ [{ v: 'Hello', s: 'custom-style-1' }, { v: 'Univer', s: 'custom-style-1' }], [{ v: 'To', s: 'custom-style-1' }, { v: '0001', s: 'custom-style-2' }],]);// Remove the style `custom-style-1` after 2 secondssetTimeout(() => { fWorkbook.removeStyles(['custom-style-1']); fWorksheet.refreshCanvas();}, 2000);@univerjs/sheets
save
Save workbook snapshot data, including conditional formatting, data validation, and other plugin data.
Signature
save(): IWorkbookDataReturns
IWorkbookData— Workbook snapshot data
Examples
// The code below saves the workbook snapshot dataconst fWorkbook = univerAPI.getActiveWorkbook();const snapshot = fWorkbook.save();console.log(snapshot);@univerjs/sheets
saveScreenshotToClipboard
Signature
async saveScreenshotToClipboard(): Promise<boolean>Returns
Promise<boolean>— See signature above.
@univerjs-pro/sheets-print
setActiveRange
Sets the selection region for active sheet.
Signature
setActiveRange(range: FRange): FWorkbookParameters
rangeFRange— No description
Returns
FWorkbook— FWorkbook instance
Examples
const fWorkbook = univerAPI.getActiveWorkbook();const range = fWorkbook.getActiveSheet().getRange('A10:B10');fWorkbook.setActiveRange(range);@univerjs/sheets
setActiveSheet
Sets the given worksheet to be the active worksheet in the workbook.
Signature
setActiveSheet(sheet: FWorksheet | string): FWorksheetParameters
sheetstring | FWorksheet— No description
Returns
FWorksheet— The active worksheet
Examples
// The code below sets the given worksheet to be the active worksheetconst fWorkbook = univerAPI.getActiveWorkbook();const sheet = fWorkbook.getSheets()[1];fWorkbook.setActiveSheet(sheet);@univerjs/sheets
setCustomMetadata
Set custom metadata of workbook
Signature
setCustomMetadata(custom: CustomData | undefined): FWorkbookParameters
customCustomData— metadata
Returns
FWorkbook— FWorkbook
Examples
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setCustomMetadata({ key: 'value' });@univerjs/sheets
setLocale
setSpreadsheetLocale instead.Signature
setLocale(locale: LocaleType): voidParameters
localeLocaleType— No description
@univerjs/sheets
setNumfmtLocal
Set the locale for number format display. This affects how numbers, dates, and currencies are formatted in the workbook.
Signature
setNumfmtLocal(locale: INumfmtLocaleTag): FWorkbookParameters
localeINumfmtLocaleTag— The locale tag to use (e.g.'en_US','zh_CN','de_DE').
Returns
FWorkbook— The current workbook instance, for chaining.
Examples
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setNumfmtLocal('de_DE');@univerjs/sheets-numfmt
setPermissionDialogVisible
Signature
setPermissionDialogVisible(visible: boolean): voidParameters
visibleboolean— No description
@univerjs/sheets-ui
setSpreadsheetLocale
Set the locale of the workbook.
Signature
setSpreadsheetLocale(locale: LocaleType): FWorkbookParameters
localeLocaleType— No description
Returns
FWorkbook— This workbook, for chaining
Examples
// The code below sets the locale of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setSpreadsheetLocale(univerAPI.Enum.LocaleType.EN_US);console.log(fWorkbook.getLocale());@univerjs/sheets
showSelection
Signature
showSelection(): FWorkbookReturns
FWorkbook— See signature above.
@univerjs/sheets-ui
startEditing
Signature
startEditing(): booleanReturns
boolean— See signature above.
@univerjs/sheets-ui
transparentSelection
Signature
transparentSelection(): FWorkbookReturns
FWorkbook— See signature above.
@univerjs/sheets-ui
undo
Undo the last action.
Signature
undo(): FWorkbookReturns
FWorkbook— A promise that resolves to true if the undo was successful, false otherwise.
Examples
// The code below undoes the last actionconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.undo();@univerjs/sheets
closePrintDialog
Signature
closePrintDialog(): void@univerjs-pro/sheets-print
openPrintDialog
Signature
openPrintDialog(): void@univerjs-pro/sheets-print
print
Signature
print(): void@univerjs-pro/sheets-print
updatePrintConfig
Signature
updatePrintConfig(config: ISheetPrintLayoutConfig): FWorkbookParameters
configISheetPrintLayoutConfig— No description
Returns
FWorkbook— See signature above.
@univerjs-pro/sheets-print
updatePrintRenderConfig
Signature
updatePrintRenderConfig(config: ISheetPrintRenderConfig): FWorkbookParameters
configISheetPrintRenderConfig— No description
Returns
FWorkbook— See signature above.
@univerjs-pro/sheets-print
Tables
addTable
Signature
async addTable(subUnitId: string, tableName: string, rangeInfo: ITableRange, tableId?: string, options?: ITableOptions): Promise<string | undefined>Parameters
subUnitIdstring— No descriptiontableNamestring— No descriptionrangeInfoITableRange— No descriptiontableIdstring(optional) — No descriptionoptionsITableOptions(optional) — No description
Returns
Promise<string>— See signature above.
@univerjs/sheets-table
getTableInfo
Signature
getTableInfo(tableId: string): ITableInfoWithUnitId | undefinedParameters
tableIdstring— No description
Returns
any— See signature above.
@univerjs/sheets-table
getTableList
Signature
getTableList(): ITableInfoWithUnitId[]Returns
ITableInfoWithUnitId[]— See signature above.
@univerjs/sheets-table
removeTable
Signature
async removeTable(tableId: string): Promise<boolean>Parameters
tableIdstring— No description
Returns
Promise<boolean>— See signature above.
@univerjs/sheets-table
setEditable
Used to modify the editing permissions of the workbook. When the value is false, editing is not allowed.
Signature
setEditable(value: boolean): FWorkbookParameters
valueboolean— No description
Returns
FWorkbook— FWorkbook instance
Examples
// The code below sets the editing permissions of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setEditable(false);@univerjs/sheets
setTableFilter
Signature
setTableFilter(tableId: string, column: number, filter: ITableFilterItem | undefined): Promise<boolean>Parameters
tableIdstring— No descriptioncolumnnumber— No descriptionfilterany— No description
Returns
Promise<boolean>— See signature above.
@univerjs/sheets-tableHow is this guide?