Excel.NamedItem class

Ссылка

Пакет:: excel

Представляет определенное имя для диапазона ячеек или значения. Имена могут быть примитивными именованными объектами (как показано в типе ниже), объектом диапазона или ссылкой на диапазон. Этот объект может использоваться для получения объекта диапазона, связанного с именами.

Extends: OfficeExtension.ClientObject

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/34-named-item/create-and-remove-named-item.yaml

await Excel.run(async (context) => {
    // Log all the named items in the active worksheet.
    const namedItems = context.workbook.worksheets.getActiveWorksheet().names.load();
    await context.sync();

    console.log("This worksheet contains " + namedItems.items.length + " named items.");

    for (let i = 0; i < namedItems.items.length; i++) {
        const namedItem : Excel.NamedItem = namedItems.items[i];
        console.log(JSON.stringify(namedItem)) + "\n";
    }

    await context.sync();
});

Свойства

arrayValues	Возвращает объект, содержащий значения и типы именованного элемента.
comment	Указывает комментарий, связанный с этим именем.
context	Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.
formula	Формула именованного элемента. Формулы всегда начинаются со знака равенства ("=").
name	Имя объекта.
scope	Указывает, имеет ли имя область действия книги или определенного листа. Возможные значения: Лист, Книга.
type	Указывает тип значения, возвращаемого формулой имени. Дополнительные сведения см. в этой `Excel.NamedItemType` статье.
value	Представляет значение, вычисленное по формуле имени. Для именованного диапазона он вернет адрес диапазона. Этот API возвращает #VALUE! ошибка в пользовательском интерфейсе Excel, если она ссылается на определяемую пользователем функцию.
visible	Указывает, является ли объект видимым.
worksheet	Возвращает лист, к которому относится именованный элемент. Выдает ошибку, если элемент ограничен книгой.
worksheetOrNullObject	Возвращает лист, для которого задана область именованного элемента. Если элемент ограничен книгой, то этот метод возвращает объект со свойством `isNullObjecttrue`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

Методы

delete()	Удаляет заданное имя.
getRange()	Возвращает объект диапазона, связанный с именем. Выдает ошибку, если именованный элемент не является диапазоном.
getRangeOrNullObject()	Возвращает объект Range, сопоставленный с именем. Если тип именованного элемента не является диапазоном, то этот метод возвращает объект со свойством `isNullObject` .`true` Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
load(options)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNames)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNamesAndPaths)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
set(properties, options)	Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.
set(properties)	Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.
toJSON()	Переопределяет метод JavaScript `toJSON()` , чтобы обеспечить более полезные выходные данные при передаче объекта API в `JSON.stringify()`. (`JSON.stringify`в свою очередь вызывает `toJSON` метод переданного ему объекта.) В то время как исходный объект Excel.NamedItem является объектом API, `toJSON` метод возвращает обычный объект JavaScript (типизированный как `Excel.Interfaces.NamedItemData`), который содержит неглубокие копии всех загруженных дочерних свойств из исходного объекта.

Сведения о свойстве

arrayValues

Возвращает объект, содержащий значения и типы именованного элемента.

readonly arrayValues: Excel.NamedItemArrayValues;

Значение свойства

Excel.NamedItemArrayValues

comment

Указывает комментарий, связанный с этим именем.

comment: string;

Значение свойства

string

context

Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.

context: RequestContext;

Значение свойства

Excel.RequestContext

formula

Формула именованного элемента. Формулы всегда начинаются со знака равенства ("=").

formula: any;

Значение свойства

any

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/34-named-item/update-named-item.yaml

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

Имя объекта.

readonly name: string;

Значение свойства

string

scope

Указывает, имеет ли имя область действия книги или определенного листа. Возможные значения: Лист, Книга.

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

Значение свойства

Excel.NamedItemScope | "Worksheet" | "Workbook"

type

Указывает тип значения, возвращаемого формулой имени. Дополнительные сведения см. в этой Excel.NamedItemType статье.

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

Значение свойства

value

Представляет значение, вычисленное по формуле имени. Для именованного диапазона он вернет адрес диапазона. Этот API возвращает #VALUE! ошибка в пользовательском интерфейсе Excel, если она ссылается на определяемую пользователем функцию.

readonly value: any;

Значение свойства

any

visible

Указывает, является ли объект видимым.

visible: boolean;

Значение свойства

boolean

worksheet

Возвращает лист, к которому относится именованный элемент. Выдает ошибку, если элемент ограничен книгой.

readonly worksheet: Excel.Worksheet;

