Excel.NamedItem class

セルまたは値の範囲の定義済みの名前を表します。Represents a defined name for a range of cells or value. 名前には、プリミティブという名前のオブジェクト、range オブジェクト、または範囲への参照を指定できます。Names can be primitive named objects (as seen in the type below), range object, or a reference to a range. このオブジェクトを使用して、名前に関連付けられた範囲オブジェクトを取得することができます。This object can be used to obtain range object associated with names.

[API セット: excelapi 1.1][ API set: ExcelApi 1.1 ]

Extends

プロパティ

arrayValues

名前付きアイテムの値と型を含むオブジェクトを返します。Returns an object containing values and types of the named item. 読み取り専用です。Read-only.

[API セット: excelapi 1.7][ API set: ExcelApi 1.7 ]

comment

この名前に関連付けられているコメントを表します。Represents the comment associated with this name.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

context

オブジェクトに関連付けられている要求コンテキスト。The request context associated with the object. これにより、アドインのプロセスが Office ホストアプリケーションのプロセスに接続されます。This connects the add-in's process to the Office host application's process.

formula

名前付きのアイテムの数式を取得または設定します。Gets or sets the formula of the named item. 数式は常に '=' 記号で始まります。Formula always starts with a '=' sign.

[API セット: excelapi 1.7][ API set: ExcelApi 1.7 ]

name

オブジェクトの名前。The name of the object. 値の取得のみ可能です。Read-only.

[API セット: excelapi 1.1][ API set: ExcelApi 1.1 ]

scope

ブックまたは特定のワークシートに対して名前のスコープを設定するかどうかを示します。Indicates whether the name is scoped to the workbook or to a specific worksheet. 可能な値は次のとおりです。ワークシート、ブック。Possible values are: Worksheet, Workbook. 読み取り専用です。Read-only.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

type

名前の数式によって返される値の型を示します。Indicates the type of the value returned by the name's formula. 詳細については、「Excel. nameditemtype」を参照してください。See Excel.NamedItemType for details. 読み取り専用です。Read-only.

[API set: excelapi 1.1 for String、Integer、Double、Boolean、Range、Error; 1.7 (配列)][ API set: ExcelApi 1.1 for String,Integer,Double,Boolean,Range,Error; 1.7 for Array ]

value

名前の数式で計算された値を表します。Represents the value computed by the name's formula. 名前付き範囲の場合は範囲のアドレスを返します。For a named range, will return the range address. 読み取り専用です。Read-only.

[API セット: excelapi 1.1][ API set: ExcelApi 1.1 ]

visible

オブジェクトを表示するかどうかを指定します。Specifies whether the object is visible or not.

[API セット: excelapi 1.1][ API set: ExcelApi 1.1 ]

worksheet

名前付きのアイテムの対象になるワークシートを返します。Returns the worksheet on which the named item is scoped to. アイテムのスコープがブックに設定されている場合は、エラーをスローします。Throws an error if the item is scoped to the workbook instead.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

worksheetOrNullObject

名前付きのアイテムの対象になるワークシートを返します。Returns the worksheet on which the named item is scoped to. アイテムがブックを対象にしている場合は、null オブジェクトを返します。Returns a null object if the item is scoped to the workbook instead.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

メソッド

delete()

指定された名前を削除します。Deletes the given name.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

getRange()

名前に関連付けられている範囲オブジェクトを返します。Returns the range object that is associated with the name. 名前付きアイテムの型が範囲でない場合、エラーをスローします。Throws an error if the named item's type is not a range.

[API セット: excelapi 1.1][ API set: ExcelApi 1.1 ]

getRangeOrNullObject()

名前に関連付けられている範囲オブジェクトを返します。Returns the range object that is associated with the name. 名前付きアイテムの型が範囲でない場合は、null オブジェクトを返します。Returns a null object if the named item's type is not a range.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

load(option)

オブジェクトの指定のプロパティを読み込むコマンドを待ち行列に入れます。Queues up a command to load the specified properties of the object. プロパティを読み取るには先に "context.sync()" を呼び出す必要があります。You must call "context.sync()" before reading the properties.

load(propertyNames)

オブジェクトの指定のプロパティを読み込むコマンドを待ち行列に入れます。Queues up a command to load the specified properties of the object. プロパティを読み取るcontext.sync()前に、を呼び出す必要があります。You must call context.sync() before reading the properties.

load(propertyNamesAndPaths)

オブジェクトの指定のプロパティを読み込むコマンドを待ち行列に入れます。Queues up a command to load the specified properties of the object. プロパティを読み取るcontext.sync()前に、を呼び出す必要があります。You must call context.sync() before reading the properties.

set(properties, options)

一度に1つのオブジェクトの複数のプロパティを設定します。Sets multiple properties of an object at the same time. 適切なプロパティを持つプレーンオブジェクト、または同じ種類の別の API オブジェクトのいずれかを渡すことができます。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()

