Excel.Worksheet class
An Excel worksheet is a grid of cells. It can contain data, tables, charts, etc. To learn more about the worksheet object model, read Work with worksheets using the Excel JavaScript API.
- Extends
Remarks
Examples
// Get a Worksheet object by its name and activate it.
await Excel.run(async (context) => {
const wSheetName = 'Sheet1';
const worksheet = context.workbook.worksheets.getItem(wSheetName);
worksheet.activate();
await context.sync();
});
Properties
| charts | Returns a collection of charts that are part of the worksheet. |
| context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
| id | Returns a value that uniquely identifies the worksheet in a given workbook. The value of the identifier remains the same even when the worksheet is renamed or moved. |
| name | The display name of the worksheet. The name must be fewer than 32 characters. |
| position | The zero-based position of the worksheet within the workbook. |
| tables | Collection of tables that are part of the worksheet. |
| visibility | The visibility of the worksheet. |
Methods
| activate() | Activate the worksheet in the Excel UI. |
| delete() | Deletes the worksheet from the workbook. Note that if the worksheet's visibility is set to "VeryHidden", the delete operation will fail with an |
| get |
Gets the |
| get |
Gets the |
| load(options) | Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| load(property |
Queues up a command to load the specified properties of the object. You must call |
| set(properties, options) | Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type. |
| set(properties) | Sets multiple properties on the object at the same time, based on an existing loaded object. |
| toJSON() | Overrides the JavaScript |
Property Details
charts
Returns a collection of charts that are part of the worksheet.
readonly charts: Excel.ChartCollection;Property Value
Remarks
context
The request context associated with the object. This connects the add-in's process to the Office host application's process.
context: RequestContext;Property Value
id
Returns a value that uniquely identifies the worksheet in a given workbook. The value of the identifier remains the same even when the worksheet is renamed or moved.
readonly id: string;Property Value
string
Remarks
name
The display name of the worksheet. The name must be fewer than 32 characters.
name: string;Property Value
string
Remarks
position
The zero-based position of the worksheet within the workbook.
position: number;Property Value
number
Remarks
Examples
// Set worksheet position.
await Excel.run(async (context) => {
const wSheetName = 'Sheet1';
const worksheet = context.workbook.worksheets.getItem(wSheetName);
worksheet.position = 2;
await context.sync();
});
tables
Collection of tables that are part of the worksheet.
readonly tables: Excel.TableCollection;Property Value
Remarks
visibility
The visibility of the worksheet.
visibility: Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden";Property Value
Excel.SheetVisibility | "Visible" | "Hidden" | "VeryHidden"
Remarks
[ API set: ExcelApi 1.1 for reading visibility; 1.2 for setting it. ]
Method Details
activate()
Activate the worksheet in the Excel UI.
activate(): void;Returns
void
Remarks
Examples
await Excel.run(async (context) => {
const wSheetName = 'Sheet1';
const worksheet = context.workbook.worksheets.getItem(wSheetName);
worksheet.activate();
await context.sync();
});
delete()
Deletes the worksheet from the workbook. Note that if the worksheet's visibility is set to "VeryHidden", the delete operation will fail with an InvalidOperation exception. You should first change its visibility to hidden or visible before deleting it.
delete(): void;Returns
void
Remarks
Examples
await Excel.run(async (context) => {
const wSheetName = 'Sheet1';
const worksheet = context.workbook.worksheets.getItem(wSheetName);
worksheet.delete();
await context.sync();
});
getCell(row, column)
Gets the Range object containing the single cell based on row and column numbers. The cell can be outside the bounds of its parent range, so long as it stays within the worksheet grid.
getCell(row: number, column: number): Excel.Range;Parameters
- row
-
number
The row number of the cell to be retrieved. Zero-indexed.
- column
-
number
The column number of the cell to be retrieved. Zero-indexed.
Returns
Remarks
Examples
await Excel.run(async (context) => {
const sheetName = "Sheet1";
const rangeAddress = "A1:F8";
const worksheet = context.workbook.worksheets.getItem(sheetName);
const cell = worksheet.getCell(0,0);
cell.load('address');
await context.sync();
console.log(cell.address);
});
getRange(address)
Gets the Range object, representing a single rectangular block of cells, specified by the address or name.
getRange(address?: string): Excel.Range;Parameters
- address
-
string
Optional. The string representing the address or name of the range. For example, "A1:B2". If not specified, the entire worksheet range is returned.
Returns
Remarks
Examples
// Use the range address to get the range object.
await Excel.run(async (context) => {
const sheetName = "Sheet1";
const rangeAddress = "A1:F8";
const worksheet = context.workbook.worksheets.getItem(sheetName);
const range = worksheet.getRange(rangeAddress);
range.load('cellCount');
await context.sync();
console.log(range.cellCount);
});
load(options)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(options?: Excel.Interfaces.WorksheetLoadOptions): Excel.Worksheet;Parameters
Provides options for which properties of the object to load.
Returns
load(propertyNames)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames?: string | string[]): Excel.Worksheet;Parameters
- propertyNames
-
string | string[]
A comma-delimited string or an array of strings that specify the properties to load.
Returns
Examples
// Get worksheet properties based on sheet name.
await Excel.run(async (context) => {
const wSheetName = 'Sheet1';
const worksheet = context.workbook.worksheets.getItem(wSheetName);
worksheet.load('position')
await context.sync();
console.log(worksheet.position);
});
load(propertyNamesAndPaths)
Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths?: {
select?: string;
expand?: string;
}): Excel.Worksheet;Parameters
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.
Returns
set(properties, options)
Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties: Interfaces.WorksheetUpdateData, options?: OfficeExtension.UpdateOptions): void;Parameters
- properties
- Excel.Interfaces.WorksheetUpdateData
A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.
- options
- OfficeExtension.UpdateOptions
Provides an option to suppress errors if the properties object tries to set any read-only properties.
Returns
void
Examples
// Set the color and name of the current worksheet.
await Excel.run(async (context) => {
const activeSheet = context.workbook.worksheets.getActiveWorksheet();
activeSheet.set({
tabColor: "yellow",
name: "MySheet"
});
await context.sync();
});
set(properties)
Sets multiple properties on the object at the same time, based on an existing loaded object.
set(properties: Excel.Worksheet): void;Parameters
- properties
- Excel.Worksheet
Returns
void
toJSON()
Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.Worksheet object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.WorksheetData) that contains shallow copies of any loaded child properties from the original object.
toJSON(): Excel.Interfaces.WorksheetData;Returns
Office Add-ins