Insertar formas de línea en Excel con JavaScript (React)

Una hoja de cálculo no siempre es solo una cuadrícula de números. A veces es un lienzo: un diagrama de flujo esbozado entre bloques de datos, un diagrama de relaciones que conecta equipos con proyectos, una llamada que señala desde una nota hasta la celda que anota. En todos estos casos, el elemento que falta es una línea: un trazo recto entre dos cuadros, un arco curvo alrededor de una región, un conector de codo que se dobla una vez y continúa.

Spire.XLS for JavaScript ofrece a una aplicación React el método sheet.Lines.AddLine() para insertar formas de línea en una posición especificada, con cuatro tipos de línea disponibles a través de la enumeración LineShapeType y control total sobre el estilo de guion, el color y el grosor. Todo se ejecuta en el navegador sobre WebAssembly: sin backend, sin automatización de Excel, sin carga de archivos.

Para la configuración del proyecto, consulte Integrar Spire.XLS for JavaScript en un proyecto de React. Los ejemplos a continuación asumen que el paquete está instalado y que el módulo WebAssembly se ha inicializado.

Cuándo una hoja de cálculo necesita líneas

Las líneas en una hoja de cálculo cumplen tres propósitos generales, y el tipo de línea que elija depende de cuál tenga delante:

El caso de la punta de flecha —donde la línea necesita mostrar dirección— usa una API diferente, TypedLines.AddLine(), que admite estilos de flecha en ambos extremos y un posicionamiento con precisión de píxeles. Eso se trata por separado en Añadir conectores de flecha en Excel en JavaScript (React). Este artículo se centra en Lines.AddLine(), que maneja las cuatro formas de línea principales y su estilo visual.

Requisitos previos

Necesita un proyecto React con Spire.XLS for JavaScript instalado y el módulo WebAssembly inicializado, accesible en window.wasmModule.spirexls. El ejemplo carga una fuente en el VFS para la medición de texto y guarda con el indicador de versión de Excel 2010.

Los cuatro tipos de líneas

LineShapeType expone cuatro formas, y la diferencia entre ellas es geométrica: cómo recorre la línea desde su inicio hasta su final:

Las cuatro se crean con el mismo método —sheet.Lines.AddLine()—, y el parámetro lineShapeType selecciona cuál se dibuja. Las propiedades de apariencia (DashStyle, Color, Weight) se aplican a las cuatro por igual.

Insertar líneas en una hoja de cálculo

El ejemplo inserta una de cada tipo de línea en una hoja de cálculo nueva, cada una con un estilo de guion y un color distintos para que las cuatro formas se distingan en el resultado. Los pasos son:

1. Cree un objeto Workbook y obtenga la primera hoja de cálculo.
2. Llame a Worksheet.Lines.AddLine() cuatro veces, pasando parámetros de posición y un LineShapeType diferente cada vez.
3. Personalice el DashStyle, Color y Weight de cada línea.
4. Guarde el libro con 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;

Cuatro tipos de líneas insertadas en una hoja de cálculo: recta, curva, de codo e invertida

La primera línea también establece EndArrowHeadStyle, lo que le da una punta de flecha al final; Lines.AddLine() admite un solo estilo de flecha al final, pero no al principio. Para flechas en ambos extremos o un posicionamiento con precisión de píxeles, use TypedLines.AddLine() en su lugar, tratado en Añadir conectores de flecha en Excel en JavaScript (React).

Personalizar la apariencia de las líneas

Tres propiedades controlan el aspecto de una línea, y son independientes: cambiar una no restablece las otras:

El estilo de guion es el que vale la pena experimentar. Una línea continua se interpreta como una conexión permanente; una línea punteada se interpreta como una conexión tentativa u opcional; una línea discontinua se interpreta como un límite. En un diagrama de flujo donde algunas conexiones son condicionales, usar Solid para el flujo principal y Dashed para las ramas condicionales comunica la distinción sin necesidad de una leyenda.

