Principais conceitos de modelo de objetos do Excel para Suplementos do Office

Este artigo explica como os livros, folhas de cálculo, intervalos, tabelas e gráficos se encaixam no modelo de objetos JavaScript do Excel.

Na maioria dos suplementos do Excel, começa com um livro, muda para uma folha de cálculo, trabalha com um ou mais intervalos e, em seguida, cria objetos de nível superior, como tabelas ou gráficos. Compreender esse fluxo ajuda-o a desenvolver o suplemento mais rapidamente e a escolher a API certa para cada tarefa.

Comece com os objetos do Excel que irá utilizar mais

Normalmente, os suplementos do Excel começam com o livro e funcionam com elementos mais específicos da folha de cálculo. Eis como conceptualizar alguns dos objetos JavaScript.

• Um Workbook contém um ou mais Worksheet objetos.
• A Worksheet contém células e objetos ao nível da folha.
• Um Range representa uma célula ou um bloco de células contíguas.
• Range os objetos são o ponto de partida para escrever valores, fórmulas e formatos.
• Table E Chart os objetos são normalmente criados a partir de dados que já existem num intervalo.

Se não estiver familiarizado com o modelo de objetos do Excel, comece com estas tarefas comuns:

• Definir ou obter valores, texto e fórmulas do intervalo do Excel
• Criar, ler e gerir tabelas com a API JavaScript do Excel
• Gerir folhas de cálculo do Excel com a API javaScript

Trabalhar com intervalos

Um intervalo é um grupo de células contíguas num livro. Normalmente, os suplementos utilizam notação de estilo A1 para definir intervalos, como B3 para uma única célula ou C2:F4 para um bloco retangular de células.

Os intervalos expõem três propriedades principais que a maioria dos suplementos utiliza imediatamente:

• values para ler ou escrever valores de células.
• formulas para ler ou escrever fórmulas.
• format para alterar a formatação visual.

Criar uma folha de cálculo de vendas simples com intervalos

O exemplo seguinte cria um pequeno relatório de vendas. Escreve uma linha de cabeçalho e linhas de produto, calcula totais com fórmulas e formatará os totais como moeda. Utilize este padrão quando o seu suplemento precisar de preencher e formatar um bloco de células numa única operação.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // Create the headers and format them to stand out.
    const headers = [["Product", "Quantity", "Unit Price", "Totals"]];
    const headerRange = sheet.getRange("B2:E2");
    headerRange.values = headers;
    headerRange.format.fill.color = "#4472C4";
    headerRange.format.font.color = "white";

    // Create the product data rows.
    const productData = [
        ["Almonds", 6, 7.5],
        ["Coffee", 20, 34.5],
        ["Chocolate", 10, 9.56]
    ];
    const dataRange = sheet.getRange("B3:D5");
    dataRange.values = productData;

    // Create the formulas to total the amounts sold.
    const totalFormulas = [
        ["=C3 * D3"],
        ["=C4 * D4"],
        ["=C5 * D5"],
        ["=SUM(E3:E5)"]
    ];
    const totalRange = sheet.getRange("E3:E6");
    totalRange.formulas = totalFormulas;
    totalRange.format.font.bold = true;

    // Display the totals as US dollar amounts.
    totalRange.numberFormat = [["$0.00"]];

    await context.sync();
});

Este exemplo cria os seguintes dados na folha de cálculo ativa.

Para obter mais informações, consulte Definir ou obter valores, texto e fórmulas do intervalo do Excel.

Transformar intervalos em tabelas e gráficos

Depois de o suplemento escrever dados num intervalo, muitas vezes transforma esses dados num objeto mais rico. As tabelas facilitam a ordenação e filtragem dos dados. Os gráficos facilitam a compreensão rápida dos padrões.

A API JavaScript do Excel também suporta outros objetos de livro, incluindo tabelas dinâmicas, formas e imagens. No entanto, as tabelas e os gráficos são o passo seguinte mais comum depois de criar um intervalo.

Criar uma tabela a partir de um intervalo

Crie uma tabela quando os utilizadores precisarem de filtragem incorporada, referências estruturadas e formatação de tabelas. O exemplo seguinte converte os dados de vendas do exemplo anterior numa tabela.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.tables.add("B2:E5", true);
    await context.sync();
});

Quando executa este código na folha de cálculo com os dados anteriores, o Excel cria a seguinte tabela.

Para obter mais informações, veja Criar, ler e gerir tabelas com a API JavaScript do Excel.

Criar um gráfico a partir de um intervalo

Crie um gráfico quando quiser que os utilizadores interpretem os dados do livro visualmente. O exemplo seguinte cria um gráfico de colunas empilhadas a partir do item e dados de quantidade e, em seguida, coloca o gráfico 100 píxeis abaixo da parte superior da folha de cálculo.

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const chart = sheet.charts.add(Excel.ChartType.columnStacked, sheet.getRange("B3:C5"));
    chart.top = 100;
    await context.sync();
});

Quando executa este código na folha de cálculo com a tabela anterior, o Excel cria o seguinte gráfico.

Para obter mais informações, veja Criar e personalizar gráficos com a API JavaScript do Excel.

Saber quando utilizar APIs Comuns

Um suplemento do Excel interage com objetos no Excel usando a API JavaScript do Office, que inclui dois modelos de objetos JavaScript:

• API JavaScript do Excel: Introduzida com o Office 2016, a API JavaScript do Excel fornece objetos do Excel fortemente tipados que você pode usar para acessar planilhas, intervalos, tabelas, gráficos e muito mais.

• APIs Comuns: Introduzida com o Office 2013, a API Comum permite que você acesse recursos como interface de usuário, caixas de diálogo e configurações de cliente, que são comuns entre vários tipos de aplicativos do Office. A funcionalidade limitada para a interação do Excel na API Comum foi substituída pela API JavaScript do Excel.

Irá utilizar a API JavaScript do Excel para a maioria das operações de livros, mas também utilizará objetos na API Comum para informações de runtime de suplementos e acesso a ficheiros.

• Contexto: utilize o Context objeto para inspecionar o runtime do suplemento, incluindo contentLanguage, officeTheme, hoste platform. Também pode ligar requirements.isSetSupported() para marcar se o Excel suporta um conjunto de requisitos específico.
• Documento: utilize o objeto e o Document respetivo getFileAsync() método quando precisar de transferir o ficheiro do livro onde o suplemento está em execução.

A imagem seguinte mostra quando poderá utilizar a API JavaScript do Excel em vez das APIs Comuns.

Confira também

• Criar suplementos do Excel para Excel
• Crie seu primeiro suplemento do Excel
• Gerir folhas de cálculo do Excel com a API javaScript
• Definir ou obter valores, texto e fórmulas do intervalo do Excel
• Criar, ler e gerir tabelas com a API JavaScript do Excel
• Exemplos de código de suplementos do Excel
• Otimizar o desempenho da API JavaScript do Excel
• Referência da API JavaScript do Excel