API オブジェクトがtoJSON()渡されるときに、より有用な出力を提供するために、JavaScript メソッドをオーバーライドします。JSON.stringify()Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringifyその後、渡されたtoJSONオブジェクトのメソッドを呼び出します。元の Excel の nameditem オブジェクトは API オブジェクトであるのにtoJSON対して、メソッドはプレーンな JavaScript オブジェクト (として入力されます) を返します。Excel.Interfaces.NamedItemData, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.NamedItem object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.NamedItemData) は、元のオブジェクトから読み込まれた子プロパティの浅いコピーを格納します。) that contains shallow copies of any loaded child properties from the original object.

プロパティの詳細

arrayValues

名前付きアイテムの値と型を含むオブジェクトを返します。Returns an object containing values and types of the named item. 読み取り専用です。Read-only.

[API セット: excelapi 1.7][ API set: ExcelApi 1.7 ]

readonly arrayValues: Excel.NamedItemArrayValues;

プロパティ値

comment

この名前に関連付けられているコメントを表します。Represents the comment associated with this name.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

comment: string;

プロパティ値

string

context

オブジェクトに関連付けられている要求コンテキスト。The request context associated with the object. これにより、アドインのプロセスが Office ホストアプリケーションのプロセスに接続されます。This connects the add-in's process to the Office host application's process.

context: RequestContext;

プロパティ値

RequestContext

formula

名前付きのアイテムの数式を取得または設定します。Gets or sets the formula of the named item. 数式は常に '=' 記号で始まります。Formula always starts with a '=' sign.

[API セット: excelapi 1.7][ API set: ExcelApi 1.7 ]

formula: any;

プロパティ値

any

Examples

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");

    // Get the named item
    const myNamedItem = sheet.names.getItemOrNullObject("MyRange");
    myNamedItem.load("name, formula");
    await context.sync();

    if (myNamedItem.isNullObject) {
        console.log(`There is no named item. Create it with "Add named item for a range" first.`);
    } else {                    
        // Update named item to point to the second range
        myNamedItem.formula = "=Sample!$B$10:$D$14";
        sheet.getRange("B10:D14").select();
        await context.sync();

        console.log(`Just updated the named item "${myNamedItem.name}" -- it's now located here: ${myNamedItem.formula}`);
    }
});

name

オブジェクトの名前。The name of the object. 値の取得のみ可能です。Read-only.

[API セット: excelapi 1.1][ API set: ExcelApi 1.1 ]

readonly name: string;

プロパティ値

string

scope

ブックまたは特定のワークシートに対して名前のスコープを設定するかどうかを示します。Indicates whether the name is scoped to the workbook or to a specific worksheet. 可能な値は次のとおりです。ワークシート、ブック。Possible values are: Worksheet, Workbook. 読み取り専用です。Read-only.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

readonly scope: Excel.NamedItemScope | "Worksheet" | "Workbook";

プロパティ値

Excel.NamedItemScope | "Worksheet" | "Workbook"

type

名前の数式によって返される値の型を示します。Indicates the type of the value returned by the name's formula. 詳細については、「Excel. nameditemtype」を参照してください。See Excel.NamedItemType for details. 読み取り専用です。Read-only.

[API set: excelapi 1.1 for String、Integer、Double、Boolean、Range、Error; 1.7 (配列)][ API set: ExcelApi 1.1 for String,Integer,Double,Boolean,Range,Error; 1.7 for Array ]

readonly type: Excel.NamedItemType | "String" | "Integer" | "Double" | "Boolean" | "Range" | "Error" | "Array";

プロパティ値

Excel.NamedItemType | "String" | "Integer" | "Double" | "Boolean" | "Range" | "Error" | "Array"

value

名前の数式で計算された値を表します。Represents the value computed by the name's formula. 名前付き範囲の場合は範囲のアドレスを返します。For a named range, will return the range address. 読み取り専用です。Read-only.

[API セット: excelapi 1.1][ API set: ExcelApi 1.1 ]

readonly value: any;

プロパティ値

any

visible

オブジェクトを表示するかどうかを指定します。Specifies whether the object is visible or not.

[API セット: excelapi 1.1][ API set: ExcelApi 1.1 ]

visible: boolean;

プロパティ値

boolean

worksheet

名前付きのアイテムの対象になるワークシートを返します。Returns the worksheet on which the named item is scoped to. アイテムのスコープがブックに設定されている場合は、エラーをスローします。Throws an error if the item is scoped to the workbook instead.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

readonly worksheet: Excel.Worksheet;

プロパティ値

worksheetOrNullObject

名前付きのアイテムの対象になるワークシートを返します。Returns the worksheet on which the named item is scoped to. アイテムがブックを対象にしている場合は、null オブジェクトを返します。Returns a null object if the item is scoped to the workbook instead.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

readonly worksheetOrNullObject: Excel.Worksheet;

プロパティ値

メソッドの詳細

delete()

指定された名前を削除します。Deletes the given name.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

delete(): void;

戻り値

void

Examples

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const totalName = sheet.names.getItemOrNullObject("TotalAmount");
    totalName.load();
    await context.sync();

    if (totalName.value) {
        totalName.delete();

        // Replace the named item (TotalAmount) with the actual formula for TotalAmount to avoid displaying #NAME in the cell.
        sheet.getRange("D11").values = [["=SUM(ExpensesTable[AMOUNT])"]];
    } else {
        console.log("No named item created for the formula.");
    }

    await context.sync();
});

