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
Property | Type | Description |
---|---|---|
( |
Sets the active selection region for this sheet. Example
|
Methods
activate()
activate(): FWorksheet
Activates this sheet. Does not alter the sheet itself, only the parent’s notion of the active sheet.
Returns
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
Parameter | Type | Description |
---|---|---|
rule | IConditionFormattingRule | The conditional formatting rule to add |
Returns
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
Parameter | Type | Description |
---|---|---|
column | number | The column index to add the float dom. |
layer | Partial <IFICanvasFloatDom > | The float dom layer configuration. |
domPos | IDOMAnchor | The anchor configuration of the float dom. |
id ? | string | The 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
Parameter | Type | Description |
---|---|---|
layer | IFICanvasFloatDom | The float dom layer configuration. |
id ? | string | The 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
Parameter | Type | Description |
---|---|---|
range | FRange | The range to add the float dom. |
layer | Partial <IFICanvasFloatDom > | The float dom layer configuration. |
domLayout | IDOMAnchor | The anchor configuration of the float dom. |
id ? | string | The 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
Parameter | Type | Description |
---|---|---|
sourceRanges | IRange [] | Source data location for sparklines |
targetRanges | IRange [] | Where to place sparklines |
type | LINE_CHART | The type of Sparklines |
Returns
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
Parameter | Type | Description |
---|---|---|
rowContents | CellValue [] | An array of values for the new row. |
Returns
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
Parameter | Type | Description |
---|---|---|
rowPosition | number | The row position to change. |
auto ? | BooleanNumber | Whether to auto fit the row height. |
Returns
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
Parameter | Type | Description |
---|---|---|
columnPosition | number | The position of the given column to resize. index starts at 0. |
Returns
- 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
Parameter | Type | Description |
---|---|---|
startColumn | number | The position of the first column to resize. index starts at 0. |
numColumns | number | The number of columns to auto-resize. |
Returns
- 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
Parameter | Type | Description |
---|---|---|
startRow | number | The position of the first row to resize. index starts at 0. |
numRows | number | The number of rows to auto-resize. |
Returns
- 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
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
Parameter | Type | Description |
---|---|---|
options ? | IFacadeClearOptions | Options for clearing the sheet. If not provided, the contents and formatting are cleared both. |
Returns
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
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
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
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
Parameter | Type | Description |
---|---|---|
ranges | IRange [] | 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
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
Parameter | Type | Description |
---|---|---|
cfg | IColumnsHeaderCfgParam | The 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
Parameter | Type | Description |
---|---|---|
cfg | IRowsHeaderCfgParam | The 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
Parameter | Type | Description |
---|---|---|
columnPosition | number | The position of the column, starting at 0 for the first column |
Returns
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
Parameter | Type | Description |
---|---|---|
columnPosition | number | The position of the first column to delete, starting at 0 for the first column |
howMany | number | The number of columns to delete |
Returns
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
Parameter | Type | Description |
---|---|---|
cfId | string | The conditional formatting rule id to delete |
Returns
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
Parameter | Type | Description |
---|---|---|
sheetImages | FOverGridImage [] | The images to delete |
Returns
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
Parameter | Type | Description |
---|---|---|
rowPosition | number | The position of the row, starting at 0 for the first row. |
Returns
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
Parameter | Type | Description |
---|---|---|
rowPosition | number | The position of the first row to delete, starting at 0 for the first row. |
howMany | number | The number of rows to delete. |
Returns
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
Parameter | Type | Description |
---|---|---|
other | FWorksheet | the 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
The active cell
Example
const fWorkSheet = univerAPI.getActiveWorkbook().getActiveSheet();
console.log(fWorkSheet.getActiveCell().getA1Notation());
getActiveImages()
getActiveImages(): FOverGridImage[]
Get the current selected images.
Returns
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
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
Parameter | Type | Description |
---|---|---|
row | number | The row index |
column | number | The column index |
Returns
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
Parameter | Type | Description |
---|---|---|
index | number | column index |
Returns
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
Parameter | Type | Description |
---|---|---|
index | number | The column index |
keepRaw ? | boolean | If 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
Parameter | Type | Description |
---|---|---|
columnPosition | number | The 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
Parameter | Type | Description |
---|---|---|
commentId | string | comment 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
getComments()
getComments(): FThreadComment[]
Get all comments in the current sheet
Returns
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
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
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
Parameter | Type | Description |
---|---|---|
ruleId | string | the 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
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
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
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
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
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
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
Parameter | Type | Description |
---|---|---|
id | string | The drawing id of the image |
Returns
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
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
Parameter | Type | Description |
---|---|---|
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 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
Parameter | Type | Description |
---|---|---|
row | number | The row index of the cell. |
column | number | The column index of the cell. |
Returns
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
Parameter | Type | Description |
---|---|---|
row | number | The starting row index of the range. |
column | number | The starting column index of the range. |
numRows | number | The number of rows in the range. |
Returns
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
Parameter | Type | Description |
---|---|---|
row | number | The starting row index of the range. |
column | number | The starting column index of the range. |
numRows | number | The number of rows in the range. |
numColumns | number | The number of columns in the range. |
Returns
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
Parameter | Type | Description |
---|---|---|
a1Notation | string | A string representing a range in A1 notation. |
Returns
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
Parameter | Type | Description |
---|---|---|
range | IRange | The range specification. |
Returns
A Range object representing the specified range.
getRowCustomMetadata()
getRowCustomMetadata(index): CustomData
Get custom metadata of row
Parameters
Parameter | Type | Description |
---|---|---|
index | number | row index |
Returns
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
Parameter | Type | Description |
---|---|---|
index | number | The row index |
keepRaw ? | boolean | If 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
Parameter | Type | Description |
---|---|---|
rowPosition | number | The 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
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
Parameter | Type | Description |
---|---|---|
row | number | The row index of the cell, start at 0. |
col | number | The column index of the cell, start at 0. |
Returns
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
Parameter | Type | Description |
---|---|---|
row | number | The row index of the cell, start at 0. |
col | number | The column index of the cell, start at 0. |
Returns
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
- 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
Parameter | Type | Description |
---|---|---|
column | FRange | The column range to hide |
Returns
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
Parameter | Type | Description |
---|---|---|
columnIndex | number | The starting index of the columns to hide |
numColumn ? | number | The number of columns to hide |
Returns
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
Parameter | Type | Description |
---|---|---|
row | FRange | The row range to hide. |
Returns
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
Parameter | Type | Description |
---|---|---|
rowIndex | number | The starting index of the rows to hide |
numRow ? | number | The number of rows to hide |
Returns
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
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
Parameter | Type | Description |
---|---|---|
chartBuildInfo | IChartBuilderInfo | The 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
Parameter | Type | Description |
---|---|---|
afterPosition | number | The column after which the new column should be added, starting at 0 for the first column |
Returns
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
Parameter | Type | Description |
---|---|---|
beforePosition | number | The column before which the new column should be added, starting at 0 for the first column |
Returns
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
Parameter | Type | Description |
---|---|---|
columnIndex | number | The index indicating where to insert a column, starting at 0 for the first column |
numColumns ? | number | The number of columns to insert |
Returns
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
Parameter | Type | Description |
---|---|---|
afterPosition | number | The column after which the new columns should be added, starting at 0 for the first column |
howMany | number | The number of columns to insert |
Returns
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
Parameter | Type | Description |
---|---|---|
beforePosition | number | The column before which the new columns should be added, starting at 0 for the first column |
howMany | number | The number of columns to insert |
Returns
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
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
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
Parameter | Type | Description |
---|---|---|
url | string | The 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
Parameter | Type | Description |
---|---|---|
url | string | The image url |
column | number | The column index to insert the image |
row | number | The 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
Parameter | Type | Description |
---|---|---|
url | string | The image url |
column | number | The column index to insert the image |
row | number | The row index to insert the image |
offsetX | number | The column offset, pixel unit |
offsetY | number | The 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
Parameter | Type |
---|---|
url | IFBlobSource |
Returns
Promise
<boolean
>
Call Signature
insertImage(
url,
column,
row): Promise<boolean>
Parameters
Parameter | Type |
---|---|
url | IFBlobSource |
column | number |
row | number |
Returns
Promise
<boolean
>
Call Signature
insertImage(
url,
column,
row,
offsetX,
offsetY): Promise<boolean>
Parameters
Parameter | Type |
---|---|
url | IFBlobSource |
column | number |
row | number |
offsetX | number |
offsetY | number |
Returns
Promise
<boolean
>
Call Signature
insertImage(
url,
column,
row,
offsetX,
offsetY): Promise<boolean>
Parameters
Parameter | Type |
---|---|
url | string | IFBlobSource |
column | number |
row | number |
offsetX | number |
offsetY | number |
Returns
Promise
<boolean
>
insertImages()
insertImages(sheetImages): FWorksheet
Insert images to the sheet
Parameters
Parameter | Type | Description |
---|---|---|
sheetImages | ISheetImage [] | The images to insert |
Returns
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
Parameter | Type | Description |
---|---|---|
afterPosition | number | The row after which the new row should be added, starting at 0 for the first row. |
Returns
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
Parameter | Type | Description |
---|---|---|
beforePosition | number | The row before which the new row should be added, starting at 0 for the first row. |
Returns
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
Parameter | Type | Description |
---|---|---|
rowIndex | number | The index indicating where to insert a row, starting at 0 for the first row. |
numRows ? | number | The number of rows to insert. |
Returns
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
Parameter | Type | Description |
---|---|---|
afterPosition | number | The row after which the new rows should be added, starting at 0 for the first row. |
howMany | number | The number of rows to insert. |
Returns
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
Parameter | Type | Description |
---|---|---|
beforePosition | number | The row before which the new rows should be added, starting at 0 for the first row. |
howMany | number | The number of rows to insert. |
Returns
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
Parameter | Type | Description |
---|---|---|
columnSpec | FRange | A range spanning the columns that should be moved |
destinationIndex | number | The 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
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
Parameter | Type | Description |
---|---|---|
cfId | string | The conditional formatting rule id to move |
toCfId | string | Target rule |
type ? | IAnchor | After the default move to the destination rule, if type = before moves to the front, the default value is after |
Returns
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
Parameter | Type | Description |
---|---|---|
rowSpec | FRange | A range spanning the rows that should be moved. |
destinationIndex | number | The 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
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
Parameter | Type | Description |
---|---|---|
fChart ? | FChart | The 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
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
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
Parameter | Type |
---|---|
callback | (cellValue ) => void |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params) => {})
instead
onCellDataChange()
onCellDataChange(callback): IDisposable
Parameters
Parameter | Type |
---|---|
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
Parameter | Type | Description |
---|---|---|
callback | (images ) => void | The 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
Parameter | Type | Description |
---|---|---|
callback | (images ) => void | The 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
Parameter | Type | Description |
---|---|---|
callback | (images ) => void | The callback function when a image is inserted. |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.OverGridImageInserted, (params) => {})
as instead
onScroll()
onScroll(callback): IDisposable
Parameters
Parameter | Type |
---|---|
callback | (params ) => void |
Returns
IDisposable
Deprecated
use univerAPI.addEvent(univerAPI.Event.Scroll, (params) => {})
instead
refreshCanvas()
refreshCanvas(): FWorksheet
Refresh the canvas.
Returns
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
Parameter | Type | Description |
---|---|---|
themeName | string | The name of the theme. |
theme | IEchartTheme | The 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
Parameter | Type | Description |
---|---|---|
chart | FChart | The 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
Parameter | Type | Description |
---|---|---|
row | number | Cell row index |
column | number | Cell column index |
Returns
- 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
Parameter | Type | Description |
---|---|---|
range | FRange | The range to set as the active selection |
Returns
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
Parameter | Type | Description |
---|---|---|
columnPosition | number | The position of the first column to resize. index starts at 0. |
numColumn | number | The number of columns to auto-resize. |
Returns
- The FWorksheet instance for chaining.
Deprecated
use autoResizeColumns
instead
setColumnCustom()
setColumnCustom(custom): FWorksheet
Set custom properties for given columns.
Parameters
Parameter | Type | Description |
---|---|---|
custom | IObjectArrayPrimitiveType <CustomData > | The custom properties to set |
Returns
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
Parameter | Type | Description |
---|---|---|
index | number | column index |
custom | CustomData | custom metadata |
Returns
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
Parameter | Type | Description |
---|---|---|
index | number | The row index |
style | string | Nullable <…> | The style name or style data |
Returns
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
Parameter | Type | Description |
---|---|---|
height | number | The height to set. |
Returns
- 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
Parameter | Type | Description |
---|---|---|
columnPosition | number | The position of the given column to set |
width | number | The width in pixels to set it to |
Returns
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
Parameter | Type | Description |
---|---|---|
startColumn | number | The starting column position to change |
numColumn | number | The number of columns to change |
width | number | The width in pixels to set it to |
Returns
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
Parameter | Type | Description |
---|---|---|
cfId | string | The conditional formatting rule id to set |
rule | IConditionFormattingRule | The conditional formatting rule to set |
Returns
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
Parameter | Type | Description |
---|---|---|
custom | CustomData | custom metadata |
Returns
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
Parameter | Type | Description |
---|---|---|
style | string | Nullable <…> | The style to set |
Returns
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
Parameter | Type | Description |
---|---|---|
freeze | IFreeze | the 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
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
Parameter | Type | Description |
---|---|---|
columns | number | The number of columns to freeze. To unfreeze all columns, set this value to 0. |
Returns
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
Parameter | Type | Description |
---|---|---|
startColumn | number | The start column of the range to freeze |
endColumn | number | The end column of the range to freeze |
Returns
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
Parameter | Type | Description |
---|---|---|
rows | number | The number of rows to freeze. To unfreeze all rows, set this value to 0. |
Returns
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
Parameter | Type | Description |
---|---|---|
startRow | number | The start row of the range to freeze |
endRow | number | The end row of the range to freeze |
Returns
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
Parameter | Type | Description |
---|---|---|
color | string | The color to set for the gridlines.Undefined or null to reset to the default color. |
Returns
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
Parameter | Type | Description |
---|---|---|
hidden | boolean | If true , hide gridlines in this sheet; otherwise show the gridlines. |
Returns
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
Parameter | Type | Description |
---|---|---|
name | string | The new name for the sheet. |
Returns
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
Parameter | Type | Description |
---|---|---|
ranges | IRange [] | The ranges to change |
Returns
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
Parameter | Type | Description |
---|---|---|
startRow | number | The starting row position to change |
numRows | number | The number of rows to change |
Returns
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
Parameter | Type | Description |
---|---|---|
custom | IObjectArrayPrimitiveType <CustomData > | The custom properties to set |
Returns
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
Parameter | Type | Description |
---|---|---|
index | number | row index |
custom | CustomData | custom metadata |
Returns
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
Parameter | Type | Description |
---|---|---|
index | number | The column index |
style | string | Nullable <…> | The style name or style data |
Returns
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
Parameter | Type | Description |
---|---|---|
width | number | The width to set. |
Returns
- 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
Parameter | Type | Description |
---|---|---|
rowPosition | number | The row position to change. |
height | number | The height in pixels to set it to. |
Returns
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
Parameter | Type | Description |
---|---|---|
startRow | number | The starting row position to change |
numRows | number | The number of rows to change |
height | number | The height in pixels to set it to |
Returns
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
Parameter | Type | Description |
---|---|---|
startRow | number | The starting row position to change |
numRows | number | The number of rows to change |
height | number | The height in pixels to set it to |
Returns
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
Parameter | Type | Description |
---|---|---|
color | string | A color code in CSS notation (like ‘#ffffff’ or ‘white’), or null to reset the tab color. |
Returns
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
Parameter | Type | Description |
---|---|---|
columnIndex | number | The starting index of the columns to unhide |
numColumns ? | number | The number of columns to unhide |
Returns
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
Parameter | Type | Description |
---|---|---|
rowIndex | number | The starting index of the rows |
numRows ? | number | The number of rows |
Returns
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
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
Parameter | Type | Description |
---|---|---|
colIndex | number | The column index to sort by. |
asc ? | boolean | The sort order. true for ascending, false for descending. The column A index is 0. |
Returns
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
Parameter | Type | Description |
---|---|---|
ranges | IRange [] | 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
Parameter | Type | Description |
---|---|---|
column | FRange | The range to unhide, if hidden |
Returns
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
Parameter | Type | Description |
---|---|---|
row | FRange | The range to unhide, if hidden. |
Returns
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
Parameter | Type | Description |
---|---|---|
chartBuildInfo | IChartBuilderInfo | The 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
Parameter | Type | Description |
---|---|---|
sheetImages | ISheetImage [] | The images to update |
Returns
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
Parameter | Type | Description |
---|---|---|
zoomRatio | number | The zoom ratio to set.It should be in the range of 0.1 to 4.0. |
Returns
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