Partilhar via


Definir e obter valores de intervalo, texto ou fórmulas usando 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 compatíveis com o Range objeto, consulte 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 a seguir 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 no Excel antes que o valor da célula seja atualizado.

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

Dados no Excel 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 no Excel antes que os valores de célula sejam atualizados.

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

Dados no Excel após a atualização dos valores de 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 no Excel antes da fórmula da célula ser definida.

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

Dados no Excel depois que a fórmula da célula é definida.

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 no Excel antes que as fórmulas de célula sejam definidas.

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

Dados no Excel depois que as fórmulas de célula são definidas.

Obter valores, texto ou fórmulas

Esses exemplos de código obtêm valores, texto e fórmulas de uma variedade de células.

Obter valores de um intervalo de células

O exemplo de código a seguir obtém o intervalo B2:E6, carrega sua values propriedade e grava os valores no console. A values propriedade de um intervalo especifica os valores brutos que as células contêm. Mesmo que algumas células em um intervalo contenham fórmulas, a values propriedade do intervalo especifica os valores brutos para essas células, não nenhuma 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)

Dados no Excel depois que as fórmulas de célula são definidas.

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 exemplo de código a seguir obtém o intervalo B2:E6, carrega sua text propriedade e grava-o no console. A text propriedade de um intervalo especifica os valores de exibição para células no intervalo. Mesmo que algumas células em um intervalo contenham fórmulas, a text propriedade do intervalo especifica os valores de exibição dessas células, não nenhuma 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)

Dados no Excel depois que as fórmulas de célula são definidas.

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 exemplo de código a seguir obtém o intervalo B2:E6, carrega sua formulas propriedade e grava-o no console. A formulas propriedade de um intervalo especifica as fórmulas para células no intervalo que contêm fórmulas e os valores brutos 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)

Dados no Excel depois que as fórmulas de célula são definidas.

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