API 参考

Workbook

本 API 页面目前提供英文正文。代码签名与标识符不随界面语言变化。
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 univerAPI instead.

Overview

@univerjs/sheets

MethodDescription
addStylesAdd styles to the workbook styles
createCreate a new worksheet and returns a handle to it
createRangeThemeStyleCreate a range theme style
deleteActiveSheetDeletes the currently active sheet
deleteDefinedNameDelete the defined name with the given name
deleteSheetDeletes the specified worksheet
dispose-
duplicateActiveSheetDuplicates the active sheet
duplicateSheetDuplicates the given worksheet
getActiveCellReturns the active cell in this spreadsheet
getActiveRangeReturns the selected range in the active sheet, or null if there is no active range
getActiveSheetGet the active sheet of the workbook
getCustomMetadataGet custom metadata of workbook
getDefinedNameGet the defined name by name
getDefinedNamesGet all the defined names in the workbook
getIdGet the id of the workbook
getLocaleGet the locale of the workbook
getNameGet the name of the workbook
getNumSheetsGet the number of sheets in the workbook
getRegisteredRangeThemesGets the registered range themes
getSheetByNameGet a worksheet by sheet name
getSheetBySheetIdGet a worksheet by sheet id
getSheetsGets all the worksheets in this workbook
getSnapshot-
getUrlGet the URL of the workbook
getWorkbookGet the Workbook instance
getWorkbookPermissionGet the WorkbookPermission instance for managing workbook-level permissions
id-
insertDefinedNameInsert a defined name
insertDefinedNameBuilderInsert a defined name by builder param
insertSheetInserts a new worksheet into the workbook
moveActiveSheetMove the active sheet to the specified index
moveSheetMove the sheet to the specified index
newDefinedNameBuilderCreate a new defined name builder
onBeforeCommandExecuteCallback for command execution
onCommandExecutedCallback for command execution
onSelectionChangeCallback for selection changes
redoRedo the last undone action
registerRangeThemeRegister a custom range theme style
removeStylesRemove styles from the workbook styles
saveSave workbook snapshot data, including conditional formatting, data validation, and other plugin data
setActiveRangeSets the selection region for active sheet
setActiveSheetSets the given worksheet to be the active worksheet in the workbook
setCustomMetadataSet custom metadata of workbook
setEditableUsed to modify the editing permissions of the workbook
setLocale-
setNameSet the name of the workbook
setSpreadsheetLocaleSet the locale of the workbook
undoUndo the last action
unregisterRangeThemeUnregister a custom range theme style
updateDefinedNameBuilderUpdate the defined name with the given name

@univerjs/sheets-data-validation

@univerjs/sheets-formula

MethodDescription
getAllFormulaErrorGet all formula errors in the workbook
MethodDescription
getUrlOfDefineNameCreate a hyperlink url for the defined name
parseSheetHyperlinkParse the hyperlink string to get the hyperlink info
MethodDescription
navigateToSheetHyperlinkNavigate to the specified hyperlink

@univerjs/sheets-numfmt

MethodDescription
setNumfmtLocalSet the locale for number format display

@univerjs/sheets-table

@univerjs/sheets-thread-comment

MethodDescription
clearComments-
getComments-

@univerjs/sheets-ui

@univerjs-pro/sheets-pivot

@univerjs-pro/sheets-print

@univerjs-pro/range-preprocess

MethodDescription
getPreprocessRangesGet all preprocess range information

APIs

Sheet Operations

create

Create a new worksheet and returns a handle to it.

Signature

TypeScript
create(name: string, rows: number, columns: number, options?: { index?: number; sheet?: Partial<IWorksheetData> }): FWorksheet

Parameters

  • name stringNo description
  • rows numberNo description
  • columns numberNo description
  • options { index?: number; sheet?: Partial<IWorksheetData>; } (optional)No description

Returns

  • FWorksheet — The new created sheet

Examples

TypeScript
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);
Source: @univerjs/sheets

createRangeThemeStyle

Create a range theme style.

Signature

TypeScript
createRangeThemeStyle(themeName: string, themeStyleJson?: Omit<IRangeThemeStyleJSON, 'name'>): RangeThemeStyle

Parameters

  • themeName stringNo description
  • themeStyleJson Omit<IRangeThemeStyleJSON, "name"> (optional)No description