Posicionamiento por fila y columna

Lines.AddLine() coloca una línea usando coordenadas de fila y columna, además de un ancho y un alto:

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

• row y column establecen el punto de anclaje: donde comienza la línea.
• width establece la extensión horizontal en píxeles.
• height establece la extensión vertical en píxeles. Un alto de 1 produce una línea horizontal; un ancho de 1 produce una vertical.

Se trata de un sistema híbrido: el anclaje está en unidades de hoja de cálculo (filas y columnas), pero el tamaño está en píxeles. Eso hace que sea sencillo alinear una línea con una celda específica —pase la fila y la columna de esa celda—, pero la longitud debe tener en cuenta los anchos de columna y las alturas de fila, que varían. Si necesita un control total en píxeles sobre la posición inicial además del tamaño, TypedLines.AddLine() ofrece Top y Left en píxeles.

Problemas comunes

La línea no es visible en el resultado. Compruebe Weight y Color. Un grosor de 0 o un color que coincida con el fondo producen una línea invisible. Verifique también que row y column sitúen la línea dentro del rango usado de la hoja de cálculo: una línea anclada en la fila 1000 en una hoja vacía se dibuja, pero fuera de la pantalla.

Falta la punta de flecha. No se estableció EndArrowHeadStyle, o se estableció en LineNoArrow. Asigne ShapeArrowStyleType.LineArrow para mostrar una punta de flecha al final de la línea. Lines.AddLine() no admite BeginArrowHeadStyle; para flechas en ambos extremos, use TypedLines.AddLine().

La línea de codo va en una dirección inesperada. Un conector de codo se dobla una vez, y la dirección del doblez depende de los valores de width y height. Un ancho positivo con un alto positivo se dobla hacia abajo y a la derecha; cambiar el signo de cualquiera de los dos valores cambia la dirección del doblez. Experimente primero con valores pequeños para confirmar la forma antes de comprometerse con un diseño grande.

Las líneas se superponen o se apilan unas sobre otras. Cada llamada a AddLine crea una forma independiente en la posición especificada. Si dos líneas comparten la misma row y column, se superponen. Desplace el valor de row en 2 o más para cada línea sucesiva, como hace el ejemplo.

Preguntas frecuentes

¿Cuál es la diferencia entre Lines.AddLine() y TypedLines.AddLine()?

Lines.AddLine() posiciona por fila y columna y solo admite una punta de flecha al final. TypedLines.AddLine() posiciona por coordenadas de píxeles y admite puntas de flecha en ambos extremos. Para formas de línea básicas sin flechas direccionales, Lines.AddLine() es más sencillo. Para conectores que necesitan una ubicación precisa o flechas bidireccionales, consulte Añadir conectores de flecha en Excel en JavaScript (React).

¿Puedo crear una línea vertical?

Sí. Establezca width en 1 y height en un valor positivo. La línea se extiende hacia abajo desde el punto de anclaje.

¿Cuántas líneas puede contener una sola hoja de cálculo?

No hay un límite estricto en la API. Cada línea es un objeto de forma almacenado en la colección de formas de la hoja de cálculo, y la limitación práctica es el tamaño del archivo y el rendimiento de representación cuando hay cientos de formas.

¿Las líneas se conservan si el archivo se abre en Excel?

Sí. Las líneas se almacenan como objetos de forma estándar en el XML de la hoja de cálculo. Excel las lee y las representa de forma nativa: no son un artefacto de representación específico de Spire.XLS.

¿Puedo recuperar y modificar líneas que ya existen en un libro?

Sí. Recorra la colección sheet.Shapes para acceder a los objetos de forma de línea y, a continuación, modifique sus propiedades a través de la interfaz ILineShape. Para eliminarlas, use sheet.Shapes.Remove(index).

Véase también

• Añadir conectores de flecha en Excel en JavaScript (React)
• Integrar Spire.XLS for JavaScript en un proyecto de React
• Página del producto Spire.XLS for JavaScript