Inserir Formas de Linha no Excel em JavaScript (React)

Uma planilha nem sempre é apenas uma grade de números. Às vezes, ela é uma tela — um fluxograma esboçado entre blocos de dados, um diagrama de relacionamento conectando equipes a projetos, uma chamada apontando de uma nota para a célula que ela anota. Em cada um desses casos, o elemento que falta é uma linha: um traço reto entre duas caixas, um arco curvo ao redor de uma região, um conector em cotovelo que dobra uma vez e continua.

Spire.XLS for JavaScript oferece a um aplicativo React o método sheet.Lines.AddLine() para inserir formas de linha em uma posição especificada, com quatro tipos de linha disponíveis por meio do enum LineShapeType e controle total sobre estilo de traço, cor e espessura. Tudo é executado no navegador via WebAssembly — sem backend, sem automação do Excel, sem upload de arquivo.

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

Quando uma planilha precisa de linhas

Linhas em uma planilha atendem a três propósitos amplos, e o tipo de linha que você escolhe depende de qual deles está diante de você:

O caso da ponta de seta — em que a linha precisa mostrar direção — usa uma API diferente, TypedLines.AddLine(), que oferece suporte a estilos de seta nas duas extremidades e posicionamento com precisão de pixels. Isso é abordado separadamente em Adicionar conectores de seta no Excel em JavaScript (React). Este artigo concentra-se em Lines.AddLine(), que lida com as quatro formas de linha principais e sua estilização visual.

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 no VFS para medição de texto e salva com o sinalizador de versão do Excel 2010.

Os quatro tipos de linha

LineShapeType expõe quatro formas, e a diferença entre elas é geométrica — como a linha percorre do início ao fim:

Todas as quatro são criadas pelo mesmo método — sheet.Lines.AddLine() — com o parâmetro lineShapeType selecionando qual delas é desenhada. As propriedades de aparência (DashStyle, Color, Weight) aplicam-se uniformemente a todas as quatro.

Inserir linhas em uma planilha

O exemplo insere um de cada tipo de linha em uma nova planilha, cada uma com um estilo de traço e cor distintos para que as quatro formas sejam distinguíveis na saída. As etapas são:

1. Crie um objeto Workbook e obtenha a primeira planilha.
2. Chame Worksheet.Lines.AddLine() quatro vezes, passando parâmetros de posição e um LineShapeType diferente a cada vez.
3. Personalize DashStyle, Color e Weight de cada linha.
4. Salve a pasta de trabalho com Workbook.SaveToFile().

function App() {
  const addLineShapes = 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 into the VFS for text measurement and column auto-fit
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    // Create a new workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    const sheet = workbook.Worksheets.get(0);

    // Add a straight line - solid, CadetBlue, weight 2, with arrow
    let line1 = sheet.Lines.AddLine({ row: 10, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.Line });
    line1.DashStyle = xlsModule.ShapeDashLineStyleType.Solid;
    line1.Color = xlsModule.Color.get_CadetBlue();
    line1.Weight = 2;
    line1.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;

    // Add a curved line - dotted, OrangeRed, weight 2
    let line2 = sheet.Lines.AddLine({ row: 12, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.CurveLine });
    line2.DashStyle = xlsModule.ShapeDashLineStyleType.Dotted;
    line2.Color = xlsModule.Color.get_OrangeRed();
    line2.Weight = 2;

    // Add an elbow connector - DashDotDot, Purple, weight 2
    let line3 = sheet.Lines.AddLine({ row: 14, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.ElbowLine });
    line3.DashStyle = xlsModule.ShapeDashLineStyleType.DashDotDot;
    line3.Color = xlsModule.Color.get_Purple();
    line3.Weight = 2;

    // Add an inverted line - Dashed, Green, weight 2
    let line4 = sheet.Lines.AddLine({ row: 16, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.LineInv });
    line4.DashStyle = xlsModule.ShapeDashLineStyleType.Dashed;
    line4.Color = xlsModule.Color.get_Green();
    line4.Weight = 2;

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

    // Release resources
    workbook.Dispose();

    // Read the saved 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>Add Line Shapes</h1>
      <button onClick={addLineShapes}>Start</button>
    </div>
  );
}

export default App;

Quatro tipos de linha inseridos em uma planilha: reta, curva, em cotovelo e invertida

A primeira linha também define EndArrowHeadStyle, o que lhe dá uma ponta de seta no final — Lines.AddLine() oferece suporte a um único estilo de seta no final, mas não no início. Para setas nas duas extremidades ou posicionamento com precisão de pixels, use TypedLines.AddLine(), abordado em Adicionar conectores de seta no Excel em JavaScript (React).