Returns

  • RangeThemeStyle — - The created range theme style

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {  secondRowStyle: {    bg: {      rgb: 'rgb(214,231,241)',    },  },});console.log(rangeThemeStyle);
Source: @univerjs/sheets

deleteActiveSheet

Deletes the currently active sheet.

Signature

TypeScript
deleteActiveSheet(): boolean

Returns

  • boolean — true if the sheet was deleted, false otherwise

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.deleteActiveSheet();
Source: @univerjs/sheets

deleteDefinedName

Delete the defined name with the given name.

Signature

TypeScript
deleteDefinedName(name: string): boolean

Parameters

  • name stringNo description

Returns

  • boolean — true if the defined name was deleted, false otherwise

Examples

TypeScript
// The code below deletes the defined name with the given nameconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.deleteDefinedName('MyDefinedName');
Source: @univerjs/sheets

deleteSheet

Deletes the specified worksheet.

Signature

TypeScript
deleteSheet(sheet: FWorksheet | string): boolean

Parameters

  • sheet string | FWorksheetNo description

Returns

  • boolean — True if the worksheet was deleted, false otherwise.

Examples

TypeScript
// 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());
Source: @univerjs/sheets

getActiveSheet

Get the active sheet of the workbook.

Signature

TypeScript
getActiveSheet(): FWorksheet

Returns

  • FWorksheet — The active sheet of the workbook

Examples

TypeScript
// The code below gets the active sheet of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const fWorksheet = fWorkbook.getActiveSheet();console.log(fWorksheet);
Source: @univerjs/sheets

getSheetByName

Get a worksheet by sheet name.

Signature

TypeScript
getSheetByName(name: string): FWorksheet | null

Parameters

  • name stringNo description

Returns

  • FWorksheet — The worksheet with given sheet name

Examples

TypeScript
// The code below gets a worksheet by sheet nameconst fWorkbook = univerAPI.getActiveWorkbook();const sheet = fWorkbook.getSheetByName('Sheet1');console.log(sheet);
Source: @univerjs/sheets

getSheetBySheetId

Get a worksheet by sheet id.

Signature

TypeScript
getSheetBySheetId(sheetId: string): FWorksheet | null

Parameters

  • sheetId stringNo description

Returns

  • FWorksheet — The worksheet with given sheet id

Examples

TypeScript
// The code below gets a worksheet by sheet idconst fWorkbook = univerAPI.getActiveWorkbook();const sheet = fWorkbook.getSheetBySheetId('sheetId');console.log(sheet);
Source: @univerjs/sheets

getSheets

Gets all the worksheets in this workbook

Signature

TypeScript
getSheets(): FWorksheet[]

Returns

  • FWorksheet[] — An array of all the worksheets in the workbook

Examples

TypeScript
// The code below gets all the worksheets in the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const sheets = fWorkbook.getSheets();console.log(sheets);
Source: @univerjs/sheets

insertDefinedName

Insert a defined name.

Signature

TypeScript
insertDefinedName(name: string, formulaOrRefString: string): FWorkbook

Parameters

  • name stringNo description
  • formulaOrRefString stringNo description

Returns

  • FWorkbook — The current FWorkbook instance

Examples

TypeScript
// The code below inserts a defined nameconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!$A$1');
Source: @univerjs/sheets

insertDefinedNameBuilder

Insert a defined name by builder param.

Signature

TypeScript
insertDefinedNameBuilder(param: ISetDefinedNameMutationParam): void

Parameters

  • param ISetDefinedNameMutationParamNo description

Examples

TypeScript
// 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);
Source: @univerjs/sheets

newDefinedNameBuilder

Create a new defined name builder.

Signature

TypeScript
newDefinedNameBuilder(): FDefinedNameBuilder

Returns

  • FDefinedNameBuilder — The defined name builder.

Examples

TypeScript
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);
Source: @univerjs/sheets

insertSheet

Inserts a new worksheet into the workbook. Using a default sheet name. The new sheet becomes the active sheet

Signature

TypeScript
insertSheet(sheetName?: string, options?: { index?: number; sheet?: Partial<IWorksheetData> }): FWorksheet

Parameters

  • sheetName string (optional)No description
  • options { index?: number; sheet?: Partial<IWorksheetData>; } (optional)No description

Returns

  • FWorksheet — The new sheet

Examples

TypeScript
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);
Source: @univerjs/sheets

Defined Names

