Skip to Content
ClassesFWorksheet

Class: FWorksheet

A Facade API object bounded to a worksheet. It provides a set of methods to interact with the worksheet.

Extends

  • FBaseInitialable.IFWorksheetHyperlinkMixin.IFWorksheetFilter.IFWorksheetSort.IFWorksheetDataValidationMixin.IFWorksheetConditionalFormattingMixin.IFWorksheetCommentMixin.IFWorkSheetPivotMixin.IFWorksheetSparklineMixin.IFWorksheetSkeletonMixin.IFWorksheetLegacy.IFWorksheetChartMixin

Properties

PropertyTypeDescription

setActiveSelection

(range: FRange) => FWorksheet

Sets the active selection region for this sheet.

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorkSheet.setActiveSelection(fWorkSheet.getRange('A10:B10'));

Methods

activate()

activate(): FWorksheet

Activates this sheet. Does not alter the sheet itself, only the parent’s notion of the active sheet.

Returns

FWorksheet

Current sheet, for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheets = fWorkbook.getSheets(); // activate the last sheet fWorkSheets[fWorkSheets.length - 1].activate();

addConditionalFormattingRule()

addConditionalFormattingRule(rule): FWorksheet

Add a new conditional format

Parameters

ParameterTypeDescription
ruleIConditionFormattingRuleThe conditional formatting rule to add

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Memberof

IFWorksheetConditionalFormattingMixin

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100. const fRange = fWorksheet.getRange('A1:T100'); const rule = fWorksheet.newConditionalFormattingRule() .whenCellNotEmpty() .setRanges([fRange.getRange()]) .setItalic(true) .setBackground('red') .setFontColor('green') .build(); fWorksheet.addConditionalFormattingRule(rule);

addFloatDomToColumnHeader()

addFloatDomToColumnHeader( column, layer, domPos, id?): Nullable<{ dispose: ...; id: ...; }>

Add dom at column header, And FloatDOM is registerComponent(BuiltInUIPart.CONTENT)

Parameters

ParameterTypeDescription
columnnumberThe column index to add the float dom.
layerPartial<IFICanvasFloatDom>The float dom layer configuration.
domPosIDOMAnchorThe anchor configuration of the float dom.
id?stringThe float dom id, if not given will be auto generated

Returns

Nullable<{ dispose: …; id: …; }>

float dom id and dispose function

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Register a float button component const FloatButton = () => { const divStyle = { width: '100px', height: '30px', backgroundColor: '#fff', border: '1px solid #ccc', boxSizing: 'border-box' as const, display: 'flex', justifyContent: 'center', alignItems: 'center', textAlign: 'center' as const, cursor: 'pointer', }; const clickHandler = () => { console.warn('click'); }; return ( <div style={divStyle} onClick={clickHandler}> FloatButton </div> ); }; univerAPI.registerComponent('FloatButton', FloatButton); // Add the float button to the column D header, position is right align, width is 100px, height is 30px, margin is 0 const disposeable = fWorksheet.addFloatDomToColumnHeader(3, { componentKey: 'FloatButton', allowTransform: false, }, { width: 100, height: 30, marginX: 0, marginY: 0, horizonOffsetAlign: 'right', }, 'myFloatButton'); // Remove the float button setTimeout(() => { disposeable?.dispose(); }, 2000);

addFloatDomToPosition()

addFloatDomToPosition(layer, id?): Nullable<{ dispose: ...; id: ...; }>

Add a float dom to position.

Parameters

ParameterTypeDescription
layerIFICanvasFloatDomThe float dom layer configuration.
id?stringThe float dom id, if not given will be auto generated.

Returns

Nullable<{ dispose: …; id: …; }>

float dom id and dispose function

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // You should register components at an appropriate time (e.g., when Univer is loaded) // This is a React component. For Vue3 components, the third parameter should be `{ framework: 'vue3' }` univerAPI.registerComponent( 'myFloatDom', ({ data }) => ( <div style={{ width: '100%', height: '100%', background: '#fff', border: '1px solid #ccc', boxSizing: 'border-box' }}> popup content: {' '} {data?.label} </div> ), ); // Add a floating DOM // If disposable is null, floating DOM addition failed const disposeable = fWorksheet.addFloatDomToPosition({ componentKey: 'myFloatDom', initPosition: { startX: 100, endX: 300, startY: 100, endY: 200, }, // Component data data: { label: 'hahah', }, }); // Remove the floating DOM setTimeout(() => { disposeable?.dispose(); }, 2000);

addFloatDomToRange()

addFloatDomToRange( range, layer, domLayout, id?): Nullable<{ dispose: ...; id: ...; }>

Add dom over range to FloatDOM, And FloatDOM is registerComponent(BuiltInUIPart.CONTENT)

Parameters

ParameterTypeDescription
rangeFRangeThe range to add the float dom.
layerPartial<IFICanvasFloatDom>The float dom layer configuration.
domLayoutIDOMAnchorThe anchor configuration of the float dom.
id?stringThe float dom id, if not given will be auto generated

Returns

Nullable<{ dispose: …; id: …; }>

float dom id and dispose function

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Register a range loading component const RangeLoading = () => { const divStyle = { width: '100%', height: '100%', backgroundColor: '#fff', border: '1px solid #ccc', boxSizing: 'border-box' as const, display: 'flex', justifyContent: 'center', alignItems: 'center', textAlign: 'center' as const, transformOrigin: 'top left', }; return ( <div style={divStyle}> Loading... </div> ); }; univerAPI.registerComponent('RangeLoading', RangeLoading); // Add the range loading component covering the range A1:C3 const range = fWorksheet.getRange('A1:C3'); const disposeable = fWorksheet.addFloatDomToRange(range, { componentKey: 'RangeLoading' }, {}, 'myRangeLoading'); setTimeout(() => { disposeable?.dispose(); }, 2000); // another example------------------- // Register a float button component const FloatButton = () => { const divStyle = { width: '100px', height: '30px', backgroundColor: '#fff', border: '1px solid #ccc', boxSizing: 'border-box' as const, display: 'flex', justifyContent: 'center', alignItems: 'center', textAlign: 'center' as const, cursor: 'pointer', }; const clickHandler = () => { console.warn('click'); }; return ( <div style={divStyle} onClick={clickHandler}> FloatButton </div> ); }; univerAPI.registerComponent('FloatButton', FloatButton); // Add the float button to the range A5:C7, position is start from A5 cell, and width is 100px, height is 30px, margin is 100% of range width and height const range2 = fWorksheet.getRange('A5:C7'); const disposeable2 = fWorksheet.addFloatDomToRange(range2, { componentKey: 'FloatButton', }, { width: 100, height: 30, marginX: '100%', // margin percent to range width, or pixel marginY: '100%' }, 'myFloatButton');

addSparkline()

addSparkline( sourceRanges, targetRanges, type): FSparkline

Parameters

ParameterTypeDescription
sourceRangesIRange[]Source data location for sparklines
targetRangesIRange[]Where to place sparklines
typeLINE_CHARTThe type of Sparklines

Returns

FSparkline

Returns the sparkline instance for the next call

Description

Add sparkline to the worksheet.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a sparkline in the range A10, with the data source in the range A1:A7. const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]; const targetRanges = [fWorksheet.getRange('A10').getRange()]; const sparkline = fWorksheet.addSparkline(sourceRanges, targetRanges, univerAPI.Enum.SparklineTypeEnum.LINE_CHART); console.log('sparkline instance', sparkline);

appendRow()

appendRow(rowContents): FWorksheet

Appends a row to the bottom of the current data region in the sheet. If a cell’s content begins with =, it’s interpreted as a formula.

Parameters

ParameterTypeDescription
rowContentsCellValue[]An array of values for the new row.

Returns

FWorksheet

Returns the current worksheet instance for method chaining.

Example

// Appends a new row with 4 columns to the bottom of the current // data region in the sheet containing the values in the array. const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); fWorkSheet.appendRow([1, 'Hello Univer', true, '=A1']);

autoFitRow()

autoFitRow(rowPosition, auto?): FWorksheet

Make certain row wrap and auto height.

Parameters

ParameterTypeDescription
rowPositionnumberThe row position to change.
auto?BooleanNumberWhether to auto fit the row height.

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorkSheet.autoFitRow(24);

autoResizeColumn()

autoResizeColumn(columnPosition): FWorksheet

Sets the width of the given column to fit its contents.

Parameters

ParameterTypeDescription
columnPositionnumberThe position of the given column to resize. index starts at 0.

Returns

FWorksheet

  • The FWorksheet instance for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Set the long text value in cell A1 const fRange = fWorksheet.getRange('A1'); fRange.setValue('Whenever it is a damp, drizzly November in my soul...'); // Set the column A to a width which fits the text fWorksheet.autoResizeColumn(0);

autoResizeColumns()

autoResizeColumns(startColumn, numColumns): FWorksheet

Sets the width of all columns starting at the given column position to fit their contents.

Parameters

ParameterTypeDescription
startColumnnumberThe position of the first column to resize. index starts at 0.
numColumnsnumberThe number of columns to auto-resize.

Returns

