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

NamedItem

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

NamedItem

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

NamedItem

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

NamedItem

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));
        }
});
} }); }).catch(function(error) { console.log("Error: " + error); if (error instanceof OfficeExtension.Error) { console.log("Debug info: " + JSON.stringify(error.debugInfo)); } });