Definir e obter valores de intervalo, texto ou fórmulas com a API JavaScript do Excel

Este artigo fornece exemplos de código que definem e obtêm valores de intervalo, texto ou fórmulas com a API JavaScript do Excel. Para obter a lista completa de propriedades e métodos suportados pelo Range objeto, consulte Excel.Range class (Classe Excel.Range).

Observação

A API JavaScript do Excel não tem um objeto ou classe "Célula". Em vez disso, a API JavaScript do Excel define todas as células do Excel como objetos Range. Uma célula individual na interface do usuário do Excel se traduz em um objeto Range com uma célula na API JavaScript do Excel. Um único objeto Range também pode conter várias células contíguas. Confira Trabalhar com células usando a API JavaScript do Excel para saber mais.

Definir valores ou fórmulas

Os exemplos de código seguintes definem valores e fórmulas para uma única célula ou um intervalo de células.

Definir valor para uma única célula

O exemplo de código a seguir define o valor da célula C3 como "5" e, em seguida, define a largura das colunas para melhor ajustar os dados.

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

    let range = sheet.getRange("C3");
    range.values = [[ 5 ]];
    range.format.autofitColumns();

    await context.sync();
});

Dados antes da atualização do valor da célula

Dados após a atualização do valor da célula

Definir valores para um intervalo de células

O exemplo de código a seguir define valores das células no intervalo B5:D5 e, em seguida, define a largura das colunas para melhor ajustar os dados.

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

    let data = [
        ["Potato Chips", 10, 1.80],
    ];

    let range = sheet.getRange("B5:D5");
    range.values = data;
    range.format.autofitColumns();

    await context.sync();
});

Dados antes da atualização dos valores da célula

Dados após a atualização dos valores da célula

Definir fórmula para uma única célula

O exemplo de código a seguir define uma fórmula para a célula E3 e, em seguida, define a largura das colunas para melhor ajustar os dados.

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

    let range = sheet.getRange("E3");
    range.formulas = [[ "=C3 * D3" ]];
    range.format.autofitColumns();

    await context.sync();
});

Dados antes da definição da fórmula da célula

Dados após a definição da fórmula da célula

Definir fórmulas para um intervalo de células

O exemplo de código a seguir define fórmulas para células no intervalo E2:E6 e, em seguida, define a largura das colunas para melhor ajustar os dados.

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

    let data = [
        ["=C3 * D3"],
        ["=C4 * D4"],
        ["=C5 * D5"],
        ["=SUM(E3:E5)"]
    ];

    let range = sheet.getRange("E3:E6");
    range.formulas = data;
    range.format.autofitColumns();

    await context.sync();
});

Dados antes da definição das fórmulas da célula

Dados após a definição das fórmulas da célula

Obter valores, texto ou fórmulas

Estes exemplos de código obtêm valores, texto e fórmulas de um intervalo de células.

Obter valores de um intervalo de células

O seguinte exemplo de código obtém o intervalo B2:E6, carrega a respetiva values propriedade e escreve os valores na consola. A values propriedade de um intervalo especifica os valores não processados que as células contêm. Mesmo que algumas células num intervalo contenham fórmulas, a values propriedade do intervalo especifica os valores não processados para essas células e não qualquer uma das fórmulas.

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

    let range = sheet.getRange("B2:E6");
    range.load("values");
    await context.sync();

    console.log(JSON.stringify(range.values, null, 4));
});

Dados no intervalo (valores na coluna E são um resultado de fórmulas)

range.values (conforme registrado em log no console pelo exemplo de código acima)

[
    [
        "Product",
        "Qty",
        "Unit Price",
        "Total Price"
    ],
    [
        "Almonds",
        2,
        7.5,
        15
    ],
    [
        "Coffee",
        1,
        34.5,
        34.5
    ],
    [
        "Chocolate",
        5,
        9.56,
        47.8
    ],
    [
        "",
        "",
        "",
        97.3
    ]
]

Obter texto de um intervalo de células

O seguinte exemplo de código obtém o intervalo B2:E6, carrega a respetiva text propriedade e escreve-a na consola do . A text propriedade de um intervalo especifica os valores de apresentação das células no intervalo. Mesmo que algumas células num intervalo contenham fórmulas, a text propriedade do intervalo especifica os valores de apresentação dessas células e não qualquer uma das fórmulas.

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

    let range = sheet.getRange("B2:E6");
    range.load("text");
    await context.sync();

    console.log(JSON.stringify(range.text, null, 4));
});

Dados no intervalo (valores na coluna E são um resultado de fórmulas)

range.text (conforme registrado em log no console pelo exemplo de código acima)

[
    [
        "Product",
        "Qty",
        "Unit Price",
        "Total Price"
    ],
    [
        "Almonds",
        "2",
        "7.5",
        "15"
    ],
    [
        "Coffee",
        "1",
        "34.5",
        "34.5"
    ],
    [
        "Chocolate",
        "5",
        "9.56",
        "47.8"
    ],
    [
        "",
        "",
        "",
        "97.3"
    ]
]

Obter fórmulas de um intervalo de células

O seguinte exemplo de código obtém o intervalo B2:E6, carrega a respetiva formulas propriedade e escreve-a na consola do . A formulas propriedade de um intervalo especifica as fórmulas para células no intervalo que contêm fórmulas e os valores não processados para células no intervalo que não contêm fórmulas.

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

    let range = sheet.getRange("B2:E6");
    range.load("formulas");
    await context.sync();

    console.log(JSON.stringify(range.formulas, null, 4));
});

Dados no intervalo (valores na coluna E são um resultado de fórmulas)

range.formulas (conforme registrado em log no console pelo exemplo de código acima)

[
    [
        "Product",
        "Qty",
        "Unit Price",
        "Total Price"
    ],
    [
        "Almonds",
        2,
        7.5,
        "=C3 * D3"
    ],
    [
        "Coffee",
        1,
        34.5,
        "=C4 * D4"
    ],
    [
        "Chocolate",
        5,
        9.56,
        "=C5 * D5"
    ],
    [
        "",
        "",
        "",
        "=SUM(E3:E5)"
    ]
]

Confira também

• Modelo de objeto JavaScript do Excel em Suplementos do Office
• Trabalhar com células com a API javaScript do Excel
• Definir e obter intervalos com a API JavaScript do Excel
• Definir o formato de intervalo com a API JavaScript do Excel