FWorksheet

  • The FWorksheet instance for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Set the A:C columns to a width that fits their text. fWorksheet.autoResizeColumns(0, 3);

autoResizeRows()

autoResizeRows(startRow, numRows): FWorksheet

Sets the height of all rows starting at the given row position to fit their contents.

Parameters

ParameterTypeDescription
startRownumberThe position of the first row to resize. index starts at 0.
numRowsnumberThe number of rows to auto-resize.

Returns

FWorksheet

  • The FWorksheet instance for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Set the first 3 rows to a height that fits their text. fWorksheet.autoResizeRows(0, 3);

cancelFreeze()

cancelFreeze(): FWorksheet

Cancels the frozen state of the current sheet.

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Cancel freeze fWorksheet.cancelFreeze();

clear()

clear(options?): FWorksheet

Clears the sheet of content and formatting information.Or Optionally clears only the contents or only the formatting.

Parameters

ParameterTypeDescription
options?IFacadeClearOptionsOptions for clearing the sheet. If not provided, the contents and formatting are cleared both.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // clear the sheet of content and formatting information fWorkSheet.clear(); // clear the sheet of content only fWorkSheet.clear({ contentsOnly: true });

clearComments()

clearComments(): Promise<boolean>

Clear all comments in the current sheet

Returns

Promise<boolean>

Whether the comments are cleared successfully.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const result = await fWorksheet.clearComments(); console.log(result);

clearConditionalFormatRules()

clearConditionalFormatRules(): FWorksheet

Removes all conditional format rules from the sheet.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Memberof

IFWorksheetConditionalFormattingMixin

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); fWorksheet.clearConditionalFormatRules(); console.log(fWorksheet.getConditionalFormattingRules()); // []

clearContents()

clearContents(): FWorksheet

Clears the sheet of contents, while preserving formatting information.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // clear the sheet of content only fWorkSheet.clearContents();

clearFormats()

clearFormats(): FWorksheet

Clears the sheet of formatting, while preserving contents.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // clear the sheet of formatting only fWorkSheet.clearFormats();

composeSparkline()

composeSparkline(ranges): void

Parameters

ParameterTypeDescription
rangesIRange[]The selection range to be grouped

Returns

void

Description

Group the sparklines in the selection into a new sparkline group

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a sparkline in the range A10, with the data source in the range A1:A7. const firstSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('A1:A7').getRange()], [fWorksheet.getRange('A10').getRange()] ); // Create a sparkline in the range B10, with the data source in the range B1:B7. const secondSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('B1:B7').getRange()], [fWorksheet.getRange('B10').getRange()] ); console.log('debugger', fWorksheet.getAllSubSparkline().size); // 2 // Compose the two sparklines into one group after 3 seconds setTimeout(() => { fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()]); console.log('debugger', fWorksheet.getAllSubSparkline().size); // 1 }, 3000);

createConditionalFormattingRule()

createConditionalFormattingRule(): FConditionalFormattingBuilder

Returns

FConditionalFormattingBuilder

The conditional formatting builder

Deprecated

use newConditionalFormattingRule instead. Creates a constructor for conditional formatting

Memberof

IFWorksheetConditionalFormattingMixin


customizeColumnHeader()

customizeColumnHeader(cfg): void

Customize the column header of the spreadsheet.

Parameters

ParameterTypeDescription
cfgIColumnsHeaderCfgParamThe configuration of the column header.

Returns

void

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); fWorksheet.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): void

Customize the row header of the spreadsheet.

Parameters

ParameterTypeDescription
cfgIRowsHeaderCfgParamThe configuration of the row header.

Returns

void

Example

univerAPI.customizeRowHeader({ headerStyle: { backgroundColor: 'pink', fontSize: 12 }, rowsCfg: { 0: 'MokaII', 3: { text: 'Size', textAlign: 'left' } } });

deleteColumn()

deleteColumn(columnPosition): FWorksheet

Deletes the column at the given column position.

Parameters

ParameterTypeDescription
columnPositionnumberThe position of the column, starting at 0 for the first column

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Delete column C fWorksheet.deleteColumn(2); // Delete column A fWorksheet.deleteColumn(0);

deleteColumns()

deleteColumns(columnPosition, howMany): FWorksheet

Deletes a number of columns starting at the given column position.

Parameters

ParameterTypeDescription
columnPositionnumberThe position of the first column to delete, starting at 0 for the first column
howManynumberThe number of columns to delete

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Delete 3 columns at column index 2 (columns C, D, E) fWorksheet.deleteColumns(2, 3); // Delete 1 column at column index 0 (column A) fWorksheet.deleteColumns(0, 1);

deleteConditionalFormattingRule()

deleteConditionalFormattingRule(cfId): FWorksheet

Delete conditional format according to cfId

Parameters

ParameterTypeDescription
cfIdstringThe conditional formatting rule id to delete

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Memberof

IFWorksheetConditionalFormattingMixin

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const rules = fWorksheet.getConditionalFormattingRules(); // Delete the first rule fWorksheet.deleteConditionalFormattingRule(rules[0]?.cfId);

deleteImages()

deleteImages(sheetImages): FWorksheet

Delete images from the sheet

Parameters

ParameterTypeDescription
sheetImagesFOverGridImage[]The images to delete

Returns

FWorksheet

The FWorksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const image = fWorksheet.getImages()[0]; fWorksheet.deleteImages([image]);

deleteRow()

deleteRow(rowPosition): FWorksheet

Deletes the row at the given row position.

Parameters

ParameterTypeDescription
rowPositionnumberThe position of the row, starting at 0 for the first row.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Delete the third row fWorksheet.deleteRow(2); // Delete the first row fWorksheet.deleteRow(0);

deleteRows()

deleteRows(rowPosition, howMany): FWorksheet

Deletes a number of rows starting at the given row position.

Parameters

ParameterTypeDescription
rowPositionnumberThe position of the first row to delete, starting at 0 for the first row.
howManynumberThe number of rows to delete.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Delete 3 rows at row index 2 (rows 3-5) fWorksheet.deleteRows(2, 3); // Delete 1 row at row index 0 (first row) fWorksheet.deleteRows(0, 1);

equalTo()

equalTo(other): boolean

Judge whether provided FWorksheet is equal to current.

Parameters

ParameterTypeDescription
otherFWorksheetthe FWorksheet to compare with.

Returns

boolean

true if the FWorksheet is equal to the current FWorksheet, false otherwise.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const sheets = fWorkbook.getSheets(); const fWorkSheet = fWorkbook.getActiveSheet(); console.log(fWorkSheet.equalTo(sheets[0])); // true, if the active sheet is the first sheet.

getActiveCell()

getActiveCell(): FRange

Returns the active cell in this sheet.

Returns

FRange

The active cell

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); console.log(fWorkSheet.getActiveCell().getA1Notation());

getActiveImages()

getActiveImages(): FOverGridImage[]

Get the current selected images.

Returns

FOverGridImage[]

The FOverGridImage instances

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const images = fWorksheet.getActiveImages(); images.forEach((image) => { console.log(image, image.getId()); });

getActiveRange()

getActiveRange(): FRange

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

Returns

FRange

the active range

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get the currently active range const activeRange = fWorksheet.getActiveRange(); if (activeRange) { console.log('Active range:', activeRange.getA1Notation()); }

getAllSubSparkline()

getAllSubSparkline(): Map<string, ISparklineGroup>

Returns

Map<string, ISparklineGroup>

  • The key is sparkline group id.

Description

Get all sparklines in the worksheet.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Get all sparklines in the current worksheet const allSparkline = fWorksheet.getAllSubSparkline(); console.log('allSparkline', allSparkline);

getCellMergeData()

getCellMergeData(row, column): FRange

Get the merged cell data of the specified row and column.

Parameters

ParameterTypeDescription
rownumberThe row index
columnnumberThe column index

Returns

FRange

The merged cell data, or undefined if the cell is not merged

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); const merge = fWorkSheet.getCellMergeData(0, 0); if (merge) { console.log('Merged range:', merge.getA1Notation()); }

getCharts()

getCharts(): FChart[]

Returns an array of charts on this sheet.

Returns

FChart[]

  • An array of charts on this sheet.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Get all charts on the active sheet. const charts = fWorksheet.getCharts(); console.log(charts);

getColumnCustomMetadata()

getColumnCustomMetadata(index): CustomData

Get custom metadata of column

Parameters

ParameterTypeDescription
indexnumbercolumn index

Returns

CustomData

custom metadata

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); const custom = fWorkSheet.getColumnCustomMetadata(0); console.log(custom);

getColumnDefaultStyle()

getColumnDefaultStyle(index, keepRaw?): string | Nullable<...>

Get the default style of the worksheet column

Parameters

ParameterTypeDescription
indexnumberThe column index
keepRaw?booleanIf true, return the raw style data maybe the style name or style data, otherwise return the data from col manager

Returns

string | Nullable<…>

The default style of the worksheet column name or style data

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get default style for column 0 (A) const colStyle = fWorksheet.getColumnDefaultStyle(0); console.log(colStyle); // Get raw style data for column 0 const rawColStyle = fWorksheet.getColumnDefaultStyle(0, true); console.log(rawColStyle);