Значение свойства

Excel.Worksheet

worksheetOrNullObject

Возвращает лист, для которого задана область именованного элемента. Если элемент ограничен книгой, то этот метод возвращает объект со свойством isNullObjecttrue. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

readonly worksheetOrNullObject: Excel.Worksheet;

Значение свойства

Excel.Worksheet

Сведения о методе

delete()

Удаляет заданное имя.

delete(): void;

Возвращаемое значение

void

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/34-named-item/create-and-remove-named-item.yaml

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()

Возвращает объект диапазона, связанный с именем. Выдает ошибку, если именованный элемент не является диапазоном.

getRange(): Excel.Range;

Возвращаемое значение

Excel.Range

Примеры

// Returns the Range object that is associated with the name.
// Returns `null` if the name is not of type Range.
// Note: This API currently supports only the Workbook scoped items.
await Excel.run(async (context) => { 
    const names = context.workbook.names;
    const range = names.getItem('MyRange').getRange();
    range.load('address');
    await context.sync();

    console.log(range.address);
});

getRangeOrNullObject()

Возвращает объект Range, сопоставленный с именем. Если тип именованного элемента не является диапазоном, то этот метод возвращает объект со свойством isNullObject .true Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getRangeOrNullObject(): Excel.Range;

Возвращаемое значение

Excel.Range

load(options)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

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

Параметры

options: Excel.Interfaces.NamedItemLoadOptions

Предоставляет параметры свойств объекта для загрузки.

Возвращаемое значение

Excel.NamedItem

load(propertyNames)

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

Параметры

propertyNames: string | string[]

Строка с разделителями-запятыми или массив строк, указывающих свойства для загрузки.

Возвращаемое значение

Excel.NamedItem

Примеры

await Excel.run(async (context) => { 
    const names = context.workbook.names;
    const namedItem = names.getItem('MyRange');
    namedItem.load('type');
    await context.sync();
    
    console.log(namedItem.type);
});

load(propertyNamesAndPaths)

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

Параметры

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

propertyNamesAndPaths.select — это строка с разделителями-запятыми, указывающая загружаемые свойства, и propertyNamesAndPaths.expand строка с разделителями-запятыми, указывающая загружаемые свойства навигации.

Возвращаемое значение

Excel.NamedItem

set(properties, options)

Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.

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

Параметры

properties: Excel.Interfaces.NamedItemUpdateData

Объект JavaScript со свойствами, структурированными изоморфно по свойствам объекта, для которого вызывается метод .

options: OfficeExtension.UpdateOptions

Предоставляет возможность подавления ошибок, если объект свойств пытается задать какие-либо свойства, доступные только для чтения.

Возвращаемое значение

void

set(properties)

Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.

set(properties: Excel.NamedItem): void;

Параметры

properties: Excel.NamedItem

Возвращаемое значение

void

toJSON()

Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringifyв свою очередь вызывает toJSON метод переданного ему объекта.) В то время как исходный объект Excel.NamedItem является объектом API, toJSON метод возвращает обычный объект JavaScript (типизированный как Excel.Interfaces.NamedItemData), который содержит неглубокие копии всех загруженных дочерних свойств из исходного объекта.

toJSON(): Excel.Interfaces.NamedItemData;

Возвращаемое значение

Excel.Interfaces.NamedItemData

Excel.NamedItem class

Комментарии

Примеры

Свойства

Методы

Сведения о свойстве

arrayValues

Значение свойства

Комментарии

comment

Значение свойства

Комментарии

context

Значение свойства

formula

Значение свойства

Комментарии

Примеры

name

Значение свойства

Комментарии

scope

Значение свойства

Комментарии

type

Значение свойства

Комментарии

value

Значение свойства

Комментарии

visible

Значение свойства

Комментарии

worksheet

Значение свойства

Комментарии

worksheetOrNullObject

Значение свойства

Комментарии

Сведения о методе

delete()

Возвращаемое значение

Комментарии

Примеры

getRange()

Возвращаемое значение

Комментарии

Примеры

getRangeOrNullObject()

Возвращаемое значение

Комментарии

load(options)

Параметры

Возвращаемое значение

load(propertyNames)

Параметры

Возвращаемое значение

Примеры

load(propertyNamesAndPaths)

Параметры

Возвращаемое значение

set(properties, options)

Параметры

Возвращаемое значение

set(properties)

Параметры

Возвращаемое значение

toJSON()

Возвращаемое значение

Обратная связь

Дополнительные ресурсы