Torne os Dados do Excel Visuais com Formatação Condicional em JavaScript

Uma tabela de vendas com vinte colunas de números é precisa e ilegível. O olho não consegue comparar 43.210 com 38.900 ao longo de uma linha rápido o suficiente para encontrar o trimestre fraco, e quem lê o relatório sabe disso — por isso pede um gráfico. Mas um gráfico por coluna significa vinte gráficos, e agora a planilha é uma galeria em vez de uma tabela.

Barras de dados, escalas de cores e conjuntos de ícones resolvem isso dentro das próprias células. Uma barra cresce proporcionalmente ao valor. Uma cor muda de pálida para saturada conforme o número aumenta. Um ícone muda de forma quando o valor cruza um limite. Nenhum deles adiciona linhas, colunas ou objetos flutuantes — a visualização fica na célula que já contém o número. Todos os três são formas de formatação condicional do Excel, e o Spire.XLS for JavaScript os aplica por meio de uma única API no navegador em WebAssembly, com arquivos percorrendo um sistema de arquivos virtual (VFS) e sem necessidade de backend.

Para configuração do projeto, consulte Integrando o Spire.XLS for JavaScript em um projeto React. Os exemplos abaixo assumem que o pacote está instalado e que o módulo WebAssembly foi inicializado.

Por que não apenas adicionar um gráfico

Gráficos e visualização na célula respondem à mesma pergunta — "como esses valores se comparam?" — mas se encaixam em momentos diferentes:

Quando o objetivo é tornar uma tabela de números fácil de escanear sem reconstruir o layout, a visualização na célula é a ferramenta mais leve. As três seções abaixo cobrem cada tipo, e elas compartilham mais API do que diferem — o que é a primeira coisa que vale a pena saber.

Pré-requisitos

Você precisa de um projeto React com o Spire.XLS for JavaScript instalado e o módulo WebAssembly inicializado, acessível em window.wasmModule.spirexls. O exemplo carrega uma fonte e um arquivo de dados de vendas no VFS, e salva com o sinalizador de versão do Excel 2010, que é a versão mais antiga que suporta esses tipos de formato condicional.

Uma API, três visualizações

Todos os três tipos seguem a mesma cadeia de chamadas. A única linha que muda é a atribuição de FormatType:

sheet.ConditionalFormats.Add()  →  xcfs.AddRange(range)  →  format = xcfs.AddCondition()  →  format.FormatType = ???

A cadeia compartilhada é o motivo pelo qual os três exemplos de código abaixo parecem semelhantes — eles são a mesma operação com um tipo de formato diferente. As diferenças estão no que cada tipo produz e quando você recorreria a ele, o que a tabela de comparação mais adiante neste artigo aborda.

Barras de dados: magnitude em um relance

Uma barra de dados desenha uma faixa colorida horizontal dentro de cada célula, e o comprimento da faixa é proporcional ao valor da célula em relação ao restante do intervalo selecionado. O maior valor preenche a célula; o menor preenche uma lasca. Escanear uma linha de barras de dados é a mesma operação mental que escanear um gráfico de barras, exceto que os números permanecem visíveis por baixo.

Os passos são:

1. Carregue a fonte e o arquivo de dados de teste no VFS.
2. Carregue a pasta de trabalho e obtenha a planilha.
3. Chame ConditionalFormats.Add para criar um formato condicional e vincule o intervalo de dados com AddRange.
4. Chame AddCondition para adicionar uma condição, defina FormatType como DataBar e defina a cor da barra.
5. Salve a pasta de trabalho.

function App() {
  const applyDataBars = async () => {
    // Get the Spire.XLS WASM module
    const xlsModule = window.wasmModule?.spirexls;

    // Check whether the module is ready
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // Load the font and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'SalesData.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // Load the workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });
    const sheet = workbook.Worksheets.get(0);

    // Select the data range that receives the data bars
    const dataRange = sheet.Range.get("B2:E9");

    // Create a conditional format and bind it to that range
    const xcfs = sheet.ConditionalFormats.Add();
    xcfs.AddRange(dataRange);

    // Add a data bar condition and set the bar color
    const format = xcfs.AddCondition();
    format.FormatType = xlsModule.ConditionalFormatType.DataBar;
    format.DataBar.BarColor = xlsModule.Color.get_CadetBlue();

    // Save the workbook
    const outputFileName = "ApplyDataBars.xlsx";
    workbook.SaveToFile({ fileName: outputFileName, version: xlsModule.ExcelVersion.Version2010 });

    // Dispose of the workbook object to free resources
    workbook.Dispose();

    // Read the result file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Apply Data Bars</h1>
      <button onClick={applyDataBars}>Start</button>
    </div>
  );
}

export default App;

Barras de dados aplicadas a uma tabela de números de vendas, com o comprimento da barra proporcional ao valor da célula