getColumnWidth()

getColumnWidth(columnPosition): number

Gets the width in pixels of the given column.

Parameters

ParameterTypeDescription
columnPositionnumberThe position of the column to examine. index starts at 0.

Returns

number

The width of the column in pixels

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Set the long text value in cell A1 const fRange = fWorksheet.getRange('A1'); fRange.setValue('Whenever it is a damp, drizzly November in my soul...'); // Set the column A to a width which fits the text fWorksheet.autoResizeColumn(0); // Get the width of the column A console.log(fWorksheet.getColumnWidth(0));

getCommentById()

getCommentById(commentId): FThreadComment

get comment by comment id

Parameters

ParameterTypeDescription
commentIdstringcomment id const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a new comment const richText = univerAPI.newRichText().insertText('hello univer'); const commentBuilder = univerAPI.newTheadComment() .setContent(richText) .setId('mock-comment-id'); const cell = fWorksheet.getRange('A1'); await cell.addCommentAsync(commentBuilder); const comment = fWorksheet.getCommentById('mock-comment-id'); console.log(comment, comment?.getCommentData());

Returns

FThreadComment


getComments()

getComments(): FThreadComment[]

Get all comments in the current sheet

Returns

FThreadComment[]

All comments in the current sheet

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const comments = fWorksheet.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()); }); } });

getConditionalFormattingRules()

getConditionalFormattingRules(): IConditionFormattingRule[]

Gets all the conditional formatting for the current sheet

Returns

IConditionFormattingRule[]

conditional formatting rules for the current sheet

Memberof

IFWorksheetConditionalFormattingMixin

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const rules = fWorksheet.getConditionalFormattingRules(); console.log(rules);

getCustomMetadata()

getCustomMetadata(): CustomData

Get custom metadata of worksheet

Returns

CustomData

custom metadata

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); const custom = fWorkSheet.getCustomMetadata(); console.log(custom);

getDataRange()

getDataRange(): FRange

Returns a Range corresponding to the dimensions in which data is present. This is functionally equivalent to creating a Range bounded by A1 and (Sheet.getLastColumns(), Sheet.getLastRows()).

Returns

FRange

The range of the data in the sheet.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // Assume the sheet is a empty sheet const cellRange = fWorkSheet.getRange('J50'); cellRange.setValue('Hello World'); console.log(fWorkSheet.getDataRange().getA1Notation()); // A1:J50

getDataValidation()

getDataValidation(ruleId): Nullable<FDataValidation>

get data validation rule by rule id

Parameters

ParameterTypeDescription
ruleIdstringthe rule id

Returns

Nullable<FDataValidation>

data validation rule

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const rules = fWorksheet.getDataValidations(); console.log(fWorksheet.getDataValidation(rules[0]?.rule.uid));

getDataValidations()

getDataValidations(): FDataValidation[]

Get all data validation rules in current sheet.

Returns

FDataValidation[]

All data validation rules

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const rules = fWorksheet.getDataValidations(); console.log(rules);

getDefaultStyle()

getDefaultStyle(): string | Nullable<...>

Get the default style of the worksheet.

Returns

string | Nullable<…>

Default style of the worksheet.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const defaultStyle = fWorksheet.getDefaultStyle(); console.log(defaultStyle);

getDefinedNames()

getDefinedNames(): FDefinedName[]

Get all the defined names in the worksheet.

Returns

FDefinedName[]

All the defined names in the worksheet

Example

// The code below gets all the defined names in the worksheet const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const definedNames = fWorksheet.getDefinedNames(); console.log(definedNames);

getFilter()

getFilter(): FFilter

Get the filter for the current worksheet.

Returns

FFilter

The interface class to handle the filter. If the worksheet does not have a filter, this method would return null.

Example

const workbook = univerAPI.getActiveWorkbook(); const worksheet = workbook.getActiveSheet(); const filter = worksheet.getFilter(); console.log(filter, filter?.getRange().getA1Notation());

getFreeze()

getFreeze(): IFreeze

Get the freeze state of the current sheet.

Returns

IFreeze

The freeze state of the current sheet

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get the freeze state of the current sheet const freeze = fWorksheet.getFreeze(); console.log(freeze);

getFrozenColumnRange()

getFrozenColumnRange(): IColumnRange

Get freezed columns

Returns

IColumnRange

The range of the frozen columns.

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get the range of the frozen columns const frozenColumns = fWorkSheet.getFrozenColumnRange(); console.log(frozenColumns);

getFrozenColumns()

getFrozenColumns(): number

Get the number of frozen columns.

Returns

number

The number of frozen columns, returns 0 if no columns are frozen.

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get the number of frozen columns const frozenColumns = fWorkSheet.getFrozenColumns(); console.log(frozenColumns);

getFrozenRowRange()

getFrozenRowRange(): IRowRange

Get freezed rows.

Returns

IRowRange

The range of the frozen rows.

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get the range of the frozen rows const frozenRows = fWorkSheet.getFrozenRowRange(); console.log(frozenRows);

getFrozenRows()

getFrozenRows(): number

Get the number of frozen rows.

Returns

number

The number of frozen rows. returns 0 if no rows are frozen.

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get the number of frozen rows const frozenRows = fWorkSheet.getFrozenRows(); console.log(frozenRows);

getGridLinesColor()

getGridLinesColor(): string

Get the color of the gridlines in the sheet.

Returns

string

The color of the gridlines in the sheet or undefined. The default color is ‘rgb(214, 216, 219)’.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // get the gridlines color of the sheet console.log(fWorkSheet.getGridLinesColor());

getImageById()

getImageById(id): FOverGridImage

Get image by drawing id

Parameters

ParameterTypeDescription
idstringThe drawing id of the image

Returns

FOverGridImage

The FOverGridImage instance

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const image = fWorksheet.getImageById('xxxx'); console.log(image);

getImages()

getImages(): FOverGridImage[]

Get all images of the sheet.

Returns

FOverGridImage[]

The FOverGridImage instances

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const images = fWorksheet.getImages(); images.forEach((image) => { console.log(image, image.getId()); });

getIndex()

getIndex(): number

Gets the position of the sheet in its parent spreadsheet. Starts at 0.

Returns

number

The position of the sheet in its parent spreadsheet.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // get the position of the active sheet const position = fWorkSheet.getIndex(); console.log(position);

getInject()

getInject(): Injector

Get the injector instance.

Returns

Injector

The injector instance.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const injector = fWorksheet.getInject(); console.log(injector);

getLastColumn()

getLastColumn(): number

Returns the column index of the last column that contains content.

Returns

number

the column index of the last column that contains content.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // Assume the sheet is a empty sheet const cellRange = fWorkSheet.getRange('J50'); cellRange.setValue('Hello World'); console.log(fWorkSheet.getLastColumn()); // 9

getLastColumns()

getLastColumns(): number

Returns

number

the column index of the last column that contains content.

Deprecated

use getLastColumn instead. Returns the column index of the last column that contains content.


getLastRow()

getLastRow(): number

Returns the row index of the last row that contains content.

Returns

number

the row index of the last row that contains content.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // Assume the sheet is a empty sheet const cellRange = fWorkSheet.getRange('J50'); cellRange.setValue('Hello World'); console.log(fWorkSheet.getLastRow()); // 49

getLastRows()

getLastRows(): number

Returns

number

the row index of the last row that contains content.

Deprecated

use getLastRow instead. Returns the row index of the last row that contains content.


getMaxColumns()

getMaxColumns(): number

Returns the current number of columns in the sheet, regardless of content.

Returns

number

The maximum columns count of the sheet

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const totalColumns = fWorksheet.getMaxColumns(); console.log(`Sheet has ${totalColumns} columns`);

getMaxRows()

getMaxRows(): number

Returns the current number of rows in the sheet, regardless of content.

Returns

number

The maximum rows count of the sheet

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const totalRows = fWorksheet.getMaxRows(); console.log(`Sheet has ${totalRows} rows`);

getMergeData()

getMergeData(): FRange[]

Get all merged cells in the current worksheet

Returns

FRange[]

All the merged cells in the worksheet

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get all merged ranges in the sheet const mergedData = fWorksheet.getMergeData(); // Process each merged range mergedData.forEach(range => { console.log(range.getA1Notation()); });

getMergedRanges()

getMergedRanges(): FRange[]

Get all merged cells in the current sheet

Returns

FRange[]

all merged cells

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get all merged ranges in the sheet const mergedRanges = fWorksheet.getMergedRanges(); // Process each merged range mergedRanges.forEach(range => { console.log(range.getA1Notation()); });

getPivotTableByCell()

getPivotTableByCell(row, col): FPivotTable

Parameters

ParameterTypeDescription
rownumberThe checked row.
colnumberThe checked column.

Returns

FPivotTable

The pivot table instance or undefined.

Description

Get the pivot table id by the cell in current sheet.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fSheet = fWorkbook.getActiveSheet(); const pivotTable = fSheet.getPivotTableByCell(1, 1); if(pivotTable) { pivotTable.addField(1, univerAPI.Enum.PivotTableFiledAreaEnum.Row, 0); }

getRange()

Call Signature

