FWorkbook

GitHubEdit on GitHub
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>): void

Parameters

  • 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> }): FWorksheet

Parameters

  • name (string) — Name of the new sheet
  • rows (number) — How many rows would the new sheet have
  • columns (number) — How many columns would the new sheet have
  • options ({ index?: number; sheet?: Partial<IWorksheetData> }) — The options for the new sheet
  • options.index — The position index where the new sheet is to be inserted
  • options.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'>): RangeThemeStyle

Parameters

  • themeName (string) — - The name of the theme to register
  • themeStyleJson (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(): boolean

Returns

  • (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): boolean

Parameters

  • 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): boolean

Parameters

  • 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(): void

duplicateActiveSheet

Duplicates the active sheet.

Signature

duplicateActiveSheet(): FWorksheet

Returns

  • (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): FWorksheet

Parameters

  • 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 | null

Returns

  • (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 | null

Returns

  • (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(): FWorksheet

Returns

  • (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 | undefined

Returns

  • (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 | null

Parameters

  • 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(): string

Returns

  • (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(): LocaleType

Returns

  • (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(): string

Returns

  • (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(): number

Returns

  • (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(): FPermission

Returns

  • (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 | null

Parameters

  • 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 | null

Parameters

  • 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(): IWorkbookData

Returns

  • (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(): string

Returns

  • (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(): Workbook

Returns

  • (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(): FWorkbookPermission

Returns

  • (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): FWorkbook

Parameters

  • name (string) — The name of the defined name to insert
  • formulaOrRefString (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): void

Parameters

  • 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> }): FWorksheet

Parameters

  • sheetName (string) — The name of the new sheet
  • options ({ index?: number; sheet?: Partial<IWorksheetData> }) — The options for the new sheet
  • options.index — The position index where the new sheet is to be inserted
  • options.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): FWorkbook

Parameters

  • 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): FWorkbook

Parameters

  • sheet (FWorksheet) — The sheet to move
  • index (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): IDisposable

Parameters

  • 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): IDisposable

Parameters

  • 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): IDisposable

Parameters

  • 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(): FWorkbook

Returns

  • (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): void

Parameters

  • 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[]): void

Parameters

  • 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(): IWorkbookData

Returns

  • (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): FWorkbook

Parameters

  • 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): FWorksheet

Parameters

  • 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): FWorkbook

Parameters

  • 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): FWorkbook

Parameters

  • 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): void

Parameters

  • locale (LocaleType) — - The locale to set

setName

Set the name of the workbook.

Signature

setName(name: string): this

Parameters

  • 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): FWorkbook

Parameters

  • 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(): FWorkbook

Returns

  • (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): void

Parameters

  • 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): void

Parameters

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