FWorkbook
| packages | @univerjs/sheets |
|---|
Facade API object bounded to a workbook. It provides a set of methods to interact with the workbook.
APIs
addStyles
Add styles to the workbook styles.
Signature
addStyles(styles: Record<string, IStyleData>): voidParameters
styles(Record<string, IStyleData>) — Styles to add
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
// Add styles to the workbook styles
const 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 styles
const 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' }],
])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
name(string) — Name of the new sheetrows(number) — How many rows would the new sheet havecolumns(number) — How many columns would the new sheet haveoptions({ index?: number; sheet?: Partial<IWorksheetData> }) — The options for the new sheetoptions.index— The position index where the new sheet is to be insertedoptions.sheet— The data configuration for the new sheet
Returns
- (
FWorksheet) — The new created sheet
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
// Create a new sheet named 'MyNewSheet' with 10 rows and 10 columns
const 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 sheet
const 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)createRangeThemeStyle
Create a range theme style.
Signature
createRangeThemeStyle(themeName: string, themeStyleJson?: Omit<IRangeThemeStyleJSON, 'name'>): RangeThemeStyleParameters
themeName(string) — - The name of the theme to registerthemeStyleJson(Omit<IRangeThemeStyleJSON, 'name'>) — - The theme style json to register
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)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()deleteDefinedName
Delete the defined name with the given name.
Signature
deleteDefinedName(name: string): booleanParameters
name(string) — The name of the defined name to delete
Returns
- (
boolean) — true if the defined name was deleted, false otherwise
Examples
// The code below deletes the defined name with the given name
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.deleteDefinedName('MyDefinedName')deleteSheet
Deletes the specified worksheet.
Signature
deleteSheet(sheet: FWorksheet | string): booleanParameters
sheet(FWorksheet | string) — The instance or id of the worksheet to delete.
Returns
- (
boolean) — True if the worksheet was deleted, false otherwise.
Examples
// The code below deletes the specified worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.deleteSheet(sheet)
// The code below deletes the specified worksheet by id
// fWorkbook.deleteSheet(sheet.getSheetId());dispose
Signature
dispose(): voidduplicateActiveSheet
Duplicates the active sheet.
Signature
duplicateActiveSheet(): FWorksheetReturns
- (
FWorksheet) — The duplicated worksheet
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
const duplicatedSheet = fWorkbook.duplicateActiveSheet()
console.log(duplicatedSheet)duplicateSheet
Duplicates the given worksheet.
Signature
duplicateSheet(sheet: FWorksheet): FWorksheetParameters
sheet(FWorksheet) — The worksheet to duplicate.
Returns
- (
FWorksheet) — The duplicated worksheet
Examples
// The code below duplicates the given worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const activeSheet = fWorkbook.getActiveSheet()
const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet)
console.log(duplicatedSheet)getActiveCell
Returns the active cell in this spreadsheet.
Signature
getActiveCell(): FRange | nullReturns
- (
FRange | null) — The active cell
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
console.log(fWorkbook.getActiveCell().getA1Notation())getActiveRange
Returns the selected range in the active sheet, or null if there is no active range.
Signature
getActiveRange(): FRange | nullReturns
- (
FRange | null) — The active range
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
const activeRange = fWorkbook.getActiveRange()
console.log(activeRange)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 workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
console.log(fWorksheet)getCustomMetadata
Get custom metadata of workbook
Signature
getCustomMetadata(): CustomData | undefinedReturns
- (
CustomData | undefined) — custom metadata
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
const custom = fWorkbook.getCustomMetadata()
console.log(custom)getDefinedName
Get the defined name by name.
Signature
getDefinedName(name: string): FDefinedName | nullParameters
name(string) — The name of the defined name to get
Returns
- (
FDefinedName | null) — The defined name with the given name
Examples
// The code below gets the defined name by name
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())
if (definedName) {
definedName.setName('NewDefinedName')
}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 workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const definedNames = fWorkbook.getDefinedNames()
console.log(definedNames, definedNames[0]?.getFormulaOrRefString())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 workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
console.log(unitId)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 workbook
const fWorkbook = univerAPI.getActiveWorkbook()
console.log(fWorkbook.getLocale())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 workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const name = fWorkbook.getName()
console.log(name)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 workbook
const fWorkbook = univerAPI.getActiveWorkbook()
console.log(fWorkbook.getNumSheets())getPermission
Get the PermissionInstance.
Deprecated
Use getWorkbookPermission() instead for the new permission API
Signature
getPermission(): FPermissionReturns
- (
FPermission) — - The PermissionInstance.
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
const permission = fWorkbook.getPermission()
console.log(permission)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 themes
const fWorkbook = univerAPI.getActiveWorkbook()
const themes = fWorkbook.getRegisteredRangeThemes()
console.log(themes)getSheetByName
Get a worksheet by sheet name.
Signature
getSheetByName(name: string): FWorksheet | nullParameters
name(string) — The name of the sheet to get.
Returns
- (
FWorksheet | null) — The worksheet with given sheet name
Examples
// The code below gets a worksheet by sheet name
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheetByName('Sheet1')
console.log(sheet)getSheetBySheetId
Get a worksheet by sheet id.
Signature
getSheetBySheetId(sheetId: string): FWorksheet | nullParameters
sheetId(string) — The id of the sheet to get.
Returns
- (
FWorksheet | null) — The worksheet with given sheet id
Examples
// The code below gets a worksheet by sheet id
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheetBySheetId('sheetId')
console.log(sheet)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 workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const sheets = fWorkbook.getSheets()
console.log(sheets)getSnapshot
Deprecated use 'save' instead.
Signature
getSnapshot(): IWorkbookDataReturns
- (
IWorkbookData) — Workbook snapshot data
Tags
@memberof— FWorkbook
Examples
// The code below saves the workbook snapshot data
const activeSpreadsheet = univerAPI.getActiveWorkbook()
const snapshot = activeSpreadsheet.getSnapshot()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 workbook
const fWorkbook = univerAPI.getActiveWorkbook()
const url = fWorkbook.getUrl()
console.log(url)getWorkbook
Get the Workbook instance.
Signature
getWorkbook(): WorkbookReturns
- (
Workbook) — The Workbook instance.
Examples
// The code below gets the Workbook instance
const fWorkbook = univerAPI.getActiveWorkbook()
const workbook = fWorkbook.getWorkbook()
console.log(workbook)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 mode
await permission.setMode('viewer')
// Add a collaborator
await permission.addCollaborator({
userId: 'user123',
name: 'John Doe',
role: 'editor',
})
// Subscribe to permission changes
permission.permission$.subscribe((snapshot) => {
console.log('Permissions changed:', snapshot)
})insertDefinedName
Insert a defined name.
Signature
insertDefinedName(name: string, formulaOrRefString: string): FWorkbookParameters
name(string) — The name of the defined name to insertformulaOrRefString(string) — The formula(=sum(A2:b10)) or reference(A1) string of the defined name to insert
Returns
- (
FWorkbook) — The current FWorkbook instance
Examples
// The code below inserts a defined name
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!$A$1')insertDefinedNameBuilder
Insert a defined name by builder param.
Signature
insertDefinedNameBuilder(param: ISetDefinedNameMutationParam): voidParameters
param(ISetDefinedNameMutationParam) — The param to insert the defined name
Returns
Examples
// The code below inserts a defined name by builder param
const fWorkbook = univerAPI.getActiveWorkbook()
const definedNameBuilder = univerAPI.newDefinedName()
.setRef('Sheet1!$A$1')
.setName('MyDefinedName')
.setComment('This is a comment')
.build()
fWorkbook.insertDefinedNameBuilder(definedNameBuilder)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
sheetName(string) — The name of the new sheetoptions({ index?: number; sheet?: Partial<IWorksheetData> }) — The options for the new sheetoptions.index— The position index where the new sheet is to be insertedoptions.sheet— The data configuration for the new sheet
Returns
- (
FWorksheet) — The new sheet
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
// Create a new sheet with default configuration
const newSheet = fWorkbook.insertSheet()
console.log(newSheet)
// Create a new sheet with custom name and default configuration
const newSheetWithName = fWorkbook.insertSheet('MyNewSheet')
console.log(newSheetWithName)
// Create a new sheet with custom name and custom configuration
const 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)moveActiveSheet
Move the active sheet to the specified index.
Signature
moveActiveSheet(index: number): FWorkbookParameters
index(number) — The index to move the active sheet to
Returns
- (
FWorkbook) — This workbook, for chaining
Examples
// The code below moves the active sheet to the specified index
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.moveActiveSheet(1)moveSheet
Move the sheet to the specified index.
Signature
moveSheet(sheet: FWorksheet, index: number): FWorkbookParameters
sheet(FWorksheet) — The sheet to moveindex(number) — The index to move the sheet to
Returns
- (
FWorkbook) — This workbook, for chaining
Examples
// The code below moves the sheet to the specified index
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getActiveSheet()
fWorkbook.moveSheet(sheet, 1)onBeforeCommandExecute
Callback for command execution.
Signature
onBeforeCommandExecute(callback: CommandListener): IDisposableParameters
callback(CommandListener) — the callback.
Returns
- (
IDisposable) — A function to dispose the listening.
Tags
@callback
Examples
// The code below registers a callback that will be triggered before invoking a command targeting the Univer sheet
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.onBeforeCommandExecute((command) => {
console.log('Before command execute:', command)
})onCommandExecuted
Callback for command execution.
Signature
onCommandExecuted(callback: CommandListener): IDisposableParameters
callback(CommandListener) — the callback.
Returns
- (
IDisposable) — A function to dispose the listening.
Tags
@callback
Examples
// The code below registers a callback that will be triggered when a command is invoked targeting the Univer sheet
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.onCommandExecuted((command) => {
console.log('Command executed:', command)
})onSelectionChange
Callback for selection changes.
Signature
onSelectionChange(callback: (selections: IRange[]) => void): IDisposableParameters
callback((selections: IRange[]) => void) — The callback.
Returns
- (
IDisposable) — A function to dispose the listening
Tags
@callback
Examples
// The code below registers a callback that will be triggered when the selection changes
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.onSelectionChange((selections) => {
console.log('Selection changed:', selections)
})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 action
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.redo()registerRangeTheme
Register a custom range theme style.
Signature
registerRangeTheme(rangeThemeStyle: RangeThemeStyle): voidParameters
rangeThemeStyle(RangeThemeStyle) — The range theme style to register
Returns
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
secondRowStyle: {
bg: {
rgb: 'rgb(214,231,241)',
},
},
})
fWorkbook.registerRangeTheme(rangeThemeStyle)removeStyles
Remove styles from the workbook styles.
Signature
removeStyles(styleKeys: string[]): voidParameters
styleKeys(string[]) — Style keys to remove
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
// Add styles to the workbook styles
const 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 styles
const 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 seconds
setTimeout(() => {
fWorkbook.removeStyles(['custom-style-1'])
fWorksheet.refreshCanvas()
}, 2000)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 data
const fWorkbook = univerAPI.getActiveWorkbook()
const snapshot = fWorkbook.save()
console.log(snapshot)setActiveRange
Sets the selection region for active sheet.
Signature
setActiveRange(range: FRange): FWorkbookParameters
range(FRange) — The range to set as the active selection.
Returns
- (
FWorkbook) — FWorkbook instance
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
const range = fWorkbook.getActiveSheet().getRange('A10:B10')
fWorkbook.setActiveRange(range)setActiveSheet
Sets the given worksheet to be the active worksheet in the workbook.
Signature
setActiveSheet(sheet: FWorksheet | string): FWorksheetParameters
sheet(FWorksheet | string) — The instance or id of the worksheet to set as active.
Returns
- (
FWorksheet) — The active worksheet
Examples
// The code below sets the given worksheet to be the active worksheet
const fWorkbook = univerAPI.getActiveWorkbook()
const sheet = fWorkbook.getSheets()[1]
fWorkbook.setActiveSheet(sheet)setCustomMetadata
Set custom metadata of workbook
Signature
setCustomMetadata(custom: CustomData | undefined): FWorkbookParameters
custom(CustomData | undefined) — custom metadata
Returns
- (
FWorkbook) — FWorkbook
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.setCustomMetadata({ key: 'value' })setEditable
Used to modify the editing permissions of the workbook. When the value is false, editing is not allowed.
Signature
setEditable(value: boolean): FWorkbookParameters
value(boolean) — editable value want to set
Returns
- (
FWorkbook) — FWorkbook instance
Examples
// The code below sets the editing permissions of the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.setEditable(false)setLocale
Deprecated
use setSpreadsheetLocale instead.
Signature
setLocale(locale: LocaleType): voidParameters
locale(LocaleType) — - The locale to set
setName
Set the name of the workbook.
Signature
setName(name: string): thisParameters
name(string) — The new name of the workbook.
Examples
// The code below sets the name of the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.setName('MyWorkbook')setSpreadsheetLocale
Set the locale of the workbook.
Signature
setSpreadsheetLocale(locale: LocaleType): FWorkbookParameters
locale(LocaleType) — The locale to set
Returns
- (
FWorkbook) — This workbook, for chaining
Examples
// The code below sets the locale of the workbook
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.setSpreadsheetLocale(univerAPI.Enum.LocaleType.EN_US)
console.log(fWorkbook.getLocale())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 action
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.undo()unregisterRangeTheme
Unregister a custom range theme style.
Signature
unregisterRangeTheme(themeName: string): voidParameters
themeName(string) — The name of the theme to unregister
Returns
Examples
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.unregisterRangeTheme('MyTheme')updateDefinedNameBuilder
Update the defined name with the given name.
Signature
updateDefinedNameBuilder(param: ISetDefinedNameMutationParam): voidParameters
param(ISetDefinedNameMutationParam) — The param to insert the defined name
Returns
Examples
// The code below updates the defined name with the given name
const fWorkbook = univerAPI.getActiveWorkbook()
const definedName = fWorkbook.getDefinedName('MyDefinedName')
console.log(definedName?.getFormulaOrRefString())
// Update the defined name
if (definedName) {
const newDefinedNameParam = definedName.toBuilder()
.setName('NewDefinedName')
.setRef('Sheet1!$A$2')
.build()
fWorkbook.updateDefinedNameBuilder(newDefinedNameParam)
}