getRange(row, column): FRange

Returns a Range object representing a single cell at the specified row and column.

Parameters
ParameterTypeDescription
rownumberThe row index of the cell.
columnnumberThe column index of the cell.
Returns

FRange

A Range object representing the specified cell.

Example
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get range for cell at row 0, column 0 (A1) const range = fWorksheet.getRange(0, 0); console.log(range);

Call Signature

getRange( row, column, numRows): FRange

Returns a Range object representing a range starting at the specified row and column, with the specified number of rows.

Parameters
ParameterTypeDescription
rownumberThe starting row index of the range.
columnnumberThe starting column index of the range.
numRowsnumberThe number of rows in the range.
Returns

FRange

A Range object representing the specified range.

Call Signature

getRange( row, column, numRows, numColumns): FRange

Returns a Range object representing a range starting at the specified row and column, with the specified number of rows and columns.

Parameters
ParameterTypeDescription
rownumberThe starting row index of the range.
columnnumberThe starting column index of the range.
numRowsnumberThe number of rows in the range.
numColumnsnumberThe number of columns in the range.
Returns

FRange

A Range object representing the specified range.

Example
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get range for cells A1:C3 const range = fWorksheet.getRange(0, 0, 3, 3); console.log(range);

Call Signature

getRange(a1Notation): FRange

Returns a Range object specified by A1 notation.

Parameters
ParameterTypeDescription
a1NotationstringA string representing a range in A1 notation.
Returns

FRange

A Range object representing the specified range.

Example
const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get range for cells A1:C3 const range = fWorksheet.getRange("A1:C3"); console.log(range); // Get range for a single cell const cell = fWorksheet.getRange("B2"); console.log(cell); // Get range with sheet name const sheetName = fWorksheet.getSheetName(); const rangeWithSheet = fWorksheet.getRange(`${sheetName}!A1:C3`); console.log(rangeWithSheet);

Call Signature

getRange(range): FRange

Returns a Range object for the specified range.

Parameters
ParameterTypeDescription
rangeIRangeThe range specification.
Returns

FRange

A Range object representing the specified range.


getRowCustomMetadata()

getRowCustomMetadata(index): CustomData

Get custom metadata of row

Parameters

ParameterTypeDescription
indexnumberrow index

Returns

CustomData

custom metadata

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); const custom = fWorkSheet.getRowCustomMetadata(0); console.log(custom);

getRowDefaultStyle()

getRowDefaultStyle(index, keepRaw?): string | Nullable<...>

Get the default style of the worksheet row

Parameters

ParameterTypeDescription
indexnumberThe row index
keepRaw?booleanIf true, return the raw style data maybe the style name or style data, otherwise return the data from row manager

Returns

string | Nullable<…>

The default style of the worksheet row name or style data

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Get default style for row 0 (1) const rowStyle = fWorksheet.getRowDefaultStyle(0); console.log(rowStyle); // Get raw style data for row 0 const rawRowStyle = fWorksheet.getRowDefaultStyle(0, true); console.log(rawRowStyle);

getRowHeight()

getRowHeight(rowPosition): number

Gets the height in pixels of the given row.

Parameters

ParameterTypeDescription
rowPositionnumberThe position of the row to examine. index starts at 0.

Returns

number

The height in pixels of the given row.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Set the value of the cell A1 to 'Hello, Univer!', set the font size to 30 and font weight to bold const fRange = fWorksheet.getRange('A1'); fRange.setValue('Hello, Univer!').setFontSize(30).setFontWeight('bold'); // Get the height of the first row console.log(fWorksheet.getRowHeight(0));

getScrollState()

getScrollState(): IScrollState

Get scroll state of current sheet.

Returns

IScrollState

curr scroll state

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Scroll to cell D10 const fRange = fWorksheet.getRange('D10'); const row = fRange.getRow(); const column = fRange.getColumn(); fWorksheet.scrollToCell(row, column); // Get scroll state const scrollState = fWorksheet.getScrollState(); const { offsetX, offsetY, sheetViewStartColumn, sheetViewStartRow } = scrollState; console.log(scrollState); // sheetViewStartRow: 9, sheetViewStartColumn: 3, offsetX: 0, offsetY: 0

getSelection()

getSelection(): FSelection

Get the current selection of the worksheet.

Returns

FSelection

return the current selections of the worksheet or null if there is no selection.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const selection = fWorksheet.getSelection(); console.log(selection);

getSheet()

getSheet(): Worksheet

Get the worksheet instance.

Returns

Worksheet

The worksheet instance.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const sheet = fWorksheet.getSheet(); console.log(sheet);

getSheetId()

getSheetId(): string

Get the worksheet id.

Returns

string

The id of the worksheet.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const sheetId = fWorksheet.getSheetId(); console.log(sheetId);

getSheetName()

getSheetName(): string

Get the worksheet name.

Returns

string

The name of the worksheet.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const sheetName = fWorksheet.getSheetName(); console.log(sheetName);

getSkeleton()

getSkeleton(): any

Get the skeleton service of the worksheet.

Returns

any

The skeleton of the worksheet.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const skeleton = fWorksheet.getSkeleton(); console.log(skeleton);

getSparklineByCell()

getSparklineByCell(row, col): FSparkline

Parameters

ParameterTypeDescription
rownumberThe row index of the cell, start at 0.
colnumberThe column index of the cell, start at 0.

Returns

FSparkline

Returns the sparkline instance for the next call

Description

Get the sparkline instance of the current cell

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a sparkline in the range A10, with the data source in the range A1:A7. const sourceRanges = [fWorksheet.getRange('A1:A7').getRange()]; const targetRanges = [fWorksheet.getRange('A10').getRange()]; const sparkline = fWorksheet.addSparkline(sourceRanges, targetRanges); console.log('Cell A10: ', fWorksheet.getSparklineByCell(9, 0)); console.log('Cell A11: ', fWorksheet.getSparklineByCell(10, 0));

getSparklineGroupByCell()

getSparklineGroupByCell(row, col): FSparklineGroup

Parameters

ParameterTypeDescription
rownumberThe row index of the cell, start at 0.
colnumberThe column index of the cell, start at 0.

Returns

FSparklineGroup

Returns the sparkline group instance for the next call

Description

Get the sparkline groups instance of the current cell

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a sparkline in the range A10, with the data source in the range A1:A7. const firstSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('A1:A7').getRange()], [fWorksheet.getRange('A10').getRange()] ); // Create a sparkline in the range B10, with the data source in the range B1:B7. const secondSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('B1:B7').getRange()], [fWorksheet.getRange('B10').getRange()] ); console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0)); // Compose the two sparklines into one group after 3 seconds setTimeout(() => { fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()]); console.log('Cell A10: ', fWorksheet.getSparklineGroupByCell(9, 0)); }, 3000);

getTabColor()

getTabColor(): string

Get the tab color of the sheet.

Returns

string

The tab color of the sheet or undefined. The default color is css style property ‘unset’.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // get the tab color of the sheet console.log(fWorkSheet.getTabColor());

getUrl()

getUrl(): string

Create a hyperlink url to this sheet

Returns

string

The url of this sheet

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const url = fWorksheet.getUrl(); console.log(url);

getValidatorStatus()

getValidatorStatus(): Promise<ObjectMatrix<...>>

Returns

Promise<ObjectMatrix<…>>

Deprecated

use getValidatorStatusAsync instead


getValidatorStatusAsync()

getValidatorStatusAsync(): Promise<ObjectMatrix<...>>

Get data validation validator status for current sheet.

Returns

Promise<ObjectMatrix<…>>

matrix of validator status

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const status = await fWorksheet.getValidatorStatusAsync(); console.log(status);

getVisibleRange()

getVisibleRange(): IRange

Return visible range, sum view range of 4 viewports.

Returns

IRange

  • visible range

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const visibleRange = fWorksheet.getVisibleRange(); console.log(visibleRange); console.log(fWorksheet.getRange(visibleRange).getA1Notation());

getWorkbook()

getWorkbook(): Workbook

Get the workbook instance.

Returns

Workbook

The workbook instance.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const workbook = fWorksheet.getWorkbook(); console.log(workbook);

getZoom()

getZoom(): number

Get the zoom ratio of the worksheet.

Returns

number

The zoom ratio of the worksheet.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const zoomRatio = fWorksheet.getZoom(); console.log(zoomRatio);

hasHiddenGridLines()

hasHiddenGridLines(): boolean

Returns true if the sheet’s gridlines are hidden; otherwise returns false. Gridlines are visible by default.

Returns

boolean

True if the sheet’s gridlines are hidden; otherwise false.

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // check if the gridlines are hidden if (fWorkSheet.hasHiddenGridLines()) { console.log('Gridlines are hidden'); }

hideColumn()

hideColumn(column): FWorksheet

Hides the column or columns in the given range.

Parameters

ParameterTypeDescription
columnFRangeThe column range to hide

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Hide columns C, D, E const column1 = fWorksheet.getRange('C:E'); fWorksheet.hideColumn(column1); // Hide column A const column2 = fWorksheet.getRange('A:A'); fWorksheet.hideColumn(column2);

hideColumns()