Apenas células numéricas recebem barras — células de texto dentro do intervalo são ignoradas. Isso é esperado: uma barra de dados expressa magnitude relativa, e texto não tem magnitude a expressar. Mantenha o intervalo limitado à área numérica; incluir uma coluna de nomes de produtos ou uma linha de cabeçalho não causa erro, mas essas células não mostrarão nada.

Escalas de cores: mapa de calor sem gráfico

Uma escala de cores sombreia cada célula com base em onde seu valor se posiciona entre o mínimo e o máximo do intervalo. Nenhum argumento de cor é necessário — quando nenhum é especificado, o resultado é uma escala de duas cores que assume laranja no mínimo e amarelo pálido no máximo, com valores intermediários sombreados proporcionalmente. O efeito é um mapa de calor incorporado à tabela de dados: pontos quentes e frios ficam visíveis sem classificação ou gráfico.

Os passos são os mesmos das barras de dados, com FormatType definido como ColorScale e nenhuma propriedade adicional:

1. Carregue a fonte e o arquivo de dados de teste no VFS.
2. Carregue a pasta de trabalho e obtenha a planilha.
3. Chame ConditionalFormats.Add para criar um formato condicional e vincule o intervalo de dados com AddRange.
4. Chame AddCondition para adicionar uma condição e defina FormatType como ColorScale.
5. Salve a pasta de trabalho.

function App() {
  const applyColorScales = async () => {
    // Get the Spire.XLS WASM module
    const xlsModule = window.wasmModule?.spirexls;

    // Check whether the module is ready
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // Load the font and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'SalesData.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // Load the workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });
    const sheet = workbook.Worksheets.get(0);

    // Select the data range that receives the color scales
    const dataRange = sheet.Range.get("B2:E9");

    // Create a conditional format and bind it to that range
    const xcfs = sheet.ConditionalFormats.Add();
    xcfs.AddRange(dataRange);

    // Add a color scale condition; colors transition with the values
    const format = xcfs.AddCondition();
    format.FormatType = xlsModule.ConditionalFormatType.ColorScale;

    // Save the workbook
    const outputFileName = "ApplyColorScales.xlsx";
    workbook.SaveToFile({ fileName: outputFileName, version: xlsModule.ExcelVersion.Version2010 });

    // Dispose of the workbook object to free resources
    workbook.Dispose();

    // Read the result file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Apply Color Scales</h1>
      <button onClick={applyColorScales}>Start</button>
    </div>
  );
}

export default App;

Escalas de cores aplicadas a uma tabela de números de vendas, com sombreamento de laranja a amarelo pálido

Enquanto as barras de dados mostram magnitude absoluta por meio do comprimento da barra, as escalas de cores mostram posição relativa por meio da matiz. Um valor no meio do intervalo recebe um tom intermediário independentemente de o intervalo variar de 1 a 100 ou de 10.000 a 50.000 — o sombreamento é posicional, não absoluto.

Conjuntos de ícones: faixas de status

Um conjunto de ícones coloca um ícone diferente em cada célula com base em qual faixa o valor se enquadra. O exemplo usa três semáforos: vermelho para o terço mais baixo, amarelo para o meio, verde para o mais alto. Diferentemente das barras de dados e das escalas de cores, que comunicam um gradiente contínuo, os conjuntos de ícones comunicam uma categoria discreta — "isto é baixo", "isto é médio", "isto é alto" — o que está mais próximo de um indicador de status do que de uma medição.

Os passos diferem apenas no FormatType e na seleção do estilo do ícone:

1. Carregue a fonte e o arquivo de dados de teste no VFS.
2. Carregue a pasta de trabalho e obtenha a planilha.
3. Chame ConditionalFormats.Add para criar um formato condicional e vincule o intervalo de dados com AddRange.
4. Chame AddCondition para adicionar uma condição, defina FormatType como IconSet e especifique o tipo de conjunto de ícones.
5. Salve a pasta de trabalho.

function App() {
  const applyIconSets = async () => {
    // Get the Spire.XLS WASM module
    const xlsModule = window.wasmModule?.spirexls;

    // Check whether the module is ready
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // Load the font and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'SalesData.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // Load the workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });
    const sheet = workbook.Worksheets.get(0);

    // Select the data range that receives the icon sets
    const dataRange = sheet.Range.get("B2:E9");

    // Create a conditional format and bind it to that range
    const xcfs = sheet.ConditionalFormats.Add();
    xcfs.AddRange(dataRange);

    // Add an icon set condition and set the icon style to three traffic lights
    const format = xcfs.AddCondition();
    format.FormatType = xlsModule.ConditionalFormatType.IconSet;
    format.IconSet.IconSetType = xlsModule.IconSetType.ThreeTrafficLights1;

    // Save the workbook
    const outputFileName = "ApplyIconSets.xlsx";
    workbook.SaveToFile({ fileName: outputFileName, version: xlsModule.ExcelVersion.Version2010 });

    // Dispose of the workbook object to free resources
    workbook.Dispose();

    // Read the result file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Apply Icon Sets</h1>
      <button onClick={applyIconSets}>Start</button>
    </div>
  );
}

