Class: FWorkbook
Facade API object bounded to a workbook. It provides a set of methods to interact with the workbook.
Extends
FBaseInitialable.IFWorkbookEngineFormulaMixin.IFWorkbookNumfmtMixin.IFWorkbookHyperlinkMixin.IFWorkbookDataValidationMixin.IFWorkbookConditionalFormattingMixin.IFWorkbookThreadCommentMixin.IFWorkbookSheetsPivotMixin.IFWorkbookSheetsUIMixin.IFWorkbookSheetsZenEditorMixin.IFWorkbookSheetsPrintMixin
Properties
| Property | Modifier | Type |
|---|---|---|
|
|
|
Methods
abortEditingAsync()
abortEditingAsync(): Promise<boolean>Returns
Promise<boolean>
Whether the editing process is ended successfully
Async
End the editing process of the current active cell
Example
const fWorkbook = univerAPI.getActiveWorkbook();
await fWorkbook.abortEditingAsync();addPivotTable()
addPivotTable(
sourceInfo,
positionType,
anchorCellInfo): Promise<FPivotTable>Parameters
| Parameter | Type | Description |
|---|---|---|
sourceInfo | any | The source data range info of the pivot table. |
positionType | PositionType | whether new a sheet or insert a pivot table to the existing sheet. |
anchorCellInfo | IPivotCellPositionInfo | The target cell info of the pivot table. |
Returns
Promise<FPivotTable>
The added pivot table id.
Description
Add a pivot table to the Workbook.
Example
// should ensure the sheet range A1:G9 is not empty
const fWorkbook = univerAPI.getActiveWorkbook();
const unitId = fWorkbook.getId();
const fSheet = fWorkbook.getActiveSheet();
const subUnitId = fSheet.getSheetId();
const sheetName = fSheet.getSheetName();
const sourceInfo = {
unitId,
subUnitId,
sheetName,
range: {
startRow: 0,
endRow: 8,
startColumn: 0,
endColumn: 6
}
};
const anchorCellInfo = {
unitId,
subUnitId,
row: 0,
col: 8
};
const fPivotTable = await fWorkbook.addPivotTable(sourceInfo, 'existing', anchorCellInfo);
const pivotTableId = fPivotTable.getPivotTableId();
let hasAdded = false;
// the addPivotTable is async, you can add pivot fields after the pivot table is added
univerAPI.addEvent(univerAPI.Event.PivotTableRendered, (params) => {
if (!hasAdded && params.pivotTableId === pivotTableId) {
fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0);
fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Value, 0);
hasAdded = true;
}
});addStyles()
addStyles(styles): voidAdd styles to the workbook styles.
Parameters
| Parameter | Type | Description |
|---|---|---|
styles | Record<string, IStyleData> | Styles to add |
Returns
void
Example
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' }],
]);clearComments()
clearComments(): Promise<boolean>Clear all comments in the current workbook
Returns
Promise<boolean>
Whether the comments are cleared successfully.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const result = await fWorkbook.clearComments();
console.log(result);closePrintDialog()
closePrintDialog(): voidClose print preview dialog.
Returns
void
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.openPrintDialog();
// Close print dialog after 3 seconds
setTimeout(() => {
fWorkbook.closePrintDialog();
}, 3000);create()
create(
name,
rows,
columns,
options?): FWorksheetCreate a new worksheet and returns a handle to it.
Parameters
| Parameter | Type | Description |
|---|---|---|
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? | Pick<IInsertSheetCommandParams, … | …> | The options for the new sheet |
Returns
The new created sheet
Example
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()
createRangeThemeStyle(themeName, themeStyleJson?): RangeThemeStyleCreate a range theme style.
Parameters
| Parameter | Type | Description |
|---|---|---|
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
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
secondRowStyle: {
bg: {
rgb: 'rgb(214,231,241)',
},
},
});
console.log(rangeThemeStyle);createSheetHyperlink()
createSheetHyperlink(
this,
sheetId,
range?): stringParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
sheetId | string |
range? | string | IRange |
Returns
string
Deprecated
use getUrl method in FRange or FWorksheet instead.
customizeColumnHeader()
customizeColumnHeader(cfg): voidCustomize the column header of the all worksheets in the workbook.
Parameters
| Parameter | Type | Description |
|---|---|---|
cfg | IColumnsHeaderCfgParam | The configuration of the column header. |
Returns
void
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.customizeColumnHeader({
headerStyle: {
fontColor: '#fff',
backgroundColor: '#4e69ee',
fontSize: 9
},
columnsCfg: {
0: 'kuma II',
3: {
text: 'Size',
textAlign: 'left', // CanvasTextAlign
fontColor: '#fff',
fontSize: 12,
borderColor: 'pink',
backgroundColor: 'pink',
},
4: 'Wow'
}
});customizeRowHeader()
customizeRowHeader(cfg): voidCustomize the row header of the all worksheets in the workbook.
Parameters
| Parameter | Type | Description |
|---|---|---|
cfg | IRowsHeaderCfgParam | The configuration of the row header. |
Returns
void
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.customizeRowHeader({
headerStyle: {
backgroundColor: 'pink',
fontSize: 12
},
rowsCfg: {
0: 'Moka II',
3: {
text: 'Size',
textAlign: 'left', // CanvasTextAlign
},
}
});deleteActiveSheet()
deleteActiveSheet(): booleanDeletes the currently active sheet.
Returns
boolean
true if the sheet was deleted, false otherwise
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.deleteActiveSheet();deleteDefinedName()
deleteDefinedName(name): booleanDelete the defined name with the given name.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The name of the defined name to delete |
Returns
boolean
true if the defined name was deleted, false otherwise
Example
// The code below deletes the defined name with the given name
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.deleteDefinedName('MyDefinedName');deleteSheet()
deleteSheet(sheet): booleanDeletes the specified worksheet.
Parameters
| Parameter | Type | Description |
|---|---|---|
sheet | string | FWorksheet | The instance or id of the worksheet to delete. |
Returns
boolean
True if the worksheet was deleted, false otherwise.
Example
// 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());disableSelection()
disableSelection(): FWorkbookDisable selection. After disabled, there would be no response for selection.
Returns
FWorkbook
FWorkbook instance for chaining
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.disableSelection();dispose()
dispose(): voidReturns
void
duplicateActiveSheet()
duplicateActiveSheet(): FWorksheetDuplicates the active sheet.
Returns
The duplicated worksheet
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const duplicatedSheet = fWorkbook.duplicateActiveSheet();
console.log(duplicatedSheet);duplicateSheet()
duplicateSheet(sheet): FWorksheetDuplicates the given worksheet.
Parameters
| Parameter | Type | Description |
|---|---|---|
sheet | FWorksheet | The worksheet to duplicate. |
Returns
The duplicated worksheet
Example
// The code below duplicates the given worksheet
const fWorkbook = univerAPI.getActiveWorkbook();
const activeSheet = fWorkbook.getActiveSheet();
const duplicatedSheet = fWorkbook.duplicateSheet(activeSheet);
console.log(duplicatedSheet);enableSelection()
enableSelection(): FWorkbookEnable selection. After this you can select range.
Returns
FWorkbook
FWorkbook instance for chaining
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.enableSelection();endEditing()
endEditing(save?): Promise<boolean>Parameters
| Parameter | Type |
|---|---|
save? | boolean |
Returns
Promise<boolean>
Deprecated
Use endEditingAsync as instead
endEditingAsync()
endEditingAsync(save?): Promise<boolean>Parameters
| Parameter | Type | Description |
|---|---|---|
save? | boolean | Whether to save the changes, default is true |
Returns
Promise<boolean>
Whether the editing process is ended successfully
Async
End the editing process of the current active cell
Example
const fWorkbook = univerAPI.getActiveWorkbook();
await fWorkbook.endEditingAsync(false);endZenEditingAsync()
endZenEditingAsync(save?): Promise<boolean>End the zen editing process on the active cell and optionally save the changes
Parameters
| Parameter | Type | Description |
|---|---|---|
save? | boolean | Whether to save the changes, default is true |
Returns
Promise<boolean>
A promise that resolves to a boolean indicating whether the zen editing process was ended successfully.
Async
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const success = await fWorkbook.endZenEditingAsync(false);
console.log(success);getActiveCell()
getActiveCell(): FRangeReturns the active cell in this spreadsheet.
Returns
The active cell
Example
const fWorkbook = univerAPI.getActiveWorkbook();
console.log(fWorkbook.getActiveCell().getA1Notation());getActiveRange()
getActiveRange(): FRangeReturns the selected range in the active sheet, or null if there is no active range.
Returns
The active range
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const activeRange = fWorkbook.getActiveRange();
console.log(activeRange);getActiveSheet()
getActiveSheet(): FWorksheetGet the active sheet of the workbook.
Returns
The active sheet of the workbook
Example
// The code below gets the active sheet of the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
console.log(fWorksheet);getAllDataValidationErrorAsync()
getAllDataValidationErrorAsync(): Promise<...[]>Get all data validation errors for current workbook.
Returns
Promise<…[]>
A promise that resolves to an array of validation errors.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const errors = await fWorkbook.getAllDataValidationError();
console.log(errors);getAllFormulaError()
getAllFormulaError(): ISheetFormulaError[]Get all formula errors in the workbook
Returns
ISheetFormulaError[]
Array of formula errors
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const errors = fWorkbook.getAllFormulaError();
console.log('Formula errors:', errors);getComments()
getComments(): FThreadComment[]Get all comments in the current workbook
Returns
All comments in the current workbook
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const comments = fWorkbook.getComments();
comments.forEach((comment) => {
const isRoot = comment.getIsRoot();
if (isRoot) {
console.log('root comment:', comment.getCommentData());
const replies = comment.getReplies();
replies.forEach((reply) => {
console.log('reply comment:', reply.getCommentData());
});
}
});getCustomMetadata()
getCustomMetadata(): CustomDataGet custom metadata of workbook
Returns
custom metadata
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const custom = fWorkbook.getCustomMetadata();
console.log(custom);getDefinedName()
getDefinedName(name): FDefinedNameGet the defined name by name.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The name of the defined name to get |
Returns
The defined name with the given name
Example
// 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()
getDefinedNames(): FDefinedName[]Get all the defined names in the workbook.
Returns
All the defined names in the workbook
Example
// 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()
getId(): stringGet the id of the workbook.
Returns
string
The id of the workbook.
Example
// The code below gets the id of the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
const unitId = fWorkbook.getId();
console.log(unitId);getLocale()
getLocale(): LocaleTypeGet the locale of the workbook.
Returns
The locale of the workbook
Example
// The code below gets the locale of the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
console.log(fWorkbook.getLocale());getName()
getName(): stringGet the name of the workbook.
Returns
string
The name of the workbook.
Example
// The code below gets the name of the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
const name = fWorkbook.getName();
console.log(name);getNumSheets()
getNumSheets(): numberGet the number of sheets in the workbook.
Returns
number
The number of sheets in the workbook
Example
// The code below gets the number of sheets in the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
console.log(fWorkbook.getNumSheets());getPermission()
getPermission(): FPermissionGet the PermissionInstance.
Returns
- The PermissionInstance.
Deprecated
Use getWorkbookPermission() instead for the new permission API
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const permission = fWorkbook.getPermission();
console.log(permission);getPivotTableByCell()
getPivotTableByCell(
unitId,
subUnitId,
row,
col): FPivotTableParameters
| Parameter | Type | Description |
|---|---|---|
unitId | string | The unit id of workbook. |
subUnitId | string | The sheet id, which pivot table belongs to. |
row | number | The checked row. |
col | number | The checked column. |
Returns
The pivot table instance or undefined.
Description
Get the pivot table id by the cell.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const unitId = fWorkbook.getId();
const fSheet = fWorkbook.getActiveSheet();
const subUnitId = fSheet.getSheetId();
const fPivotTable = fWorkbook.getPivotTableByCell(unitId, subUnitId, 0, 8);
if(fPivotTable) {
fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0);
}getPivotTableById()
getPivotTableById(pivotTableId): FPivotTableParameters
| Parameter | Type | Description |
|---|---|---|
pivotTableId | string | The pivot table id. |
Returns
The pivot table instance or undefined.
Description
Get the pivot table by the pivot table id.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const mockId = 'abc123456';
const fPivotTable = fWorkbook.getPivotTableById(mockId);
if(fPivotTable) {
fPivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0);
}getRegisteredRangeThemes()
getRegisteredRangeThemes(): string[]Gets the registered range themes.
Returns
string[]
The name list of registered range themes.
Example
// The code below gets the registered range themes
const fWorkbook = univerAPI.getActiveWorkbook();
const themes = fWorkbook.getRegisteredRangeThemes();
console.log(themes);getScrollStateBySheetId()
getScrollStateBySheetId(sheetId): anyGet scroll state of specified sheet.
Parameters
| Parameter | Type | Description |
|---|---|---|
sheetId | string | sheet id |
Returns
any
scroll state
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
// scroll to cell D10
fWorksheet.scrollToCell(9, 3);
// get scroll state
const scrollState = fWorkbook.getScrollStateBySheetId(fWorksheet.getSheetId());
const { offsetX, offsetY, sheetViewStartRow, sheetViewStartColumn } = scrollState;
console.log(scrollState); // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0getSheetByName()
getSheetByName(name): FWorksheetGet a worksheet by sheet name.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The name of the sheet to get. |
Returns
The worksheet with given sheet name
Example
// The code below gets a worksheet by sheet name
const fWorkbook = univerAPI.getActiveWorkbook();
const sheet = fWorkbook.getSheetByName('Sheet1');
console.log(sheet);getSheetBySheetId()
getSheetBySheetId(sheetId): FWorksheetGet a worksheet by sheet id.
Parameters
| Parameter | Type | Description |
|---|---|---|
sheetId | string | The id of the sheet to get. |
Returns
The worksheet with given sheet id
Example
// The code below gets a worksheet by sheet id
const fWorkbook = univerAPI.getActiveWorkbook();
const sheet = fWorkbook.getSheetBySheetId('sheetId');
console.log(sheet);getSheets()
getSheets(): FWorksheet[]Gets all the worksheets in this workbook
Returns
An array of all the worksheets in the workbook
Example
// The code below gets all the worksheets in the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
const sheets = fWorkbook.getSheets();
console.log(sheets);getSnapshot()
getSnapshot(): IWorkbookDataReturns
Workbook snapshot data
Deprecated
use ‘save’ instead.
Memberof
FWorkbook
Example
// The code below saves the workbook snapshot data
const activeSpreadsheet = univerAPI.getActiveWorkbook();
const snapshot = activeSpreadsheet.getSnapshot();getUrl()
getUrl(): stringGet the URL of the workbook.
Returns
string
The URL of the workbook
Example
// The code below gets the URL of the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
const url = fWorkbook.getUrl();
console.log(url);getValidatorStatus()
getValidatorStatus(): Promise<Record<..., ...>>Get data validation validator status for current workbook.
Returns
Promise<Record<…, …>>
A promise that resolves to a matrix of validator status.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const status = await fWorkbook.getValidatorStatus();
console.log(status);getWorkbook()
getWorkbook(): WorkbookGet the Workbook instance.
Returns
Workbook
The Workbook instance.
Example
// The code below gets the Workbook instance
const fWorkbook = univerAPI.getActiveWorkbook();
const workbook = fWorkbook.getWorkbook();
console.log(workbook);getWorkbookPermission()
getWorkbookPermission(): FWorkbookPermissionGet the WorkbookPermission instance for managing workbook-level permissions. This is the new permission API that provides a more intuitive and type-safe interface.
Returns
- The WorkbookPermission instance.
Example
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()
insertDefinedName(name, formulaOrRefString): FWorkbookInsert a defined name.
Parameters
| Parameter | Type | Description |
|---|---|---|
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
Example
// The code below inserts a defined name
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.insertDefinedName('MyDefinedName', 'Sheet1!$A$1');insertDefinedNameBuilder()
insertDefinedNameBuilder(param): voidInsert a defined name by builder param.
Parameters
| Parameter | Type | Description |
|---|---|---|
param | ISetDefinedNameMutationParam | The param to insert the defined name |
Returns
void
Example
// 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()
insertSheet(sheetName?, options?): FWorksheetInserts a new worksheet into the workbook. Using a default sheet name. The new sheet becomes the active sheet
Parameters
| Parameter | Type | Description |
|---|---|---|
sheetName? | string | The name of the new sheet |
options? | Pick<IInsertSheetCommandParams, … | …> | The options for the new sheet |
Returns
The new sheet
Example
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);isCellEditing()
isCellEditing(): booleanCheck if the current active cell is in editing state
Returns
boolean
True if the current active cell is in editing state, false otherwise
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const isEditing = fWorkbook.isCellEditing();
console.log(isEditing);moveActiveSheet()
moveActiveSheet(index): FWorkbookMove the active sheet to the specified index.
Parameters
| Parameter | Type | Description |
|---|---|---|
index | number | The index to move the active sheet to |
Returns
FWorkbook
This workbook, for chaining
Example
// The code below moves the active sheet to the specified index
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.moveActiveSheet(1);moveSheet()
moveSheet(sheet, index): FWorkbookMove the sheet to the specified index.
Parameters
| Parameter | Type | Description |
|---|---|---|
sheet | FWorksheet | The sheet to move |
index | number | The index to move the sheet to |
Returns
FWorkbook
This workbook, for chaining
Example
// The code below moves the sheet to the specified index
const fWorkbook = univerAPI.getActiveWorkbook();
const sheet = fWorkbook.getActiveSheet();
fWorkbook.moveSheet(sheet, 1);newColor()
newColor(): ColorBuilderReturns
ColorBuilder
Deprecated
use univerAPI.newColor() as instead.
onBeforeAddDataValidation()
onBeforeAddDataValidation(this, callback): IDisposableParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
callback | (params, options) => … | … |
Returns
IDisposable
Deprecated
Use univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationAdd, (event) => { ... }) instead
onBeforeAddThreadComment()
onBeforeAddThreadComment(this, callback): IDisposableParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
callback | (params, options) => … | … |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.BeforeCommentAdd, (params) => {}) as instead
onBeforeCommandExecute()
onBeforeCommandExecute(callback): IDisposableRegister a callback that will be triggered before invoking a command targeting the Univer sheet.
Parameters
| Parameter | Type | Description |
|---|---|---|
callback | CommandListener | the callback. |
Returns
IDisposable
A function to dispose the listening.
Example
// 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);
});onBeforeDeleteAllDataValidation()
onBeforeDeleteAllDataValidation(this, callback): IDisposableParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
callback | (params, options) => … | … |
Returns
IDisposable
Deprecated
Use univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDeleteAll, (event) => { ... }) instead
onBeforeDeleteDataValidation()
onBeforeDeleteDataValidation(this, callback): IDisposableParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
callback | (params, options) => … | … |
Returns
IDisposable
Deprecated
Use univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationDelete, (event) => { ... }) instead
onBeforeDeleteThreadComment()
onBeforeDeleteThreadComment(this, callback): IDisposableParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
callback | (params, options) => … | … |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.BeforeCommentDelete, (params) => {}) as instead
onBeforeUpdateDataValidationCriteria()
onBeforeUpdateDataValidationCriteria(this, callback): IDisposableParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
callback | (params, options) => … | … |
Returns
IDisposable
Deprecated
Use univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationCriteriaUpdate, (event) => { ... }) instead
onBeforeUpdateDataValidationOptions()
onBeforeUpdateDataValidationOptions(this, callback): IDisposableParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
callback | (params, options) => … | … |
Returns
IDisposable
Deprecated
Use univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationOptionsUpdate, (event) => { ... }) instead
onBeforeUpdateDataValidationRange()
onBeforeUpdateDataValidationRange(this, callback): IDisposableParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
callback | (params, options) => … | … |
Returns
IDisposable
Deprecated
Use univerAPI.addEvent(univerAPI.Event.BeforeSheetDataValidationRangeUpdate, (event) => { ... }) instead
onBeforeUpdateThreadComment()
onBeforeUpdateThreadComment(this, callback): IDisposableParameters
| Parameter | Type |
|---|---|
this | FWorkbook |
callback | (params, options) => … | … |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.BeforeCommentUpdate, (params) => {}) as instead
onCellClick()
onCellClick(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (cell) => void |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {}) instead
onCellHover()
onCellHover(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (cell) => void |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.CellHover, (params) => {}) instead
onCellPointerDown()
onCellPointerDown(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (cell) => void |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.CellPointerDown, (params) => {}) instead
onCellPointerMove()
onCellPointerMove(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (cell, event) => void |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.CellPointerMove, (params) => {}) instead
onCellPointerUp()
onCellPointerUp(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (cell) => void |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.CellPointerUp, (params) => {}) instead
onCommandExecuted()
onCommandExecuted(callback): IDisposableRegister a callback that will be triggered when a command is invoked targeting the Univer sheet.
Parameters
| Parameter | Type | Description |
|---|---|---|
callback | CommandListener | the callback. |
Returns
IDisposable
A function to dispose the listening.
Example
// 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);
});onDataValidationChange()
onDataValidationChange(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (ruleChange) => void |
Returns
IDisposable
Deprecated
Use univerAPI.addEvent(univerAPI.Event.SheetDataValidationChanged, (event) => { ... }) instead
onDataValidationStatusChange()
onDataValidationStatusChange(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (statusChange) => void |
Returns
IDisposable
Deprecated
Use univerAPI.addEvent(univerAPI.Event.SheetDataValidatorStatusChanged, (event) => { ... }) instead
onDragOver()
onDragOver(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (cell) => void |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.DragOver, (params) => {}) instead
onDrop()
onDrop(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (cell) => void |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.Drop, (params) => {}) instead
onSelectionChange()
onSelectionChange(callback): IDisposableRegister a callback that will be triggered when the selection changes.
Parameters
| Parameter | Type | Description |
|---|---|---|
callback | (selections) => void | The callback. |
Returns
IDisposable
A function to dispose the listening
Example
// 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);
});onThreadCommentChange()
onThreadCommentChange(callback): IDisposableParameters
| Parameter | Type |
|---|---|
callback | (commentUpdate) => … | … |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.CommentUpdated, (params) => {}) as instead
openDialog()
openDialog(dialog): IDisposableOpen a dialog.
Parameters
| Parameter | Type | Description |
|---|---|---|
dialog | IDialogPartMethodOptions | the dialog options |
Returns
IDisposable
the disposable object
Deprecated
use univerAPI.openDialog instead
Example
import { Button } from '@univerjs/design';
univerAPI.openDialog({
id: 'mock-dialog-id',
width: 500,
title: {
label: 'Dialog Title',
},
children: {
label: 'Dialog Content',
},
footer: {
title: (
<>
<Button onClick={() => { console.log('Cancel clicked') }}>Cancel</Button>
<Button variant="primary" onClick={() => { console.log('Confirm clicked') }} style={{marginLeft: '10px'}}>Confirm</Button>
</>
)
},
draggable: true,
mask: true,
maskClosable: true,
});openPrintDialog()
openPrintDialog(): voidOpen print preview dialog.
Returns
void
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.openPrintDialog();openSiderbar()
openSiderbar(params): IDisposableOpen a sidebar.
Parameters
| Parameter | Type | Description |
|---|---|---|
params | ISidebarMethodOptions | the sidebar options |
Returns
IDisposable
the disposable object
Deprecated
use univerAPI.openSidebar instead
Example
univerAPI.openSidebar({
id: 'mock-sidebar-id',
width: 300,
header: {
label: 'Sidebar Header',
},
children: {
label: 'Sidebar Content',
},
footer: {
label: 'Sidebar Footer',
},
onClose: () => {
console.log('Sidebar closed')
},
});parseSheetHyperlink()
parseSheetHyperlink(this, hyperlink): ISheetHyperLinkInfoParse the hyperlink string to get the hyperlink info.
Parameters
| Parameter | Type | Description |
|---|---|---|
this | FWorkbook | - |
hyperlink | string | The hyperlink string. |
Returns
ISheetHyperLinkInfo
The hyperlink info.
Example
// Create a hyperlink to the range A1:D10 of the current sheet
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const fRange = fWorksheet.getRange('A1:D10');
const hyperlink = fRange.getUrl();
// Parse the hyperlink
const hyperlinkInfo = fWorkbook.parseSheetHyperlink(hyperlink);
console.log(hyperlinkInfo);print()
print(): voidUsing current print config and render config to print.
Returns
void
Example
const fWorkbook = univerAPI.getActiveWorkbook();
// Update print layout config by default
fWorkbook.updatePrintConfig({});
// Update print render config by default
fWorkbook.updatePrintRenderConfig({});
// Start print
fWorkbook.print();redo()
redo(): FWorkbookRedo the last undone action.
Returns
FWorkbook
A promise that resolves to true if the redo was successful, false otherwise.
Example
// The code below redoes the last undone action
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.redo();registerRangeTheme()
registerRangeTheme(rangeThemeStyle): voidRegister a custom range theme style.
Parameters
| Parameter | Type | Description |
|---|---|---|
rangeThemeStyle | RangeThemeStyle | The range theme style to register |
Returns
void
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const rangeThemeStyle = fWorkbook.createRangeThemeStyle('MyTheme', {
secondRowStyle: {
bg: {
rgb: 'rgb(214,231,241)',
},
},
});
fWorkbook.registerRangeTheme(rangeThemeStyle);removeStyles()
removeStyles(styleKeys): voidRemove styles from the workbook styles.
Parameters
| Parameter | Type | Description |
|---|---|---|
styleKeys | string[] | Style keys to remove |
Returns
void
Example
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(): IWorkbookDataSave workbook snapshot data, including conditional formatting, data validation, and other plugin data.
Returns
Workbook snapshot data
Example
// The code below saves the workbook snapshot data
const fWorkbook = univerAPI.getActiveWorkbook();
const snapshot = fWorkbook.save();
console.log(snapshot);saveScreenshotToClipboard()
saveScreenshotToClipboard(): Promise<boolean>Save screenshot of current range to clipboard.
This API is only available with a license. Without a license, usage is restricted, and save operations will return false.
We use the Clipboard API to save the image to the clipboard, which may fail in an insecure network environment or in some unsupported browsers. A successful save will return true.
Returns
Promise<boolean>
- The result of saving the screenshot to the clipboard.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const result = await fWorkbook.saveScreenshotToClipboard();
console.log(result); // true or falsesetActiveRange()
setActiveRange(range): FWorkbookSets the selection region for active sheet.
Parameters
| Parameter | Type | Description |
|---|---|---|
range | FRange | The range to set as the active selection. |
Returns
FWorkbook
FWorkbook instance
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const range = fWorkbook.getActiveSheet().getRange('A10:B10');
fWorkbook.setActiveRange(range);setActiveSheet()
setActiveSheet(sheet): FWorksheetSets the given worksheet to be the active worksheet in the workbook.
Parameters
| Parameter | Type | Description |
|---|---|---|
sheet | string | FWorksheet | The instance or id of the worksheet to set as active. |
Returns
The active worksheet
Example
// 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()
setCustomMetadata(custom): FWorkbookSet custom metadata of workbook
Parameters
| Parameter | Type | Description |
|---|---|---|
custom | CustomData | custom metadata |
Returns
FWorkbook
FWorkbook
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.setCustomMetadata({ key: 'value' });setEditable()
setEditable(value): FWorkbookUsed to modify the editing permissions of the workbook. When the value is false, editing is not allowed.
Parameters
| Parameter | Type | Description |
|---|---|---|
value | boolean | editable value want to set |
Returns
FWorkbook
FWorkbook instance
Example
// The code below sets the editing permissions of the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.setEditable(false);setLocale()
setLocale(locale): voidParameters
| Parameter | Type | Description |
|---|---|---|
locale | LocaleType | The locale to set |
Returns
void
Deprecated
use setSpreadsheetLocale instead.
setName()
setName(name): thisSet the name of the workbook.
Parameters
| Parameter | Type | Description |
|---|---|---|
name | string | The new name of the workbook. |
Returns
this
Example
// The code below sets the name of the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.setName('MyWorkbook');setNumfmtLocal()
setNumfmtLocal(locale): FWorkbookSet the locale for number formatting.
Parameters
| Parameter | Type | Description |
|---|---|---|
locale | INumfmtLocaleTag | zh_CN,zh_TW,zh_HK,ja,ko,th,cs,da,nl,en,en_AU,en_CA,en_GB,en_IE,fi,fr,fr_CA,fr_CH,de,de_CH,el,hu,is,id,it,it_CH,nb,no,pl,pt,pt_BR,ru,sk,es,es_AR,es_BO,es_CL,es_CO,es_EC,es_MX,es_PY,es_UY,es_VE,sv,tr,cy,az,be,bg,ca,fil,gu,he,hr,hy,ka,kk,kn,lt,lv,ml,mn,mr,my,pa,ro,sl,sr,ta,te,uk,vi,ar,bn,hi |
Returns
FWorkbook
The FWorkbook instance for chaining.
Memberof
IFWorkbookNumfmtMixin
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const fRange = fWorksheet.getRange('A1');
fRange.setValue(1234.567).setNumberFormat('#,##0.00');
// Set the locale en_US for number formatting.
fWorkbook.setNumfmtLocal('en_US');
console.log(fRange.getDisplayValue()); // 1,234.57
// Set the locale de_DE for number formatting.
fWorkbook.setNumfmtLocal('de_DE');
console.log(fRange.getDisplayValue()); // 1.234,57Inherited from
IFWorkbookNumfmtMixin.setNumfmtLocal
setSpreadsheetLocale()
setSpreadsheetLocale(locale): FWorkbookSet the locale of the workbook.
Parameters
| Parameter | Type | Description |
|---|---|---|
locale | LocaleType | The locale to set |
Returns
FWorkbook
This workbook, for chaining
Example
// The code below sets the locale of the workbook
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.setSpreadsheetLocale(univerAPI.Enum.LocaleType.EN_US);
console.log(fWorkbook.getLocale());showSelection()
showSelection(): FWorkbookSet selection visible.
Returns
FWorkbook
FWorkbook instance for chaining
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.showSelection();startEditing()
startEditing(): booleanStart the editing process of the current active cell
Returns
boolean
Whether the editing process is started successfully
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.startEditing();startZenEditingAsync()
startZenEditingAsync(): Promise<boolean>Enter the zen editing process on the active cell
Returns
Promise<boolean>
A promise that resolves to a boolean indicating whether the zen editing process was started successfully.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const success = await fWorkbook.startZenEditingAsync();
console.log(success);transparentSelection()
transparentSelection(): FWorkbookSet selection invisible, Unlike disableSelection, selection still works, you just can not see them.
Returns
FWorkbook
FWorkbook instance for chaining
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.transparentSelection();undo()
undo(): FWorkbookUndo the last action.
Returns
FWorkbook
A promise that resolves to true if the undo was successful, false otherwise.
Example
// The code below undoes the last action
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.undo();unregisterRangeTheme()
unregisterRangeTheme(themeName): voidUnregister a custom range theme style.
Parameters
| Parameter | Type | Description |
|---|---|---|
themeName | string | The name of the theme to unregister |
Returns
void
Example
const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.unregisterRangeTheme('MyTheme');updateDefinedNameBuilder()
updateDefinedNameBuilder(param): voidUpdate the defined name with the given name.
Parameters
| Parameter | Type | Description |
|---|---|---|
param | ISetDefinedNameMutationParam | The param to insert the defined name |
Returns
void
Example
// 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);
}updatePrintConfig()
updatePrintConfig(config): FWorkbookUpdate print config, include print area, page-setting, scale, freeze, margin, and etc.
Parameters
| Parameter | Type | Description |
|---|---|---|
config | ISheetPrintLayoutConfig | The print layout config. |
Returns
FWorkbook
- The current workbook instance for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const subUnitId = fWorksheet.getSheetId();
// Update print layout config
fWorkbook.updatePrintConfig({
area: univerAPI.Enum.PrintArea.CurrentSheet, // print current sheet
subUnitIds: [subUnitId],
paperSize: univerAPI.Enum.PrintPaperSize.A4, // A4 paper size
scale: univerAPI.Enum.PrintScale.FitPage, // fit content to page
freeze: [univerAPI.Enum.PrintFreeze.Row], // freeze row headers
margin: univerAPI.Enum.PrintPaperMargin.Normal, // normal margin
// ... other settings
});
// Start print
fWorkbook.print();updatePrintRenderConfig()
updatePrintRenderConfig(config): FWorkbookUpdate print render config, include print header-footer setting, alignment, gridline, and etc.
Parameters
| Parameter | Type | Description |
|---|---|---|
config | ISheetPrintRenderConfig | The print render config. |
Returns
FWorkbook
- The current workbook instance for chaining.
Example
const fWorkbook = univerAPI.getActiveWorkbook();
// Update print layout config by default
fWorkbook.updatePrintConfig({});
// Update print render config
fWorkbook.updatePrintRenderConfig({
gridlines: true, // show gridlines
hAlign: univerAPI.Enum.PrintAlign.Middle, // horizontal align middle
vAlign: univerAPI.Enum.PrintAlign.Middle, // vertical align middle
headerFooter: [ // the array of header and footer elements to include, here is page numbers and worksheet name
univerAPI.Enum.PrintHeaderFooter.PageSize,
univerAPI.Enum.PrintHeaderFooter.WorksheetTitle
],
// ... other settings
});
// Start print
fWorkbook.print();