hideColumns(columnIndex, numColumn?): FWorksheet

Hides one or more consecutive columns starting at the given index. Use 0-index for this method

Parameters

ParameterTypeDescription
columnIndexnumberThe starting index of the columns to hide
numColumn?numberThe number of columns to hide

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Hide columns C, D, E fWorksheet.hideColumns(2, 3); // Hide column A fWorksheet.hideColumns(0, 1);

hideRow()

hideRow(row): FWorksheet

Hides the rows in the given range.

Parameters

ParameterTypeDescription
rowFRangeThe row range to hide.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Hide 3 rows starting from row index 1 (rows 2-4) const row1 = fWorksheet.getRange('2:4'); fWorksheet.hideRow(row1); // Hide single row at index 0 (first row) const row2 = fWorksheet.getRange('1:1'); fWorksheet.hideRow(row2);

hideRows()

hideRows(rowIndex, numRow?): FWorksheet

Hides one or more consecutive rows starting at the given index. Use 0-index for this method

Parameters

ParameterTypeDescription
rowIndexnumberThe starting index of the rows to hide
numRow?numberThe number of rows to hide

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Hide 3 rows starting from row index 1 (rows 2-4) fWorksheet.hideRows(1, 3); // Hide single row at index 0 (first row) fWorksheet.hideRows(0);

hideSheet()

hideSheet(): FWorksheet

Hides this sheet. Has no effect if the sheet is already hidden. If this method is called on the only visible sheet, it throws an exception.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // hide the active sheet fWorkSheet.hideSheet();

insertChart()

insertChart(chartBuildInfo): Promise<FChart>

Adds a new chart to this sheet.

Parameters

ParameterTypeDescription
chartBuildInfoIChartBuilderInfoThe chart builder info.

Returns

Promise<FChart>

  • The new chart.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a column chart with data source A1:D6. // The starting position is upper-left corner of cell B2. const chartInfo = fWorksheet.newChart() .setChartType(univerAPI.Enum.ChartType.Column) .addRange('A1:D6') .setPosition(1, 1, 0, 0) .build(); const fChart = await fWorksheet.insertChart(chartInfo);

insertColumnAfter()

insertColumnAfter(afterPosition): FWorksheet

Inserts a column after the given column position.

Parameters

ParameterTypeDescription
afterPositionnumberThe column after which the new column should be added, starting at 0 for the first column

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert a column after column C fWorksheet.insertColumnAfter(2); // Insert a column after column A fWorksheet.insertColumnAfter(0);

insertColumnBefore()

insertColumnBefore(beforePosition): FWorksheet

Inserts a column before the given column position.

Parameters

ParameterTypeDescription
beforePositionnumberThe column before which the new column should be added, starting at 0 for the first column

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert a column before column C fWorksheet.insertColumnBefore(2); // Insert a column before column A fWorksheet.insertColumnBefore(0);

insertColumns()

insertColumns(columnIndex, numColumns?): FWorksheet

Inserts one or more consecutive blank columns in a sheet starting at the specified location.

Parameters

ParameterTypeDescription
columnIndexnumberThe index indicating where to insert a column, starting at 0 for the first column
numColumns?numberThe number of columns to insert

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert 3 columns before column C fWorksheet.insertColumns(2, 3); // Insert 1 column before column A fWorksheet.insertColumns(0);

insertColumnsAfter()

insertColumnsAfter(afterPosition, howMany): FWorksheet

Inserts a given number of columns after the given column position.

Parameters

ParameterTypeDescription
afterPositionnumberThe column after which the new columns should be added, starting at 0 for the first column
howManynumberThe number of columns to insert

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert 3 columns after column C fWorksheet.insertColumnsAfter(2, 3); // Insert 1 column after column A fWorksheet.insertColumnsAfter(0, 1);

insertColumnsBefore()

insertColumnsBefore(beforePosition, howMany): FWorksheet

Inserts a number of columns before the given column position.

Parameters

ParameterTypeDescription
beforePositionnumberThe column before which the new columns should be added, starting at 0 for the first column
howManynumberThe number of columns to insert

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert 3 columns before column C fWorksheet.insertColumnsBefore(2, 3); // Insert 1 column before column A fWorksheet.insertColumnsBefore(0, 1);

insertDefinedName()

insertDefinedName(name, formulaOrRefString): void

Insert a defined name for worksheet.

Parameters

ParameterTypeDescription
namestringThe name of the defined name to insert
formulaOrRefStringstringThe formula(=sum(A2:b10)) or reference(A1) string of the defined name to insert

Returns

void

Example

// The code below inserts a defined name const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorksheet.insertDefinedName('MyDefinedName', 'Sheet1!A1');

insertImage()

Call Signature

insertImage(url): Promise<boolean>

Insert an image to the sheet

Parameters
ParameterTypeDescription
urlstringThe image url
Returns

Promise<boolean>

true if the image is inserted successfully

Example
// Insert an image to the sheet, default position is A1 const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4'); console.log(result);

Call Signature

insertImage( url, column, row): Promise<boolean>
Parameters
ParameterTypeDescription
urlstringThe image url
columnnumberThe column index to insert the image
rownumberThe row index to insert the image
Returns

Promise<boolean>

True if the image is inserted successfully

Example
// Insert an image to the sheet, position is F6 const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', 5, 5); console.log(result);

Call Signature

insertImage( url, column, row, offsetX, offsetY): Promise<boolean>
Parameters
ParameterTypeDescription
urlstringThe image url
columnnumberThe column index to insert the image
rownumberThe row index to insert the image
offsetXnumberThe column offset, pixel unit
offsetYnumberThe row offset, pixel unit
Returns

Promise<boolean>

True if the image is inserted successfully

Example
// Insert an image to the sheet, position is F6, offset is 10px const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const result = await fWorksheet.insertImage('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', 5, 5, 10, 10); console.log(result);

Call Signature

insertImage(url): Promise<boolean>
Parameters
ParameterType
urlIFBlobSource
Returns

Promise<boolean>

Call Signature

insertImage( url, column, row): Promise<boolean>
Parameters
ParameterType
urlIFBlobSource
columnnumber
rownumber
Returns

Promise<boolean>

Call Signature

insertImage( url, column, row, offsetX, offsetY): Promise<boolean>
Parameters
ParameterType
urlIFBlobSource
columnnumber
rownumber
offsetXnumber
offsetYnumber
Returns

Promise<boolean>

Call Signature

insertImage( url, column, row, offsetX, offsetY): Promise<boolean>
Parameters
ParameterType
urlstring | IFBlobSource
columnnumber
rownumber
offsetXnumber
offsetYnumber
Returns

Promise<boolean>


insertImages()

insertImages(sheetImages): FWorksheet

Insert images to the sheet

Parameters

ParameterTypeDescription
sheetImagesISheetImage[]The images to insert

Returns

FWorksheet

The FWorksheet instance for chaining

Example

// create a new image builder and set image source. // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const image = await fWorksheet.newOverGridImage() .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL) .setColumn(5) .setRow(5) .setWidth(500) .setHeight(300) .buildAsync(); fWorksheet.insertImages([image]); // update the image width to 100px and height to 50px setTimeout(async () => { const imageBuilder = fWorksheet.getImageById(image.drawingId).toBuilder(); const newImage = await imageBuilder.setWidth(100).setHeight(50).buildAsync(); fWorksheet.updateImages([newImage]); }, 4000);

insertRowAfter()

insertRowAfter(afterPosition): FWorksheet

Inserts a row after the given row position.

Parameters

ParameterTypeDescription
afterPositionnumberThe row after which the new row should be added, starting at 0 for the first row.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert a row after the third row fWorksheet.insertRowAfter(2); // Insert a row after the first row fWorksheet.insertRowAfter(0);

insertRowBefore()

insertRowBefore(beforePosition): FWorksheet

Inserts a row before the given row position.

Parameters

ParameterTypeDescription
beforePositionnumberThe row before which the new row should be added, starting at 0 for the first row.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert a row before the third row fWorksheet.insertRowBefore(2); // Insert a row before the first row fWorksheet.insertRowBefore(0);

insertRows()

insertRows(rowIndex, numRows?): FWorksheet

Inserts one or more consecutive blank rows in a sheet starting at the specified location.

Parameters

ParameterTypeDescription
rowIndexnumberThe index indicating where to insert a row, starting at 0 for the first row.
numRows?numberThe number of rows to insert.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert 3 rows before the third row fWorksheet.insertRows(2, 3); // Insert 1 row before the first row fWorksheet.insertRows(0);

insertRowsAfter()

insertRowsAfter(afterPosition, howMany): FWorksheet

Inserts a number of rows after the given row position.

Parameters

ParameterTypeDescription
afterPositionnumberThe row after which the new rows should be added, starting at 0 for the first row.
howManynumberThe number of rows to insert.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert 3 rows after the third row fWorksheet.insertRowsAfter(2, 3); // Insert 1 row after the first row fWorksheet.insertRowsAfter(0, 1);

insertRowsBefore()

insertRowsBefore(beforePosition, howMany): FWorksheet

Inserts a number of rows before the given row position.

Parameters

