Вставка линий (фигур) в Excel на JavaScript (React)

Лист — это не всегда просто сетка чисел. Иногда это холст — блок-схема, набросанная между блоками данных, диаграмма связей, соединяющая команды с проектами, выноска, указывающая от примечания к ячейке, которую оно поясняет. Во всех этих случаях недостающий элемент — это линия: прямая черта между двумя блоками, изогнутая дуга вокруг области, угловой соединитель, который один раз изгибается и продолжается.

Spire.XLS for JavaScript предоставляет React-приложению метод sheet.Lines.AddLine() для вставки фигур-линий в заданной позиции, с четырьмя типами линий, доступными через перечисление LineShapeType, и полным контролем над стилем штриха, цветом и толщиной. Всё работает в браузере на WebAssembly — без серверной части, без автоматизации Excel, без загрузки файлов.

По настройке проекта см. Интеграция Spire.XLS for JavaScript в проект React. Приведённые ниже примеры предполагают, что пакет установлен, а модуль WebAssembly инициализирован.

Когда на листе нужны линии

Линии на листе служат трём основным целям, и выбор типа линии зависит от того, с какой из них вы имеете дело:

Случай со стрелкой — когда линия должна показывать направление — использует другой API, TypedLines.AddLine(), который поддерживает стили стрелок на обоих концах и позиционирование с точностью до пикселя. Это рассматривается отдельно в статье Добавление соединителей со стрелками в Excel на JavaScript (React). Данная статья посвящена Lines.AddLine(), который работает с четырьмя основными формами линий и их визуальным оформлением.

Предварительные требования

Вам нужен проект React с установленным Spire.XLS for JavaScript и инициализированным модулем WebAssembly, доступным по адресу window.wasmModule.spirexls. Пример загружает шрифт в VFS для измерения текста и сохраняет файл с флагом версии Excel 2010.

Четыре типа линий

LineShapeType предоставляет четыре фигуры, и разница между ними геометрическая — как линия проходит от начала до конца:

Все четыре создаются одним и тем же методом — sheet.Lines.AddLine() — при этом параметр lineShapeType определяет, какая именно будет нарисована. Свойства внешнего вида (DashStyle, Color, Weight) применяются ко всем четырём одинаково.

Вставка линий на лист

В примере на новый лист вставляется по одной линии каждого типа, каждая с отдельным стилем штриха и цветом, чтобы четыре фигуры различались в выводе. Шаги следующие:

1. Создайте объект Workbook и получите первый лист.
2. Вызовите Worksheet.Lines.AddLine() четыре раза, передавая параметры позиции и каждый раз другой LineShapeType.
3. Настройте DashStyle, Color и Weight для каждой линии.
4. Сохраните книгу с помощью 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;

Четыре типа линий, вставленных на лист: прямая, изогнутая, угловая и инвертированная

Первая линия также задаёт EndArrowHeadStyle, что добавляет ей стрелку на конце — Lines.AddLine() поддерживает один стиль стрелки на конце, но не в начале. Для стрелок на обоих концах или позиционирования с точностью до пикселя используйте вместо этого TypedLines.AddLine(), что рассматривается в статье Добавление соединителей со стрелками в Excel на JavaScript (React).

Настройка внешнего вида линий

Внешний вид линии определяют три свойства, и они независимы — изменение одного не сбрасывает остальные:

Стиль штриха — то, с чем стоит экспериментировать. Сплошная линия воспринимается как постоянная связь; пунктирная линия — как предварительная или необязательная; штриховая линия — как граница. В блок-схеме, где некоторые связи условны, использование Solid для основного потока и Dashed для условных ветвей передаёт это различие без легенды.

Позиционирование по строке и столбцу

Lines.AddLine() размещает линию, используя координаты строки и столбца, а также ширину и высоту:

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

• row и column задают точку привязки — место начала линии.
• width задаёт горизонтальную протяжённость в пикселях.
• height задаёт вертикальную протяжённость в пикселях. Высота 1 даёт горизонтальную линию; ширина 1 даёт вертикальную.

Это гибридная система: привязка задаётся в единицах таблицы (строки и столбцы), а размер — в пикселях. Это упрощает выравнивание линии по конкретной ячейке — передайте строку и столбец этой ячейки — но при определении длины нужно учитывать ширину столбцов и высоту строк, которые различаются. Если вам нужен полный пиксельный контроль как над начальной позицией, так и над размером, TypedLines.AddLine() предлагает Top и Left в пикселях.

Типичные проблемы

Линия не видна в выводе. Проверьте Weight и Color. Толщина 0 или цвет, совпадающий с фоном, делают линию невидимой. Также убедитесь, что row и column размещают линию в пределах используемого диапазона листа — линия, привязанная к строке 1000 на пустом листе, рисуется, но оказывается за пределами экрана.

Отсутствует стрелка. Свойство EndArrowHeadStyle не задано или установлено в LineNoArrow. Присвойте ShapeArrowStyleType.LineArrow, чтобы показать стрелку на конце линии. Lines.AddLine() не поддерживает BeginArrowHeadStyle — для стрелок на обоих концах используйте TypedLines.AddLine().

Угловая линия идёт в неожиданном направлении. Угловой соединитель изгибается один раз, и направление изгиба зависит от значений width и height. Положительная ширина с положительной высотой даёт изгиб вниз-вправо; изменение знака любого из значений меняет направление изгиба. Сначала поэкспериментируйте с небольшими значениями, чтобы убедиться в форме, прежде чем переходить к большому макету.

Линии перекрываются или накладываются друг на друга. Каждый вызов AddLine создаёт независимую фигуру в указанной позиции. Если две линии имеют одинаковые row и column, они перекрываются. Смещайте значение row на 2 или более для каждой последующей линии, как это сделано в примере.

Часто задаваемые вопросы

В чём разница между Lines.AddLine() и TypedLines.AddLine()?

Lines.AddLine() позиционирует по строке и столбцу и поддерживает стрелку только на конце. TypedLines.AddLine() позиционирует по пиксельным координатам и поддерживает стрелки на обоих концах. Для базовых форм линий без направляющих стрелок Lines.AddLine() проще. Для соединителей, которым нужно точное размещение или двунаправленные стрелки, см. Добавление соединителей со стрелками в Excel на JavaScript (React).

Можно ли создать вертикальную линию?

Да. Задайте width равным 1, а height — положительным значением. Линия простирается вниз от точки привязки.

Сколько линий может содержать один лист?

В API нет жёсткого ограничения. Каждая линия — это объект-фигура, хранящийся в коллекции фигур листа, а практическое ограничение — размер файла и производительность отрисовки при наличии сотен фигур.

Сохранятся ли линии, если файл открыть в Excel?

Да. Линии хранятся как стандартные объекты-фигуры в XML листа. Excel читает и отображает их нативно — это не артефакт отрисовки, специфичный для Spire.XLS.

Можно ли получить и изменить линии, уже существующие в книге?

Да. Пройдите по коллекции sheet.Shapes, чтобы получить доступ к объектам-фигурам линий, затем измените их свойства через интерфейс ILineShape. Для удаления используйте sheet.Shapes.Remove(index).

См. также

• Добавление соединителей со стрелками в Excel на JavaScript (React)
• Интеграция Spire.XLS for JavaScript в проект React
• Страница продукта Spire.XLS for JavaScript