getDefinedName

Get the defined name by name.

Signature

TypeScript
getDefinedName(name: string): FDefinedName | null

Parameters

  • name stringNo description

Returns

  • FDefinedName — The defined name with the given name

Examples

TypeScript
// The code below gets the defined name by nameconst fWorkbook = univerAPI.getActiveWorkbook();const definedName = fWorkbook.getDefinedName('MyDefinedName');console.log(definedName?.getFormulaOrRefString());
Source: @univerjs/sheets

getDefinedNames

Get all the defined names in the workbook.

Signature

TypeScript
getDefinedNames(): FDefinedName[]

Returns

  • FDefinedName[] — All the defined names in the workbook

Examples

TypeScript
// The code below gets all the defined names in the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const definedNames = fWorkbook.getDefinedNames();console.log(definedNames, definedNames[0]?.getFormulaOrRefString());
Source: @univerjs/sheets

getName

Get the name of the workbook.

Signature

TypeScript
getName(): string

Returns

  • string — The name of the workbook.

Examples

TypeScript
// The code below gets the name of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const name = fWorkbook.getName();console.log(name);
Source: @univerjs/sheets

getTableInfoByName

Signature

TypeScript
getTableInfoByName(tableName: string): ITableInfoWithUnitId | undefined

Parameters

  • tableName stringNo description

Returns

  • any — See signature above.
Source: @univerjs/sheets-table

setName

Set the name of the workbook.

Signature

TypeScript
setName(name: string): this

Parameters

  • name stringNo description

Returns

  • this — See signature above.

Examples

TypeScript
// The code below sets the name of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setName('MyWorkbook');
Source: @univerjs/sheets

updateDefinedNameBuilder

Update the defined name with the given name.

Signature

TypeScript
updateDefinedNameBuilder(param: ISetDefinedNameMutationParam): void

Parameters

  • param ISetDefinedNameMutationParamNo description

Examples

TypeScript
// 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);}
Source: @univerjs/sheets

Range Themes

getRegisteredRangeThemes

Gets the registered range themes.

Signature

TypeScript
getRegisteredRangeThemes(): string[]

Returns

  • string[] — The name list of registered range themes.

Examples

TypeScript
// The code below gets the registered range themesconst fWorkbook = univerAPI.getActiveWorkbook();const themes = fWorkbook.getRegisteredRangeThemes();console.log(themes);
Source: @univerjs/sheets

registerRangeTheme

Register a custom range theme style.

Signature

TypeScript
registerRangeTheme(rangeThemeStyle: RangeThemeStyle): void

Parameters

  • rangeThemeStyle RangeThemeStyleNo description

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {  secondRowStyle: {    bg: {      rgb: 'rgb(214,231,241)',    },  },});fWorkbook.registerRangeTheme(rangeThemeStyle);
Source: @univerjs/sheets

unregisterRangeTheme

Unregister a custom range theme style.

Signature

TypeScript
unregisterRangeTheme(themeName: string): void

Parameters

  • themeName stringNo description

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.unregisterRangeTheme('MyTheme');
Source: @univerjs/sheets

Range Preprocess

getPreprocessRanges

Get all preprocess range information.

Signature

TypeScript
getPreprocessRanges(responseDataMode?: string): Record<string, ITableJson[]>

Parameters

  • responseDataMode string (optional) — The response data mode.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const preprocessRanges = fWorkbook.getPreprocessRanges()
Source: @univerjs-pro/range-preprocess

Collaboration

getSnapshot

Deprecated — use 'save' instead.

Signature

TypeScript
getSnapshot(): IWorkbookData

Returns

  • IWorkbookData — Workbook snapshot data

Tags

  • @memberof — FWorkbook

Examples

TypeScript
// The code below saves the workbook snapshot dataconst activeSpreadsheet = univerAPI.getActiveWorkbook();const snapshot = activeSpreadsheet.getSnapshot();
Source: @univerjs/sheets

Pivot Tables

addPivotTable

Signature

TypeScript
async addPivotTable(sourceInfo: IUnitRangeName & { subUnitId: string }, positionType: PositionType, anchorCellInfo: IPivotCellPositionInfo): Promise<FPivotTable | undefined>

Parameters

  • sourceInfo anyNo description
  • positionType PositionTypeNo description
  • anchorCellInfo IPivotCellPositionInfoNo description