ParameterTypeDescription
beforePositionnumberThe row before which the new rows should be added, starting at 0 for the first row.
howManynumberThe number of rows to insert.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Insert 3 rows before the third row fWorksheet.insertRowsBefore(2, 3); // Insert 1 row before the first row fWorksheet.insertRowsBefore(0, 1);

isSheetHidden()

isSheetHidden(): boolean

Returns true if the sheet is currently hidden.

Returns

boolean

True if the sheet is hidden; otherwise, false.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheets = fWorkbook.getSheets(); // check if the last sheet is hidden console.log(fWorkSheets[fWorkSheets.length - 1].isSheetHidden());

moveColumns()

moveColumns(columnSpec, destinationIndex): FWorksheet

Moves the columns selected by the given range to the position indicated by the destinationIndex. The columnSpec itself does not have to exactly represent an entire column or group of columns to move—it selects all columns that the range spans.

Parameters

ParameterTypeDescription
columnSpecFRangeA range spanning the columns that should be moved
destinationIndexnumberThe index that the columns should be moved to. Note that this index is based on the coordinates before the columns are moved. Existing data is shifted right to make room for the moved columns while the source columns are removed from the grid. Therefore, the data may end up at a different index than originally specified. Use 0-index for this method

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Move columns C, D, E to column index 2 (columns B, C, D) const columnSpec1 = fWorksheet.getRange('C:E'); fWorksheet.moveColumns(columnSpec1, 1); // Move column F to column index 0 (column A) const columnSpec2 = fWorksheet.getRange('F:F'); fWorksheet.moveColumns(columnSpec2, 0);

moveConditionalFormattingRule()

moveConditionalFormattingRule( cfId, toCfId, type?): FWorksheet

Modify the priority of the conditional format

Parameters

ParameterTypeDescription
cfIdstringThe conditional formatting rule id to move
toCfIdstringTarget rule
type?IAnchorAfter the default move to the destination rule, if type = before moves to the front, the default value is after

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Memberof

FWorksheetConditionalFormattingMixin

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const rules = fWorksheet.getConditionalFormattingRules(); // Move the third rule before the first rule const rule = rules[2]; const targetRule = rules[0]; fWorksheet.moveConditionalFormattingRule(rule?.cfId, targetRule?.cfId, 'before');

moveRows()

moveRows(rowSpec, destinationIndex): FWorksheet

Moves the rows selected by the given range to the position indicated by the destinationIndex. The rowSpec itself does not have to exactly represent an entire row or group of rows to move—it selects all rows that the range spans.

Parameters

ParameterTypeDescription
rowSpecFRangeA range spanning the rows that should be moved.
destinationIndexnumberThe index that the rows should be moved to. Note that this index is based on the coordinates before the rows are moved. Existing data is shifted down to make room for the moved rows while the source rows are removed from the grid. Therefore, the data may end up at a different index than originally specified. Use 0-index for this method.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Move 3 rows at row index 2 (rows 3-5) to row index 0 const rowSpec1 = fWorksheet.getRange('3:5'); fWorksheet.moveRows(rowSpec1, 0); // Move 1 row at row index 0 (first row) to row index 2 const rowSpec2 = fWorksheet.getRange('1:1'); fWorksheet.moveRows(rowSpec2, 2);

newChart()

newChart(fChart?): FChartBuilderBase

Returns a builder to create a new chart for this sheet.The builder will not automatically create the chart. You must call build() on the returned builder to create the chart by calling insertChart(chartBuilder).

Parameters

ParameterTypeDescription
fChart?FChartThe chart to update.

Returns

FChartBuilderBase

  • a new chart builder

Description

If the fChart is provided, the builder will be initialized with the existing chart’s data.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a column chart with data source A1:D6. // The starting position is upper-left corner of cell B2. // The width of the chart is 600 and the height is 400. const chartInfo = fWorksheet.newChart() .setChartType(univerAPI.Enum.ChartType.Column) .addRange('A1:D6') .setPosition(1, 1, 0, 0) .setWidth(600) .setHeight(400) .build(); await fWorksheet.insertChart(chartInfo);

newConditionalFormattingRule()

newConditionalFormattingRule(): FConditionalFormattingBuilder

Creates a constructor for conditional formatting

Returns

FConditionalFormattingBuilder

The conditional formatting builder

Memberof

IFWorksheetConditionalFormattingMixin

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a conditional formatting rule that bolds the text for cells with not empty content in the range A1:T100. const fRange = fWorksheet.getRange('A1:T100'); const rule = fWorksheet.newConditionalFormattingRule() .whenCellNotEmpty() .setRanges([fRange.getRange()]) .setItalic(true) .setBackground('red') .setFontColor('green') .build(); fWorksheet.addConditionalFormattingRule(rule);

newOverGridImage()

newOverGridImage(): FOverGridImageBuilder

Create a new over grid image builder.

Returns

FOverGridImageBuilder

The FOverGridImageBuilder instance

Example

// create a new image builder and set image source. // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const image = await fWorksheet.newOverGridImage() .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL) .setColumn(5) .setRow(5) .setWidth(500) .setHeight(300) .buildAsync(); fWorksheet.insertImages([image]);

onBeforeCellDataChange()

onBeforeCellDataChange(callback): IDisposable

Parameters

ParameterType
callback(cellValue) => void

Returns

IDisposable

Deprecated

use univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params) => {}) instead


onCellDataChange()

onCellDataChange(callback): IDisposable

Parameters

ParameterType
callback(cellValue) => void

Returns

IDisposable

Deprecated

use univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params) => {}) instead


onImageChanged()

onImageChanged(callback): IDisposable

Hook when a image is changed.

Parameters

ParameterTypeDescription
callback(images) => voidThe callback function when a image is changed.

Returns

IDisposable

Deprecated

use univerAPI.addEvent(univerAPI.Event.OverGridImageChanged, (params) => {}) as instead


onImageDeleted()

onImageDeleted(callback): IDisposable

Hook when a image is deleted.

Parameters

ParameterTypeDescription
callback(images) => voidThe callback function when a image is deleted.

Returns

IDisposable

Deprecated

use univerAPI.addEvent(univerAPI.Event.OverGridImageRemoved, (params) => {}) as instead


onImageInserted()

onImageInserted(callback): IDisposable

Hook when a image is inserted.

Parameters

ParameterTypeDescription
callback(images) => voidThe callback function when a image is inserted.

Returns

IDisposable

Deprecated

use univerAPI.addEvent(univerAPI.Event.OverGridImageInserted, (params) => {}) as instead


onScroll()

onScroll(callback): IDisposable

Parameters

ParameterType
callback(params) => void

Returns

IDisposable

Deprecated

use univerAPI.addEvent(univerAPI.Event.Scroll, (params) => {}) instead


refreshCanvas()

refreshCanvas(): FWorksheet

Refresh the canvas.

Returns

FWorksheet

The FWorksheet instance for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); fWorksheet.refreshCanvas();

registerChartTheme()

registerChartTheme(themeName, theme): void

Univer chart is base on echarts, you can register your own theme by echart theme builder.

Parameters

ParameterTypeDescription
themeNamestringThe name of the theme.
themeIEchartThemeThe theme object.

Returns

void

Description

The theme object should be a valid echarts theme object.The online builder is available at https://echarts.apache.org/zh/theme-builder.html

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // register your theme const theme = { // your theme object 'version': 1, 'themeName': 'essos', 'theme': { // ... Some code is omitted for brevity color: [ '#893448', '#d95850', '#eb8146', '#ffb248', '#f2d643', '#ebdba4' ], // ... Some code is omitted for brevity visualMapColor: [ '#893448', '#d95850', '#eb8146', '#ffb248', '#f2d643', 'rgb(247,238,173)' ], // ... Some code is omitted for brevity 'axes': [] // ... Some code is omitted for brevity } }; fWorksheet.registerChartTheme('myTheme', theme); // use your theme for chart const chartInfo = fWorksheet.newChart() .asLineChart() .addRange('A1:D6') .setPosition(1, 1, 0, 0) .setTheme('myTheme') .build(); await fWorksheet.insertChart(chartInfo);

removeChart()

removeChart(chart): Promise<boolean>

Removes a chart from the parent sheet.

Parameters

ParameterTypeDescription
chartFChartThe chart to remove.

Returns

Promise<boolean>

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a column chart with data source A1:D6. // The starting position is upper-left corner of cell B2. const chartInfo = fWorksheet.newChart() .setChartType(univerAPI.Enum.ChartType.Column) .addRange('A1:D6') .setPosition(1, 1, 0, 0) .build(); await fWorksheet.insertChart(chartInfo); // Get all charts on the active sheet. const charts = fWorksheet.getCharts(); // Remove the first chart after 3 seconds. setTimeout(async () => { await fWorksheet.removeChart(charts[0]); console.log(fWorksheet.getCharts()); }, 3000);

scrollToCell()

scrollToCell(row, column): FWorksheet

Scroll spreadsheet(viewMain) to cell position. Make the cell at topleft of current viewport. Based on the limitations of viewport and the number of rows and columns, you can only scroll to the maximum scrollable range.

Parameters

ParameterTypeDescription
rownumberCell row index
columnnumberCell column index