getRange()

名前に関連付けられている範囲オブジェクトを返します。Returns the range object that is associated with the name. 名前付きアイテムの型が範囲でない場合、エラーをスローします。Throws an error if the named item's type is not a range.

[API セット: excelapi 1.1][ API set: ExcelApi 1.1 ]

getRange(): Excel.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. 名前付きアイテムの型が範囲でない場合は、null オブジェクトを返します。Returns a null object if the named item's type is not a range.

[API セット: excelapi 1.4][ API set: ExcelApi 1.4 ]

getRangeOrNullObject(): Excel.Range;

戻り値

load(option)

オブジェクトの指定のプロパティを読み込むコマンドを待ち行列に入れます。Queues up a command to load the specified properties of the object. プロパティを読み取るには先に "context.sync()" を呼び出す必要があります。You must call "context.sync()" before reading the properties.

load(option?: Excel.Interfaces.NamedItemLoadOptions): Excel.NamedItem;

パラメーター

戻り値

注釈

このシグネチャに加えて、このメソッドのシグネチャは次のとおりです。In addition to this signature, this method has the following signatures:

load(option?: string | string[]): Excel.NamedItem-Where オプションは、読み込むプロパティを指定する、コンマで区切られた文字列または文字列の配列です。load(option?: string | string[]): Excel.NamedItem - Where option is a comma-delimited string or an array of strings that specify the properties to load.

load(option?: { select?: string; expand?: string; }): Excel.NamedItem-Where オプションを指定します。 select は、読み込むプロパティを指定するコンマで区切られた文字列で、オプション expand は読み込むナビゲーションプロパティを指定するコンマ区切りの文字列です。load(option?: { select?: string; expand?: string; }): Excel.NamedItem - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Excel.NamedItem-コレクション型でのみ使用できます。load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Excel.NamedItem - Only available on collection types. これは、前述の署名に似ています。It is similar to the preceding signature. top は、結果に含めることができるコレクション項目の最大数を指定します。Option.top specifies the maximum number of collection items that can be included in the result. 省略すると、スキップされ、結果に含まれないアイテムの数を指定します。Option.skip specifies the number of items that are to be skipped and not included in the result. option を指定すると、指定した数のアイテムをスキップした後に結果セットが開始されます。If option.top is specified, the result set will start after skipping the specified number of items.

load(propertyNames)

オブジェクトの指定のプロパティを読み込むコマンドを待ち行列に入れます。Queues up a command to load the specified properties of the object. プロパティを読み取るcontext.sync()前に、を呼び出す必要があります。You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Excel.NamedItem;

パラメーター

propertyNames
string | string[]

読み込むプロパティを指定する、コンマで区切られた文字列または文字列の配列。A comma-delimited string or an array of strings that specify the properties to load.

戻り値

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));
        }
});

load(propertyNamesAndPaths)

オブジェクトの指定のプロパティを読み込むコマンドを待ち行列に入れます。Queues up a command to load the specified properties of the object. プロパティを読み取るcontext.sync()前に、を呼び出す必要があります。You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: { select?: string; expand?: string; }): Excel.NamedItem;

パラメーター

propertyNamesAndPaths
{ select?: string; expand?: string; }

ここで、は、読み込むプロパティを指定するコンマで区切られた文字列を指定します。 expand は、読み込むナビゲーションプロパティを指定するコンマ区切りの文字列です。Where 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.

戻り値

set(properties, options)

一度に1つのオブジェクトの複数のプロパティを設定します。Sets multiple properties of an object at the same time. 適切なプロパティを持つプレーンオブジェクト、または同じ種類の別の API オブジェクトのいずれかを渡すことができます。You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.NamedItemUpdateData, options?: OfficeExtension.UpdateOptions): void;

パラメーター

properties
Interfaces.NamedItemUpdateData

メソッドが呼び出されるオブジェクトのプロパティに構造化 isomorphically されているプロパティを持つ JavaScript オブジェクト。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.

戻り値

void

注釈

このメソッドには、次の追加のシグネチャがあります。This method has the following additional signature:

set(properties: Excel.NamedItem): void

set(properties)

既存の読み込まれたオブジェクトに基づいて、オブジェクトに複数のプロパティを設定します。Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Excel.NamedItem): void;

パラメーター

properties
Excel.NamedItem

戻り値

void

toJSON()

API オブジェクトがtoJSON()渡されるときに、より有用な出力を提供するために、JavaScript メソッドをオーバーライドします。JSON.stringify()Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringifyその後、渡されたtoJSONオブジェクトのメソッドを呼び出します。元の Excel の nameditem オブジェクトは API オブジェクトであるのにtoJSON対して、メソッドはプレーンな JavaScript オブジェクト (として入力されます) を返します。Excel.Interfaces.NamedItemData, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.NamedItem object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.NamedItemData) は、元のオブジェクトから読み込まれた子プロパティの浅いコピーを格納します。) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Excel.Interfaces.NamedItemData;

戻り値