Returns

  • Promise<FPivotTable> — See signature above.
Source: @univerjs-pro/sheets-pivot

getPivotTableByCell

Signature

TypeScript
getPivotTableByCell(unitId: string, subUnitId: string, row: number, col: number): FPivotTable | undefined

Parameters

  • unitId stringNo description
  • subUnitId stringNo description
  • row numberNo description
  • col numberNo description

Returns

  • FPivotTable — See signature above.
Source: @univerjs-pro/sheets-pivot

getPivotTableById

Signature

TypeScript
getPivotTableById(pivotTableId: string): FPivotTable | undefined

Parameters

  • pivotTableId stringNo description

Returns

  • FPivotTable — See signature above.
Source: @univerjs-pro/sheets-pivot

Miscellaneous

abortEditingAsync

Signature

TypeScript
abortEditingAsync(): Promise<boolean>

Returns

  • Promise<boolean> — See signature above.
Source: @univerjs/sheets-ui

addStyles

Add styles to the workbook styles.

Signature

TypeScript
addStyles(styles: Record<string, IStyleData>): void

Parameters

  • styles Record<string, IStyleData>No description

Examples

TypeScript
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' }],]);
Source: @univerjs/sheets

clearComments

Signature

TypeScript
clearComments(): Promise<boolean>

Returns

  • Promise<boolean> — See signature above.
Source: @univerjs/sheets-thread-comment

customizeColumnHeader

Signature

TypeScript
customizeColumnHeader(cfg: IColumnsHeaderCfgParam): void

Parameters

  • cfg IColumnsHeaderCfgParamNo description
Source: @univerjs/sheets-ui

customizeRowHeader

Signature

TypeScript
customizeRowHeader(cfg: IRowsHeaderCfgParam): void

Parameters

  • cfg IRowsHeaderCfgParamNo description
Source: @univerjs/sheets-ui

disableSelection

Signature

TypeScript
disableSelection(): FWorkbook

Returns

  • FWorkbook — See signature above.
Source: @univerjs/sheets-ui

dispose

Signature

TypeScript
dispose(): void
Source: @univerjs/sheets

duplicateActiveSheet

Duplicates the active sheet.

Signature

TypeScript
duplicateActiveSheet(): FWorksheet

Returns

  • FWorksheet — The duplicated worksheet

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const duplicatedSheet = fWorkbook.duplicateActiveSheet();console.log(duplicatedSheet);
Source: @univerjs/sheets

duplicateSheet

Duplicates the given worksheet.

Signature

TypeScript
duplicateSheet(sheet: FWorksheet): FWorksheet

Parameters

  • sheet FWorksheetNo description

Returns

  • FWorksheet — The duplicated worksheet

Examples

TypeScript
// The code below duplicates the given worksheetconst fWorkbook = univerAPI.getActiveWorkbook();const activeSheet = fWorkbook.getActiveSheet();const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet);console.log(duplicatedSheet);
Source: @univerjs/sheets

enableSelection

Signature

TypeScript
enableSelection(): FWorkbook

Returns

  • FWorkbook — See signature above.
Source: @univerjs/sheets-ui

endEditing

Signature

TypeScript
async endEditing(save?: boolean): Promise<boolean>

Parameters

  • save boolean (optional)No description

Returns

  • Promise<boolean> — See signature above.
Source: @univerjs/sheets-ui

endEditingAsync

Signature

TypeScript
endEditingAsync(save = true): Promise<boolean>

Parameters

  • save boolean (optional)No description

Returns

  • Promise<boolean> — See signature above.
Source: @univerjs/sheets-ui

getActiveCell

Returns the active cell in this spreadsheet.

Signature

TypeScript
getActiveCell(): FRange | null

Returns

  • FRange — The active cell

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();console.log(fWorkbook.getActiveCell().getA1Notation());
Source: @univerjs/sheets

getActiveRange

Returns the selected range in the active sheet, or null if there is no active range.

Signature

TypeScript
getActiveRange(): FRange | null

Returns

  • FRange — The active range

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const activeRange = fWorkbook.getActiveRange();console.log(activeRange);
Source: @univerjs/sheets

getAllDataValidationErrorAsync

Signature

TypeScript
async getAllDataValidationErrorAsync(): Promise<IDataValidationError[]>

Returns

  • Promise<IDataValidationError[]> — See signature above.