Returns

FWorksheet

  • The FWorksheet instance for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Scroll to cell D10 const fRange = fWorksheet.getRange('D10'); const row = fRange.getRow(); const column = fRange.getColumn(); fWorksheet.scrollToCell(row, column);

setActiveRange()

setActiveRange(range): FWorksheet

Sets the active selection region for this sheet.

Parameters

ParameterTypeDescription
rangeFRangeThe range to set as the active selection

Returns

FWorksheet

This sheet, for chaining

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorkSheet.setActiveRange(fWorkSheet.getRange('A10:B10'));

setColumnAutoWidth()

setColumnAutoWidth(columnPosition, numColumn): FWorksheet

Sets the width of all columns starting at the given column position to fit their contents.

Parameters

ParameterTypeDescription
columnPositionnumberThe position of the first column to resize. index starts at 0.
numColumnnumberThe number of columns to auto-resize.

Returns

FWorksheet

  • The FWorksheet instance for chaining.

Deprecated

use autoResizeColumns instead


setColumnCustom()

setColumnCustom(custom): FWorksheet

Set custom properties for given columns.

Parameters

ParameterTypeDescription
customIObjectArrayPrimitiveType<CustomData>The custom properties to set

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorkSheet.setColumnCustom({ 0: { key: 'value' } });

setColumnCustomMetadata()

setColumnCustomMetadata(index, custom): FWorksheet

Set custom metadata of column

Parameters

ParameterTypeDescription
indexnumbercolumn index
customCustomDatacustom metadata

Returns

FWorksheet

Current worksheet, for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); fWorkSheet.setColumnCustomMetadata(0, { key: 'value' });

setColumnDefaultStyle()

setColumnDefaultStyle(index, style): FWorksheet

Set the default style of the worksheet row

Parameters

ParameterTypeDescription
indexnumberThe row index
stylestring | Nullable<…>The style name or style data

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); fWorksheet.setColumnDefaultStyle(0, 'default'); // or // fWorksheet.setColumnDefaultStyle(0, {fs: 12, ff: 'Arial'});

setColumnHeaderHeight()

setColumnHeaderHeight(height): FWorksheet

Set column height for column header.

Parameters

ParameterTypeDescription
heightnumberThe height to set.

Returns

FWorksheet

  • The FWorksheet instance for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); fWorksheet.setColumnHeaderHeight(100);

setColumnWidth()

setColumnWidth(columnPosition, width): FWorksheet

Sets the width of the given column in pixels.

Parameters

ParameterTypeDescription
columnPositionnumberThe position of the given column to set
widthnumberThe width in pixels to set it to

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Set width of column B to 100 pixels fWorksheet.setColumnWidth(1, 100);

setColumnWidths()

setColumnWidths( startColumn, numColumn, width): FWorksheet

Sets the width of the given columns in pixels.

Parameters

ParameterTypeDescription
startColumnnumberThe starting column position to change
numColumnnumberThe number of columns to change
widthnumberThe width in pixels to set it to

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Set width of columns B-D (index 1-3) to 100 pixels fWorksheet.setColumnWidths(1, 3, 100);

setConditionalFormattingRule()

setConditionalFormattingRule(cfId, rule): FWorksheet

Set the conditional format according to cfId

Parameters

ParameterTypeDescription
cfIdstringThe conditional formatting rule id to set
ruleIConditionFormattingRuleThe conditional formatting rule to set

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Memberof

IFWorksheetConditionalFormattingMixin

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const fRange = fWorksheet.getRange('A1:T100'); const rule = fWorksheet.newConditionalFormattingRule() .whenCellNotEmpty() .setRanges([fRange.getRange()]) .setItalic(true) .setBackground('red') .setFontColor('green') .build(); fWorksheet.addConditionalFormattingRule(rule); // Modify the first rule to apply to a new range const rules = fWorksheet.getConditionalFormattingRules(); const newRuleRange = fWorksheet.getRange('A1:D10'); fWorksheet.setConditionalFormattingRule(rules[0]?.cfId, { ...rules[0], ranges: [newRuleRange.getRange()] });

setCustomMetadata()

setCustomMetadata(custom): FWorksheet

Set custom metadata of worksheet

Parameters

ParameterTypeDescription
customCustomDatacustom metadata

Returns

FWorksheet

Current worksheet, for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); fWorkSheet.setCustomMetadata({ key: 'value' });

setDefaultStyle()

setDefaultStyle(style): FWorksheet

Set the default style of the worksheet

Parameters

ParameterTypeDescription
stylestring | Nullable<…>The style to set

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorksheet.setDefaultStyle('default'); // or // fWorksheet.setDefaultStyle({fs: 12, ff: 'Arial'});

setFreeze()

setFreeze(freeze): FWorksheet

Sets the frozen state of the current sheet.

Parameters

ParameterTypeDescription
freezeIFreezethe scrolling viewport start range and count of freezed rows and columns. that means if you want to freeze the first 3 rows and 2 columns, you should set freeze as { startRow: 3, startColumn: 2, xSplit: 2, ySplit: 3 }

Returns

FWorksheet

This worksheet instance for chaining

Deprecated

use setFrozenRows and setFrozenColumns instead.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Freeze first 3 rows and 2 columns fWorksheet.setFreeze({ startRow: 3, startColumn: 2, xSplit: 2, ySplit: 3 });

setFrozenColumns()

Call Signature

setFrozenColumns(columns): FWorksheet

Set the number of frozen columns.

Parameters
ParameterTypeDescription
columnsnumberThe number of columns to freeze. To unfreeze all columns, set this value to 0.
Returns

FWorksheet

This FWorksheet instance.

Example
const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // freeze the first 3 columns. fWorkSheet.setFrozenColumns(3);

Call Signature

setFrozenColumns(startColumn, endColumn): FWorksheet

Set freeze column, then the range from startColumn to endColumn will be fixed. e.g. setFrozenColumns(0, 2) will fix the column range from 0 to 2. e.g. setFrozenColumns(2, 3) will fix the column range from 2 to 3, And column from 0 to 1 will be invisible.

Parameters
ParameterTypeDescription
startColumnnumberThe start column of the range to freeze
endColumnnumberThe end column of the range to freeze
Returns

FWorksheet

This FWorksheet instance.

Example
const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // freeze the column B and C, and column A will be invisible. fWorkSheet.setFrozenColumns(1, 2);

setFrozenRows()

Call Signature

setFrozenRows(rows): FWorksheet

Set the number of frozen rows.

Parameters
ParameterTypeDescription
rowsnumberThe number of rows to freeze. To unfreeze all rows, set this value to 0.
Returns

FWorksheet

This FWorksheet instance.

Example
const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // freeze the first 3 rows. fWorkSheet.setFrozenRows(3);

Call Signature

setFrozenRows(startRow, endRow): FWorksheet

Set freeze row, then the range from startRow to endRow will be fixed. e.g. setFrozenRows(0, 2) will fix the row range from 0 to 2. e.g. setFrozenRows(2, 3) will fix the row range from 2 to 3, And row from 0 to 1 will be invisible.

Parameters
ParameterTypeDescription
startRownumberThe start row of the range to freeze
endRownumberThe end row of the range to freeze
Returns

FWorksheet

This FWorksheet instance.

Example
const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // freeze the second and third rows, and the first row will be invisible. fWorkSheet.setFrozenRows(1, 2);

setGridLinesColor()

setGridLinesColor(color): FWorksheet

Set the color of the gridlines in the sheet.

Parameters

ParameterTypeDescription
colorstringThe color to set for the gridlines.Undefined or null to reset to the default color.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // set the gridlines color to red fWorkSheet.setGridLinesColor('#ff0000');

setHiddenGridlines()

setHiddenGridlines(hidden): FWorksheet

Hides or reveals the sheet gridlines.

Parameters

ParameterTypeDescription
hiddenbooleanIf true, hide gridlines in this sheet; otherwise show the gridlines.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); // hide the gridlines fWorkSheet.setHiddenGridlines(true);

setName()

setName(name): FWorksheet

Sets the sheet name.

Parameters

ParameterTypeDescription
namestringThe new name for the sheet.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // set the sheet name to 'Sheet1' fWorkSheet.setName('NewSheet1');

setRangesAutoHeight()

setRangesAutoHeight(ranges): FWorksheet

Sets the height of the given ranges to auto.

Parameters

ParameterTypeDescription
rangesIRange[]The ranges to change

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); const ranges = [ { startRow: 1, endRow: 10, startColumn: 0, endColumn: 10 }, { startRow: 11, endRow: 20, startColumn: 0, endColumn: 10 }, ] fWorksheet.setRangesAutoHeight(ranges);

setRowAutoHeight()

setRowAutoHeight(startRow, numRows): FWorksheet

Sets the height of the given rows to auto.

Parameters

ParameterTypeDescription
startRownumberThe starting row position to change
numRowsnumberThe number of rows to change

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorksheet.setRowAutoHeight(1, 10);

setRowCustom()

setRowCustom(custom): FWorksheet

Set custom properties for given rows.

Parameters

