Поделиться через

Excel.NamedItem class

  • Ссылка
Пакет:
excel

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

Extends
OfficeExtension.ClientObject

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

// 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

Комментарии

[ Набор API: ExcelApi 1.7 ]

comment

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

comment: string;

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

string

Комментарии

[ Набор API: ExcelApi 1.4 ]

context

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

context: RequestContext;

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

Excel.RequestContext

formula

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

formula: any;

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

any

Комментарии

[ Набор API: ExcelApi 1.7 ]

Примеры

// 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

Комментарии

[ Набор API: ExcelApi 1.1 ]

scope

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

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

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

Excel.NamedItemScope | "Worksheet" | "Workbook"

Комментарии

[ Набор API: ExcelApi 1.4 ]

type

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

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

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

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

Комментарии

[ Набор API: ExcelApi 1.1 для String,Integer,Double,Boolean,Range,Error; 1.7 для массива ]

value

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

readonly value: any;

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

any

Комментарии

[ Набор API: ExcelApi 1.1 ]

visible

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

visible: boolean;

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

boolean

Комментарии

[ Набор API: ExcelApi 1.1 ]

worksheet

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

readonly worksheet: Excel.Worksheet;

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

Excel.Worksheet

Комментарии

[ Набор API: ExcelApi 1.4 ]

worksheetOrNullObject

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

readonly worksheetOrNullObject: Excel.Worksheet;

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

Excel.Worksheet

Комментарии

[ Набор API: ExcelApi 1.4 ]

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

delete()

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

delete(): void;

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

void

Комментарии

[ Набор API: ExcelApi 1.4 ]

Примеры

// 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

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

// 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

Комментарии

[ Набор API: ExcelApi 1.4 ]

load(options)

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

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

Параметры

options
Excel.Interfaces.NamedItemLoadOptions

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

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

Excel.NamedItem

load(propertyNames)

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

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)

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

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