NamedItem Object (JavaScript API for Excel)

Represents a defined name for a range of cells or value. Names can be primitive named objects (as seen in the type below), range object, reference to a range. This object can be used to obtain range object associated with names.

Properties

Property Type Description Req. Set
comment string Represents the comment associated with this name. 1.4
name string The name of the object. Read-only. 1.1
scope string Indicates whether the name is scoped to the workbook or to a specific worksheet. Read-only. Possible values are: Equal, Greater, GreaterEqual, Less, LessEqual, NotEqual. 1.4
type string Indicates the type of the value returned by the name's formula. Read-only. Possible values are: String, Integer, Double, Boolean, Range. 1.1
value object Represents the value computed by the name's formula. For a named range, will return the range address. Read-only. 1.1
visible bool Specifies whether the object is visible or not. 1.1

See property access examples.

Relationships

Relationship Type Description Req. Set
worksheet Worksheet Returns the worksheet on which the named item is scoped to. Throws an error if the items is scoped to the workbook instead. Read-only. 1.4
worksheetOrNullObject Worksheet Returns the worksheet on which the named item is scoped to. Returns a null object if the item is scoped to the workbook instead. Read-only. 1.4

Methods

Method Return Type Description Req. Set
delete() void Deletes the given name. 1.4
getRange() Range Returns the range object that is associated with the name. Throws an error if the named item's type is not a range. 1.1
getRangeOrNullObject() Range Returns the range object that is associated with the name. Returns a null object if the named item's type is not a range. 1.4

Method Details

delete()

Deletes the given name.

Syntax

namedItemObject.delete();

Parameters

None

Returns

void

getRange()

Returns the range object that is associated with the name. Throws an error if the named item's type is not a range.

Syntax

namedItemObject.getRange();

Parameters

None

Returns

Range

Examples

Returns the Range object that is associated with the name. null if the name is not of the type Range. Note: This API currently supports only the Workbook scoped items.**

Excel.run(function (ctx) { 
    var names = ctx.workbook.names;
    var range = names.getItem('MyRange').getRange();
    range.load('address');
    return ctx.sync().then(function() {
            console.log(range.address);
    });
}).catch(function(error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
            console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
});

getRangeOrNullObject()

Returns the range object that is associated with the name. Returns a null object if the named item's type is not a range.

Syntax

namedItemObject.getRangeOrNullObject();

Parameters

None

Returns

Range

Property access examples

Excel.run(function (ctx) { 
    var names = ctx.workbook.names;
    var namedItem = names.getItem('MyRange');
    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));
        }
});