ParameterTypeDescription
customIObjectArrayPrimitiveType<CustomData>The custom properties to set

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorkSheet.setRowCustom({ 0: { key: 'value' } });

setRowCustomMetadata()

setRowCustomMetadata(index, custom): FWorksheet

Set custom metadata of row

Parameters

ParameterTypeDescription
indexnumberrow index
customCustomDatacustom metadata

Returns

FWorksheet

Current worksheet, for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); fWorkSheet.setRowCustomMetadata(0, { key: 'value' });

setRowDefaultStyle()

setRowDefaultStyle(index, style): FWorksheet

Set the default style of the worksheet column

Parameters

ParameterTypeDescription
indexnumberThe column index
stylestring | Nullable<…>The style name or style data

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); fWorksheet.setRowDefaultStyle(0, 'default'); // or // fWorksheet.setRowDefaultStyle(0, {fs: 12, ff: 'Arial'});

setRowHeaderWidth()

setRowHeaderWidth(width): FWorksheet

Set column height for column header.

Parameters

ParameterTypeDescription
widthnumberThe width to set.

Returns

FWorksheet

  • The FWorksheet instance for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); fWorksheet.setRowHeaderWidth(100);

setRowHeight()

setRowHeight(rowPosition, height): FWorksheet

Sets the row height of the given row in pixels. By default, rows grow to fit cell contents. If you want to force rows to a specified height, use setRowHeightsForced(startRow, numRows, height).

Parameters

ParameterTypeDescription
rowPositionnumberThe row position to change.
heightnumberThe height in pixels to set it to.

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Set the height of the second row to 30 pixels fWorksheet.setRowHeight(1, 30); // Set the height of the first row to 20 pixels fWorksheet.setRowHeight(0, 20);

setRowHeights()

setRowHeights( startRow, numRows, height): FWorksheet

Sets the height of the given rows in pixels. By default, rows grow to fit cell contents. If you want to force rows to a specified height, use setRowHeightsForced(startRow, numRows, height).

Parameters

ParameterTypeDescription
startRownumberThe starting row position to change
numRowsnumberThe number of rows to change
heightnumberThe height in pixels to set it to

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorksheet.setRowHeights(1, 10, 30);

setRowHeightsForced()

setRowHeightsForced( startRow, numRows, height): FWorksheet

Sets the height of the given rows in pixels. By default, rows grow to fit cell contents. When you use setRowHeightsForced, rows are forced to the specified height even if the cell contents are taller than the row height.

Parameters

ParameterTypeDescription
startRownumberThe starting row position to change
numRowsnumberThe number of rows to change
heightnumberThe height in pixels to set it to

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); fWorksheet.setRowHeightsForced(1, 10, 30);

setTabColor()

setTabColor(color): FWorksheet

Sets the sheet tab color.

Parameters

ParameterTypeDescription
colorstringA color code in CSS notation (like ‘#ffffff’ or ‘white’), or null to reset the tab color.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheet = fWorkbook.getActiveSheet(); // set the tab color to red fWorkSheet.setTabColor('#ff0000');

showColumns()

showColumns(columnIndex, numColumns?): FWorksheet

Show one or more consecutive columns starting at the given index. Use 0-index for this method

Parameters

ParameterTypeDescription
columnIndexnumberThe starting index of the columns to unhide
numColumns?numberThe number of columns to unhide

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Unhide columns C, D, E fWorksheet.showColumns(2, 3); // Unhide column A fWorksheet.showColumns(0, 1);

showRows()

showRows(rowIndex, numRows?): FWorksheet

Scrolling sheet to make specific rows visible.

Parameters

ParameterTypeDescription
rowIndexnumberThe starting index of the rows
numRows?numberThe number of rows

Returns

FWorksheet

This worksheet instance for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Show 3 rows starting from row index 1 (rows 2-4) fWorksheet.showRows(1, 3); // Show single row at index 0 (first row) fWorksheet.showRows(0);

showSheet()

showSheet(): FWorksheet

Shows this sheet. Has no effect if the sheet is already visible.

Returns

FWorksheet

Returns the current worksheet instance for method chaining

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorkSheets = fWorkbook.getSheets(); // show the last sheet fWorkSheets[fWorkSheets.length - 1].showSheet();

sort()

sort(colIndex, asc?): FWorksheet

Sort the worksheet by the specified column.

Parameters

ParameterTypeDescription
colIndexnumberThe column index to sort by.
asc?booleanThe sort order. true for ascending, false for descending. The column A index is 0.

Returns

FWorksheet

The worksheet itself for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Sorts the worksheet by the column A in ascending order. fWorksheet.sort(0); // Sorts the worksheet by the column A in descending order. fWorksheet.sort(0, false);

unComposeSparkline()

unComposeSparkline(ranges): void

Parameters

ParameterTypeDescription
rangesIRange[]The selection range to be ungrouped

Returns

void

Description

Split the sparkline group within the current selection

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a sparkline in the range A10, with the data source in the range A1:A7. const firstSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('A1:A7').getRange()], [fWorksheet.getRange('A10').getRange()] ); // Create a sparkline in the range B10, with the data source in the range B1:B7. const secondSparkline = fWorksheet.addSparkline( [fWorksheet.getRange('B1:B7').getRange()], [fWorksheet.getRange('B10').getRange()] ); // Compose the two sparklines into one group fWorksheet.composeSparkline([fWorksheet.getRange('A10:B10').getRange()]); console.log('debugger', fWorksheet.getAllSubSparkline().size); // 1 // Uncompose the sparkline group after 3 seconds setTimeout(() => { fWorksheet.unComposeSparkline([fWorksheet.getRange('A10:B10').getRange()]); console.log('debugger', fWorksheet.getAllSubSparkline().size); // 2 }, 3000);

unhideColumn()

unhideColumn(column): FWorksheet

Show the column in the given range.

Parameters

ParameterTypeDescription
columnFRangeThe range to unhide, if hidden

Returns

FWorksheet

This sheet, for chaining

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Unhide columns C, D, E const column1 = fWorksheet.getRange('C:E'); fWorksheet.unhideColumn(column1); // Unhide column A const column2 = fWorksheet.getRange('A:A'); fWorksheet.unhideColumn(column2);

unhideRow()

unhideRow(row): FWorksheet

Make the row in the given range visible.

Parameters

ParameterTypeDescription
rowFRangeThe range to unhide, if hidden.

Returns

FWorksheet

This sheet, for chaining.

Example

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet(); // Unhide 3 rows starting from row index 1 (rows 2-4) const row1 = fWorksheet.getRange('2:4'); fWorksheet.unhideRow(row1); // Unhide single row at index 0 (first row) const row2 = fWorksheet.getRange('1:1'); fWorksheet.unhideRow(row2);

updateChart()

updateChart(chartBuildInfo): void

Updates the chart on this sheet. This api can not update source range, please use FChart.updateRange.

Parameters

ParameterTypeDescription
chartBuildInfoIChartBuilderInfoThe chart builder info.

Returns

void

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Create a column chart with data source A1:D6. // The starting position is upper-left corner of cell B2. const chartInfo = fWorksheet.newChart() .setChartType(univerAPI.Enum.ChartType.Column) .addRange('A1:D6') .setPosition(1, 1, 0, 0) .build(); await fWorksheet.insertChart(chartInfo); // Get all charts on the active sheet. const charts = fWorksheet.getCharts(); // Update the first chart after 3 seconds. setTimeout(() => { const newChartInfo = fWorksheet.newChart(charts[0]) .asLineChart() .setOptions('legend.position', univerAPI.Enum.LegendPositionEnum.Right) .build(); fWorksheet.updateChart(newChartInfo); }, 3000);

updateImages()

updateImages(sheetImages): FWorksheet

Update images to the sheet

Parameters

ParameterTypeDescription
sheetImagesISheetImage[]The images to update

Returns

FWorksheet

The FWorksheet instance for chaining

Example

// create a new image builder and set image source. // then build `ISheetImage` and insert it into the sheet, position is start from F6 cell, width is 500px, height is 300px const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); const image = await fWorksheet.newOverGridImage() .setSource('https://avatars.githubusercontent.com/u/61444807?s=48&v=4', univerAPI.Enum.ImageSourceType.URL) .setColumn(5) .setRow(5) .setWidth(500) .setHeight(300) .buildAsync(); fWorksheet.insertImages([image]); // update the image width to 100px and height to 50px setTimeout(async () => { const imageBuilder = fWorksheet.getImageById(image.drawingId).toBuilder(); const newImage = await imageBuilder.setWidth(100).setHeight(50).buildAsync(); fWorksheet.updateImages([newImage]); }, 4000);

zoom()

zoom(zoomRatio): FWorksheet

Set zoom ratio of the worksheet.

Parameters

ParameterTypeDescription
zoomRationumberThe zoom ratio to set.It should be in the range of 0.1 to 4.0.

Returns

FWorksheet

The FWorksheet instance for chaining.

Example

const fWorkbook = univerAPI.getActiveWorkbook(); const fWorksheet = fWorkbook.getActiveSheet(); // Set zoom ratio to 200% fWorksheet.zoom(2); const zoomRatio = fWorksheet.getZoom(); console.log(zoomRatio); // 2