Source: @univerjs/sheets-data-validation

getAllFormulaError

Get all formula errors in the workbook.

Signature

TypeScript
getAllFormulaError(): ISheetFormulaError[]

Returns

  • ISheetFormulaError[] — Array of formula errors.
Source: @univerjs/sheets-formula

getComments

Signature

TypeScript
getComments(): FThreadComment[]

Returns

  • FThreadComment[] — See signature above.
Source: @univerjs/sheets-thread-comment

getCustomMetadata

Get custom metadata of workbook

Signature

TypeScript
getCustomMetadata(): CustomData | undefined

Returns

  • CustomData — custom metadata

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const custom = fWorkbook.getCustomMetadata();console.log(custom);
Source: @univerjs/sheets

getId

Get the id of the workbook.

Signature

TypeScript
getId(): string

Returns

  • string — The id of the workbook.

Examples

TypeScript
// The code below gets the id of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const unitId = fWorkbook.getId();console.log(unitId);
Source: @univerjs/sheets

getLocale

Get the locale of the workbook.

Signature

TypeScript
getLocale(): LocaleType

Returns

  • LocaleType — The locale of the workbook

Examples

TypeScript
// The code below gets the locale of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();console.log(fWorkbook.getLocale());
Source: @univerjs/sheets

getNumSheets

Get the number of sheets in the workbook.

Signature

TypeScript
getNumSheets(): number

Returns

  • number — The number of sheets in the workbook

Examples

TypeScript
// The code below gets the number of sheets in the workbookconst fWorkbook = univerAPI.getActiveWorkbook();console.log(fWorkbook.getNumSheets());
Source: @univerjs/sheets

getScrollStateBySheetId

Get scroll state of specified sheet.

Signature

TypeScript
getScrollStateBySheetId(sheetId: string): Nullable<IScrollState>

Parameters

  • sheetId stringNo description

Returns

  • any — scroll state

Examples

TypeScript
 tsuniverAPI.getActiveWorkbook().getScrollStateBySheetId($sheetId)
Source: @univerjs/sheets-ui

getUrl

Get the URL of the workbook.

Signature

TypeScript
getUrl(): string

Returns

  • string — The URL of the workbook

Examples

TypeScript
// The code below gets the URL of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();const url = fWorkbook.getUrl();console.log(url);
Source: @univerjs/sheets

getValidatorStatus

Signature

TypeScript
getValidatorStatus(): Promise<Record<string, ObjectMatrix<Nullable<DataValidationStatus>>>>

Returns

  • Promise<Record<string, ObjectMatrix<Nullable<DataValidationStatus>>>> — See signature above.
Source: @univerjs/sheets-data-validation

getWorkbook

Get the Workbook instance.

Signature

TypeScript
getWorkbook(): Workbook

Returns

  • Workbook — The Workbook instance.

Examples

TypeScript
// The code below gets the Workbook instanceconst fWorkbook = univerAPI.getActiveWorkbook();const workbook = fWorkbook.getWorkbook();console.log(workbook);
Source: @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

TypeScript
getWorkbookPermission(): FWorkbookPermission

Returns

  • FWorkbookPermission — - The WorkbookPermission instance.

Examples

TypeScript
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);});
Source: @univerjs/sheets

id

Signature

TypeScript
id: string

Returns

  • string — See signature above.
Source: @univerjs/sheets

isCellEditing

Signature

TypeScript
isCellEditing(): boolean

Returns

  • boolean — See signature above.
Source: @univerjs/sheets-ui

moveActiveSheet

Move the active sheet to the specified index.

Signature

TypeScript
moveActiveSheet(index: number): FWorkbook

Parameters

  • index numberNo description

Returns

  • FWorkbook — This workbook, for chaining

Examples

TypeScript
// The code below moves the active sheet to the specified indexconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.moveActiveSheet(1);
Source: @univerjs/sheets

moveSheet

Move the sheet to the specified index.

Signature

TypeScript
moveSheet(sheet: FWorksheet, index: number): FWorkbook

Parameters

  • sheet FWorksheetNo description
  • index numberNo description

Returns

  • FWorkbook — This workbook, for chaining

Examples

TypeScript
// The code below moves the sheet to the specified indexconst fWorkbook = univerAPI.getActiveWorkbook();const sheet = fWorkbook.getActiveSheet();fWorkbook.moveSheet(sheet, 1);
Source: @univerjs/sheets