Personalizar a aparência da linha

Três propriedades controlam a aparência de uma linha, e elas são independentes — alterar uma não redefine as outras:

O estilo de traço é o que vale a pena experimentar. Uma linha sólida é lida como uma conexão permanente; uma linha pontilhada é lida como provisória ou opcional; uma linha tracejada é lida como um limite. Em um fluxograma em que algumas conexões são condicionais, usar Solid para o fluxo principal e Dashed para os ramos condicionais comunica a distinção sem uma legenda.

Posicionamento por linha e coluna

Lines.AddLine() posiciona uma linha usando coordenadas de linha e coluna, além de largura e altura:

sheet.Lines.AddLine({ row: 10, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.Line });

• row e column definem o ponto de ancoragem — onde a linha começa.
• width define a extensão horizontal em pixels.
• height define a extensão vertical em pixels. Uma altura de 1 produz uma linha horizontal; uma largura de 1 produz uma vertical.

Este é um sistema híbrido: a âncora está em unidades da planilha (linhas e colunas), mas o tamanho está em pixels. Isso torna simples alinhar uma linha a uma célula específica — passe a linha e a coluna dessa célula — mas o comprimento precisa considerar as larguras das colunas e as alturas das linhas, que variam. Se você precisar de controle total em pixels sobre a posição inicial, bem como o tamanho, TypedLines.AddLine() oferece Top e Left em pixels.

Problemas comuns

A linha não está visível na saída. Verifique Weight e Color. Um peso 0 ou uma cor que corresponde ao fundo produz uma linha invisível. Também verifique se row e column colocam a linha dentro do intervalo usado da planilha — uma linha ancorada na linha 1000 em uma planilha vazia é desenhada, mas fora da tela.

A ponta de seta está ausente. EndArrowHeadStyle não foi definido, ou foi definido como LineNoArrow. Atribua ShapeArrowStyleType.LineArrow para mostrar uma ponta de seta no final da linha. Lines.AddLine() não oferece suporte a BeginArrowHeadStyle — para setas nas duas extremidades, use TypedLines.AddLine().

A linha em cotovelo vai em uma direção inesperada. Um conector em cotovelo dobra uma vez, e a direção da dobra depende dos valores de width e height. Uma largura positiva com uma altura positiva dobra para baixo e para a direita; alterar o sinal de qualquer um dos valores muda a direção da dobra. Experimente com valores pequenos primeiro para confirmar a forma antes de partir para um layout grande.

As linhas se sobrepõem ou se empilham umas sobre as outras. Cada chamada a AddLine cria uma forma independente na posição especificada. Se duas linhas compartilham a mesma row e column, elas se sobrepõem. Desloque o valor de row em 2 ou mais para cada linha sucessiva, como o exemplo faz.

Perguntas frequentes

Qual é a diferença entre Lines.AddLine() e TypedLines.AddLine()?

Lines.AddLine() posiciona por linha e coluna e oferece suporte a uma ponta de seta apenas no final. TypedLines.AddLine() posiciona por coordenadas em pixels e oferece suporte a pontas de seta nas duas extremidades. Para formas de linha básicas sem setas direcionais, Lines.AddLine() é mais simples. Para conectores que precisam de posicionamento preciso ou setas bidirecionais, consulte Adicionar conectores de seta no Excel em JavaScript (React).

Posso criar uma linha vertical?

Sim. Defina width como 1 e height como um valor positivo. A linha se estende para baixo a partir do ponto de ancoragem.

Quantas linhas uma única planilha pode conter?

Não há um limite rígido na API. Cada linha é um objeto de forma armazenado na coleção de formas da planilha, e a restrição prática é o tamanho do arquivo e o desempenho de renderização quando centenas de formas estão presentes.

As linhas são preservadas se o arquivo for aberto no Excel?

Sim. As linhas são armazenadas como objetos de forma padrão no XML da planilha. O Excel as lê e renderiza nativamente — não são um artefato de renderização específico do Spire.XLS.

Posso recuperar e modificar linhas que já existem em uma pasta de trabalho?

Sim. Percorra a coleção sheet.Shapes para acessar objetos de forma de linha e, em seguida, modifique suas propriedades por meio da interface ILineShape. Para exclusão, use sheet.Shapes.Remove(index).

Veja também

• Adicionar conectores de seta no Excel em JavaScript (React)
• Integrando o Spire.XLS for JavaScript em um projeto React
• Página do produto Spire.XLS for JavaScript