Compartilhar via

Excel.NamedItem class

  • Referência
Pacote:
excel

Representa um nome definido para um intervalo de células ou um valor. Os nomes podem ser objetos com nomes primitivos (como se pode ver no tipo abaixo), objeto de intervalo ou uma referência a um intervalo. Use esse objeto para obter um objeto de intervalo associado aos nomes.

Extends
OfficeExtension.ClientObject

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

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

Propriedades

arrayValues

Retorna um objeto que contém valores e tipos do item nomeado.
comment

Especifica o comentário associado a este nome.
context

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.
formula

A fórmula do item com nome. As fórmulas começam sempre com um sinal de igual ("=").
name

O nome do objeto.
scope

Especifica se o nome está no âmbito do livro ou de uma folha de cálculo específica. Os valores possíveis são: Folha de Cálculo, Livro.
type

Especifica o tipo do valor devolvido pela fórmula do nome. Veja Excel.NamedItemType para obter detalhes.
value

Representa o valor calculado pela fórmula do nome. Para um intervalo com nome, irá devolver o endereço do intervalo. Esta API devolve o #VALUE! na IU do Excel, se se referir a uma função definida pelo utilizador.
visible

Especifica se o objeto está visível.
worksheet

Retorna a planilha em que o item nomeado tem escopo. Gera um erro se o item estiver no âmbito do livro.
worksheetOrNullObject

Devolve a folha de cálculo na qual o item com nome está no âmbito. Se, em vez disso, o item estiver no âmbito do livro, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

Métodos

delete()

Exclui o nome fornecido.
getRange()

Retorna o objeto Range associado ao nome. Gerará um erro se o tipo do item nomeado não for um intervalo.
getRangeOrNullObject()

Retorna o objeto Range associado ao nome. Se o tipo do item nomeado não for um intervalo, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).
load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.
set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.
toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Excel.NamedItem é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.NamedItemData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

Detalhes da propriedade

arrayValues

Retorna um objeto que contém valores e tipos do item nomeado.

readonly arrayValues: Excel.NamedItemArrayValues;

Valor da propriedade

Excel.NamedItemArrayValues

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

comment

Especifica o comentário associado a este nome.

comment: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

context

O contexto do pedido associado ao objeto . Esta ação liga o processo do suplemento ao processo da aplicação anfitriã do Office.

context: RequestContext;

Valor da propriedade

Excel.RequestContext

formula

A fórmula do item com nome. As fórmulas começam sempre com um sinal de igual ("=").

formula: any;

Valor da propriedade

any

Comentários

[ Conjunto de API: ExcelApi 1.7 ]

Exemplos

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

O nome do objeto.

readonly name: string;

Valor da propriedade

string

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

scope

Especifica se o nome está no âmbito do livro ou de uma folha de cálculo específica. Os valores possíveis são: Folha de Cálculo, Livro.

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

Valor da propriedade

Excel.NamedItemScope | "Worksheet" | "Workbook"

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

type

Especifica o tipo do valor devolvido pela fórmula do nome. Veja Excel.NamedItemType para obter detalhes.

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

Valor da propriedade

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

Comentários

[ Conjunto de API: ExcelApi 1.1 para Cadeia,Número Inteiro,Duplo,Booleano,Intervalo,Erro; 1,7 para Matriz ]

value

Representa o valor calculado pela fórmula do nome. Para um intervalo com nome, irá devolver o endereço do intervalo. Esta API devolve o #VALUE! na IU do Excel, se se referir a uma função definida pelo utilizador.

readonly value: any;

Valor da propriedade

any

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

visible

Especifica se o objeto está visível.

visible: boolean;

Valor da propriedade

boolean

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

worksheet

Retorna a planilha em que o item nomeado tem escopo. Gera um erro se o item estiver no âmbito do livro.

readonly worksheet: Excel.Worksheet;

Valor da propriedade

Excel.Worksheet

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

worksheetOrNullObject

Devolve a folha de cálculo na qual o item com nome está no âmbito. Se, em vez disso, o item estiver no âmbito do livro, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

readonly worksheetOrNullObject: Excel.Worksheet;

Valor da propriedade

Excel.Worksheet

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

Detalhes do método

delete()

Exclui o nome fornecido.

delete(): void;

Retornos

void

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

Exemplos

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

Retorna o objeto Range associado ao nome. Gerará um erro se o tipo do item nomeado não for um intervalo.

getRange(): Excel.Range;

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.1 ]

Exemplos

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

Retorna o objeto Range associado ao nome. Se o tipo do item nomeado não for um intervalo, este método devolve um objeto com a respetiva isNullObject propriedade definida como true. Para obter mais informações, veja *OrNullObject methods and properties (Métodos e propriedades do OrNullObject).

getRangeOrNullObject(): Excel.Range;

Retornos

Excel.Range

Comentários

[ Conjunto de API: ExcelApi 1.4 ]

load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

options
Excel.Interfaces.NamedItemLoadOptions

Fornece opções para as propriedades do objeto a carregar.

Retornos

Excel.NamedItem

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

propertyNames

string | string[]

Uma cadeia delimitada por vírgulas ou uma matriz de cadeias que especificam as propriedades a carregar.

Retornos

Excel.NamedItem

Exemplos

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)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

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

Parâmetros

propertyNamesAndPaths

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

propertyNamesAndPaths.select é uma cadeia delimitada por vírgulas que especifica as propriedades a carregar e propertyNamesAndPaths.expand é uma cadeia delimitada por vírgulas que especifica as propriedades de navegação a carregar.

Retornos

Excel.NamedItem

set(properties, options)

Define várias propriedades de um objeto ao mesmo tempo. Pode transmitir um objeto simples com as propriedades adequadas ou outro objeto de API do mesmo tipo.

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

Parâmetros

properties
Excel.Interfaces.NamedItemUpdateData

Um objeto JavaScript com propriedades que são estruturadas isomorfoticamente para as propriedades do objeto no qual o método é chamado.

options
OfficeExtension.UpdateOptions

Fornece uma opção para suprimir erros se o objeto de propriedades tentar definir quaisquer propriedades só de leitura.

Retornos

void

set(properties)

Define várias propriedades no objeto ao mesmo tempo, com base num objeto carregado existente.

set(properties: Excel.NamedItem): void;

Parâmetros

properties
Excel.NamedItem

Retornos

void

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é transmitido para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que lhe é transmitido.) Enquanto o objeto original Excel.NamedItem é um objeto de API, o toJSON método devolve um objeto JavaScript simples (escrito como Excel.Interfaces.NamedItemData) que contém cópias rasas de quaisquer propriedades subordinadas carregadas do objeto original.

toJSON(): Excel.Interfaces.NamedItemData;

Retornos

Excel.Interfaces.NamedItemData