Navigate to the specified hyperlink within the workbook.

Signature

TypeScript
navigateToSheetHyperlink(hyperlink: string): void

Parameters

  • hyperlink string — The hyperlink string to navigate to.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.navigateToSheetHyperlink('#gid=sheet1&range=A1');
Source: @univerjs/sheets-hyper-link-ui

onBeforeAddDataValidation

Signature

TypeScript
onBeforeAddDataValidation(callback: (params: IAddSheetDataValidationCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable

Parameters

  • callback (params: IAddSheetDataValidationCommandParams, options: IExecutionOptions) => false | voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-data-validation

onBeforeCommandExecute

Callback for command execution.

Signature

TypeScript
onBeforeCommandExecute(callback: CommandListener): IDisposable

Parameters

  • callback CommandListenerNo description

Returns

  • IDisposable — See signature above.

Tags

  • @callback — onBeforeCommandExecuteCallback
Source: @univerjs/sheets

onBeforeDeleteAllDataValidation

Signature

TypeScript
onBeforeDeleteAllDataValidation(callback: (params: IRemoveSheetAllDataValidationCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable

Parameters

  • callback (params: IRemoveSheetAllDataValidationCommandParams, options: IExecutionOptions) => false | voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-data-validation

onBeforeDeleteDataValidation

Signature

TypeScript
onBeforeDeleteDataValidation(callback: (params: IRemoveSheetDataValidationCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable

Parameters

  • callback (params: IRemoveSheetDataValidationCommandParams, options: IExecutionOptions) => false | voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-data-validation

onBeforeUpdateDataValidationCriteria

Signature

TypeScript
onBeforeUpdateDataValidationCriteria(callback: (params: IUpdateSheetDataValidationSettingCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable

Parameters

  • callback (params: IUpdateSheetDataValidationSettingCommandParams, options: IExecutionOptions) => false | voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-data-validation

onBeforeUpdateDataValidationOptions

Signature

TypeScript
onBeforeUpdateDataValidationOptions(callback: (params: IUpdateSheetDataValidationOptionsCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable

Parameters

  • callback (params: IUpdateSheetDataValidationOptionsCommandParams, options: IExecutionOptions) => false | voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-data-validation

onBeforeUpdateDataValidationRange

Signature

TypeScript
onBeforeUpdateDataValidationRange(callback: (params: IUpdateSheetDataValidationRangeCommandParams, options: IExecutionOptions | undefined) => void | false): IDisposable

Parameters

  • callback (params: IUpdateSheetDataValidationRangeCommandParams, options: IExecutionOptions) => false | voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-data-validation

onCellClick

Signature

TypeScript
onCellClick(callback: (cell: IHoverRichTextInfo) => void): IDisposable

Parameters

  • callback (cell: IHoverRichTextInfo) => voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-ui

onCellHover

Signature

TypeScript
onCellHover(callback: (cell: IHoverRichTextPosition) => void): IDisposable

Parameters

  • callback (cell: IHoverRichTextPosition) => voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-ui

onCellPointerDown

Signature

TypeScript
onCellPointerDown(callback: (cell: ICellPosWithEvent) => void): IDisposable

Parameters

  • callback (cell: ICellPosWithEvent) => voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-ui

onCellPointerMove

Signature

TypeScript
onCellPointerMove(callback: (cell: ICellPosWithEvent, event: IPointerEvent | IMouseEvent) => void): IDisposable

Parameters

  • callback (cell: ICellPosWithEvent, event: IPointerEvent | IMouseEvent) => voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-ui

onCellPointerUp

Signature

TypeScript
onCellPointerUp(callback: (cell: ICellPosWithEvent) => void): IDisposable

Parameters

  • callback (cell: ICellPosWithEvent) => voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-ui

onCommandExecuted

Callback for command execution.

Signature

TypeScript
onCommandExecuted(callback: CommandListener): IDisposable

Parameters

  • callback CommandListenerNo description

Returns

  • IDisposable — See signature above.

Tags

  • @callback — onCommandExecutedCallback
Source: @univerjs/sheets

onDragOver

Signature

TypeScript
onDragOver(callback: (cell: IDragCellPosition) => void): IDisposable

Parameters

  • callback (cell: IDragCellPosition) => voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-ui

onDrop

Signature

TypeScript
onDrop(callback: (cell: IDragCellPosition) => void): IDisposable

Parameters

  • callback (cell: IDragCellPosition) => voidNo description

Returns

  • IDisposable — See signature above.
Source: @univerjs/sheets-ui

onSelectionChange

Callback for selection changes.

Signature

TypeScript
onSelectionChange(callback: (selections: IRange[]) => void): IDisposable

Parameters

  • callback (selections: IRange[]) => voidNo description

Returns

  • IDisposable — See signature above.

Tags

  • @callback — onSelectionChangeCallback
Source: @univerjs/sheets

Parse the hyperlink string to get the hyperlink info.

Signature

TypeScript
parseSheetHyperlink(hyperlink: string): ISheetHyperLinkInfo

Parameters

  • hyperlink string — The hyperlink string to parse.

Returns

  • ISheetHyperLinkInfo — The parsed hyperlink info, including type, name, URL, and search parameters.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const info = fWorkbook.parseSheetHyperlink('#gid=sheet1&range=A1');console.log(info);
Source: @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

TypeScript
getUrlOfDefineName(name: string): string

Parameters

  • name string — The name of the defined name.

Returns

  • string — The hyperlink url of the defined name.

Examples

TypeScript
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()}`);
Source: @univerjs/sheets-hyper-link

redo

Redo the last undone action.

Signature

TypeScript
redo(): FWorkbook

Returns

  • FWorkbook — A promise that resolves to true if the redo was successful, false otherwise.

Examples

TypeScript
// The code below redoes the last undone actionconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.redo();
Source: @univerjs/sheets

removeStyles

Remove styles from the workbook styles.

Signature

TypeScript
removeStyles(styleKeys: string[]): void

Parameters

  • styleKeys string[]No description

Examples

TypeScript
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);
Source: @univerjs/sheets

save

Save workbook snapshot data, including conditional formatting, data validation, and other plugin data.

Signature

TypeScript
save(): IWorkbookData

Returns

  • IWorkbookData — Workbook snapshot data

Examples

TypeScript
// The code below saves the workbook snapshot dataconst fWorkbook = univerAPI.getActiveWorkbook();const snapshot = fWorkbook.save();console.log(snapshot);
Source: @univerjs/sheets

saveScreenshotToClipboard

Signature

TypeScript
async saveScreenshotToClipboard(): Promise<boolean>

Returns

  • Promise<boolean> — See signature above.
Source: @univerjs-pro/sheets-print

setActiveRange

Sets the selection region for active sheet.

Signature

TypeScript
setActiveRange(range: FRange): FWorkbook

Parameters

  • range FRangeNo description

Returns

  • FWorkbook — FWorkbook instance

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();const range = fWorkbook.getActiveSheet().getRange('A10:B10');fWorkbook.setActiveRange(range);
Source: @univerjs/sheets

setActiveSheet

Sets the given worksheet to be the active worksheet in the workbook.

Signature

TypeScript
setActiveSheet(sheet: FWorksheet | string): FWorksheet

Parameters

  • sheet string | FWorksheetNo description

Returns

  • FWorksheet — The active worksheet

Examples

TypeScript
// The code below sets the given worksheet to be the active worksheetconst fWorkbook = univerAPI.getActiveWorkbook();const sheet = fWorkbook.getSheets()[1];fWorkbook.setActiveSheet(sheet);
Source: @univerjs/sheets

setCustomMetadata

Set custom metadata of workbook

Signature

TypeScript
setCustomMetadata(custom: CustomData | undefined): FWorkbook

Parameters

  • custom CustomData — metadata

Returns

  • FWorkbook — FWorkbook

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setCustomMetadata({ key: 'value' });
Source: @univerjs/sheets

setLocale

Deprecated — use setSpreadsheetLocale instead.

Signature

TypeScript
setLocale(locale: LocaleType): void

Parameters

  • locale LocaleTypeNo description
Source: @univerjs/sheets

setNumfmtLocal

Set the locale for number format display. This affects how numbers, dates, and currencies are formatted in the workbook.

Signature

TypeScript
setNumfmtLocal(locale: INumfmtLocaleTag): FWorkbook

Parameters

  • locale INumfmtLocaleTag — The locale tag to use (e.g. 'en_US', 'zh_CN', 'de_DE').

Returns

  • FWorkbook — The current workbook instance, for chaining.

Examples

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setNumfmtLocal('de_DE');
Source: @univerjs/sheets-numfmt

setPermissionDialogVisible

Signature

TypeScript
setPermissionDialogVisible(visible: boolean): void

Parameters

  • visible booleanNo description
Source: @univerjs/sheets-ui

setSpreadsheetLocale

Set the locale of the workbook.

Signature

TypeScript
setSpreadsheetLocale(locale: LocaleType): FWorkbook

Parameters

  • locale LocaleTypeNo description

Returns

  • FWorkbook — This workbook, for chaining

Examples

TypeScript
// The code below sets the locale of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setSpreadsheetLocale(univerAPI.Enum.LocaleType.EN_US);console.log(fWorkbook.getLocale());
Source: @univerjs/sheets

showSelection

Signature

TypeScript
showSelection(): FWorkbook

Returns

  • FWorkbook — See signature above.
Source: @univerjs/sheets-ui

startEditing

Signature

TypeScript
startEditing(): boolean

Returns

  • boolean — See signature above.
Source: @univerjs/sheets-ui

transparentSelection

Signature

TypeScript
transparentSelection(): FWorkbook

Returns

  • FWorkbook — See signature above.
Source: @univerjs/sheets-ui

undo

Undo the last action.

Signature

TypeScript
undo(): FWorkbook

Returns

  • FWorkbook — A promise that resolves to true if the undo was successful, false otherwise.

Examples

TypeScript
// The code below undoes the last actionconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.undo();
Source: @univerjs/sheets

Print

closePrintDialog

Signature

TypeScript
closePrintDialog(): void
Source: @univerjs-pro/sheets-print

openPrintDialog

Signature

TypeScript
openPrintDialog(): void
Source: @univerjs-pro/sheets-print

Signature

TypeScript
print(): void
Source: @univerjs-pro/sheets-print

updatePrintConfig

Signature

TypeScript
updatePrintConfig(config: ISheetPrintLayoutConfig): FWorkbook

Parameters

  • config ISheetPrintLayoutConfigNo description

Returns

  • FWorkbook — See signature above.
Source: @univerjs-pro/sheets-print

updatePrintRenderConfig

Signature

TypeScript
updatePrintRenderConfig(config: ISheetPrintRenderConfig): FWorkbook

Parameters

  • config ISheetPrintRenderConfigNo description

Returns

  • FWorkbook — See signature above.
Source: @univerjs-pro/sheets-print

Tables

addTable

Signature

TypeScript
async addTable(subUnitId: string, tableName: string, rangeInfo: ITableRange, tableId?: string, options?: ITableOptions): Promise<string | undefined>

Parameters

  • subUnitId stringNo description
  • tableName stringNo description
  • rangeInfo ITableRangeNo description
  • tableId string (optional)No description
  • options ITableOptions (optional)No description

Returns

  • Promise<string> — See signature above.
Source: @univerjs/sheets-table

getTableInfo

Signature

TypeScript
getTableInfo(tableId: string): ITableInfoWithUnitId | undefined

Parameters

  • tableId stringNo description

Returns

  • any — See signature above.
Source: @univerjs/sheets-table

getTableList

Signature

TypeScript
getTableList(): ITableInfoWithUnitId[]

Returns

  • ITableInfoWithUnitId[] — See signature above.
Source: @univerjs/sheets-table

removeTable

Signature

TypeScript
async removeTable(tableId: string): Promise<boolean>

Parameters

  • tableId stringNo description

Returns

  • Promise<boolean> — See signature above.
Source: @univerjs/sheets-table

setEditable

Used to modify the editing permissions of the workbook. When the value is false, editing is not allowed.

Signature

TypeScript
setEditable(value: boolean): FWorkbook

Parameters

  • value booleanNo description

Returns

  • FWorkbook — FWorkbook instance

Examples

TypeScript
// The code below sets the editing permissions of the workbookconst fWorkbook = univerAPI.getActiveWorkbook();fWorkbook.setEditable(false);
Source: @univerjs/sheets

setTableFilter

Signature

TypeScript
setTableFilter(tableId: string, column: number, filter: ITableFilterItem | undefined): Promise<boolean>

Parameters

  • tableId stringNo description
  • column numberNo description
  • filter anyNo description

Returns

  • Promise<boolean> — See signature above.
Source: @univerjs/sheets-table

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.