export default App;

Conjuntos de ícones aplicados a uma tabela de números de vendas, com ícones de semáforo com base nas faixas de valores

Um conjunto de ícones divide o intervalo em faixas, portanto o mesmo ícone cobre um intervalo diferente de valores em intervalos diferentes. Em um intervalo de 10 a 90, o ícone verde cobre aproximadamente 60 a 90; em um intervalo de 10 a 900, cobre aproximadamente 600 a 900. As faixas são relativas, não absolutas — o que é o padrão correto para uma tabela em que cada coluna tem sua própria escala, mas vale saber caso você espere um limite fixo.

Escolhendo entre os três

Todos os três são aplicados a um intervalo, todos os três ficam dentro das células e todos os três são formatação condicional. A escolha é sobre o que o leitor precisa fazer com os números:

Os três não são mutuamente exclusivos. Uma planilha pode conter barras de dados nas colunas de receita e conjuntos de ícones na coluna de taxa de crescimento na mesma gravação, porque cada chamada a ConditionalFormats.Add cria um formato independente vinculado ao seu próprio intervalo.

Personalizando a aparência das barras de dados

A cor de preenchimento de uma barra de dados vem de DataBar.BarColor. Definir apenas FormatType sem BarColor resulta no azul padrão. Uma borda também está disponível, mas tem uma dependência: o tipo de borda deve ser definido antes que a cor da borda entre em vigor.

// Set the border type first so that the border color takes effect
format.DataBar.BarBorder.Type = xlsModule.DataBarBorderType.DataBarBorderSolid;
format.DataBar.BarBorder.Color = xlsModule.Color.get_Red();

// Fill color of the bar
format.DataBar.BarColor = xlsModule.Color.get_GreenYellow();

Definir BarBorder.Color por si só, sem primeiro definir BarBorder.Type, não tem efeito — a borda não é desenhada porque nenhum tipo de borda foi declarado. Escalas de cores e conjuntos de ícones não têm propriedades de aparência equivalentes; seu estilo é determinado pelo tipo de formato e, para conjuntos de ícones, pela enumeração IconSetType.

Problemas comuns

Células de texto no intervalo de destino não mostram barras de dados. Isso é esperado. Uma barra de dados expressa magnitude relativa, e apenas células numéricas têm magnitude. Células de texto são ignoradas silenciosamente — nenhum erro, nenhuma barra. Mantenha o intervalo limitado à área numérica.

As barras de dados estão todas no azul padrão. DataBar.BarColor não foi definido após a atribuição de FormatType. Defina-o como qualquer valor de xlsModule.Color para alterar o preenchimento.

A cor da borda da barra de dados não está aparecendo. O tipo de borda não foi definido primeiro. Atribua DataBar.BarBorder.Type antes de DataBar.BarBorder.Color — a cor só entra em vigor depois que um tipo de borda sólida é declarado.

Nenhuma alteração visível após aplicar um formato condicional. Verifique se o intervalo passado para AddRange corresponde a onde os dados realmente estão. Um intervalo apontando para células vazias não produz erro nem resultado visível.

Perguntas frequentes

Posso aplicar mais de um formato condicional ao mesmo intervalo?

Sim. Cada chamada a ConditionalFormats.Add cria um formato independente. Dois formatos podem ter como alvo o mesmo intervalo, embora o resultado visual de empilhar uma barra de dados e uma escala de cores nas mesmas células possa ser confuso — geralmente é mais claro aplicar tipos diferentes a intervalos diferentes.

Quais versões do Excel suportam esses tipos de formato condicional?

Barras de dados, escalas de cores e conjuntos de ícones foram introduzidos no Excel 2007. O exemplo salva com ExcelVersion.Version2010 para garantir compatibilidade com o Excel 2010 e versões posteriores.

Preciso ter o Excel instalado para aplicar formatação condicional?

Não. O mecanismo de planilha é fornecido com o pacote e é executado como WebAssembly no navegador. A formatação condicional é gravada como XML padrão dentro do arquivo .xlsx, e o Excel a renderiza quando o arquivo é aberto.

Posso definir limites personalizados para conjuntos de ícones?

A enumeração IconSetType seleciona um estilo de ícone predefinido com limites de faixa predefinidos. O exemplo usa ThreeTrafficLights1, que divide o intervalo em três faixas iguais.

A formatação condicional sobrevive se o arquivo for aberto e salvo novamente no Excel?

Sim. A formatação condicional faz parte das regras de formato armazenadas da planilha, não um artefato de renderização. O Excel lê, preserva e reaplica as mesmas regras ao recalcular.

Veja também

• Integrando o Spire.XLS for JavaScript em um projeto React
• Página do produto Spire.XLS for JavaScript