NamedItemCollection Object (JavaScript API for Excel)
A collection of all the nameditem objects that are part of the workbook or worksheet, depending on how it was reached.
Properties
| Property | Type | Description | Req. Set |
|---|---|---|---|
| items | NamedItem[] | A collection of namedItem objects. Read-only. | 1.1 |
See property access examples.
Relationships
None
Methods
| Method | Return Type | Description | Req. Set |
|---|---|---|---|
| add(name: string, reference: Range or string, comment: string) | NamedItem | Adds a new name to the collection of the given scope. | 1.4 |
| addFormulaLocal(name: string, formula: string, comment: string) | NamedItem | Adds a new name to the collection of the given scope using the user's locale for the formula. | 1.4 |
| getCount() | int | Gets the number of named items in the collection. | 1.4 |
| getItem(name: string) | NamedItem | Gets a nameditem object using its name | 1.1 |
| getItemOrNullObject(name: string) | NamedItem | Gets a nameditem object using its name. If the nameditem object does not exist, will return a null object. | 1.4 |
Method Details
add(name: string, reference: Range or string, comment: string)
Adds a new name to the collection of the given scope.
Syntax
namedItemCollectionObject.add(name, reference, comment);
Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | The name of the named item. |
| reference | Range or string | The formula or the range that the name will refer to. |
| comment | string | Optional. The comment associated with the named item |
Returns
addFormulaLocal(name: string, formula: string, comment: string)
Adds a new name to the collection of the given scope using the user's locale for the formula.
Syntax
namedItemCollectionObject.addFormulaLocal(name, formula, comment);
Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | The "name" of the named item. |
| formula | string | The formula in the user's locale that the name will refer to. |
| comment | string | Optional. The comment associated with the named item |
Returns
getCount()
Gets the number of named items in the collection.
Syntax
namedItemCollectionObject.getCount();
Parameters
None
Returns
int
getItem(name: string)
Gets a nameditem object using its name
Syntax
namedItemCollectionObject.getItem(name);
Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | nameditem name. |
Returns
Examples
Excel.run(function (ctx) {
var sheetName = 'Sheet1';
var nameditem = ctx.workbook.names.getItem(sheetName);
nameditem.load('type');
return ctx.sync().then(function() {
console.log(nameditem.type);
});
}).catch(function(error) {
console.log("Error: " + error);
if (error instanceof OfficeExtension.Error) {
console.log("Debug info: " + JSON.stringify(error.debugInfo));
}
});
getItemOrNullObject(name: string)
Gets a nameditem object using its name. If the nameditem object does not exist, will return a null object.
Syntax
namedItemCollectionObject.getItemOrNullObject(name);
Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | nameditem name. |
Returns
Property access examples
Excel.run(function (ctx) {
var nameditems = ctx.workbook.names;
nameditems.load('items');
return ctx.sync().then(function() {
for (var i = 0; i < nameditems.items.length; i++)
{
console.log(nameditems.items[i].name);
console.log(nameditems.items[i].index);
}
});
}).catch(function(error) {
console.log("Error: " + error);
if (error instanceof OfficeExtension.Error) {
console.log("Debug info: " + JSON.stringify(error.debugInfo));
}
});