JavaScript(React)에서 Excel에 화살표 연결선 추가하기

순서도에서 두 상자 사이의 선은 "이 둘은 관련이 있다"는 의미입니다. 한쪽에서 다른 쪽으로 향하는 화살표는 "이쪽이 먼저다"라는 의미입니다. 바로 이 구분 — 방향 — 이 연결선과 장식을 나누는 기준이며, 기본 Lines.AddLine() API가 양쪽 끝에서 할 수 없는 유일한 것입니다. 프로세스 흐름은 각 단계에서 나가는 화살표가 필요하고, 인과 관계도는 화살표가 안쪽을 향해야 하며, 비교할 때는 양방향 연결을 나타내기 위해 양쪽 화살표가 필요한 경우도 있습니다. 이러한 것들은 단일 EndArrowHeadStyle로는 불가능합니다.

Spire.XLS for JavaScript는 바로 이러한 경우를 위해 sheet.TypedLines.AddLine()을 제공합니다. 이 메서드는 행과 열 대신 픽셀 좌표로 선의 위치를 지정하며, BeginArrowHeadStyle과 EndArrowHeadStyle을 각각 독립적으로 받아들이므로 한쪽 끝에만, 양쪽 끝에, 또는 어느 쪽에도 화살표가 없는 선을 만들 수 있습니다. 이 엔진은 브라우저에서 WebAssembly로 실행되며, 파일은 가상 파일 시스템(VFS)을 통해 이동하고 백엔드는 관여하지 않습니다.

프로젝트 설정에 대해서는 React 프로젝트에 Spire.XLS for JavaScript 통합하기를 참조하세요. 아래 예제는 패키지가 설치되어 있고 WebAssembly 모듈이 초기화되었다고 가정합니다.

방향이 모든 것을 바꿉니다

세 가지 다이어그램, 세 가지 서로 다른 방향 요구 사항이 있으며, 동일한 라인 API가 이 모두를 처리합니다:

화살촉 스타일 자체도 의미를 담고 있습니다. 채워진 화살표(LineArrow)는 확실하고 확정된 연결로 읽힙니다. 열린 화살표(LineArrowOpen)는 더 느슨하고 덜 확실한 연결로 읽히며, 방향은 알지만 메커니즘은 명시되지 않은 데이터 흐름도에서 흔히 사용됩니다.

사전 요구 사항

Spire.XLS for JavaScript가 설치되고 WebAssembly 모듈이 초기화된 React 프로젝트가 필요하며, window.wasmModule.spirexls에서 접근할 수 있어야 합니다. 예제에서는 VFS에 글꼴을 로드하고 Excel 2010 버전 플래그로 저장합니다.

TypedLines와 Lines: 무엇이 다른가

sheet.Lines.AddLine()과 sheet.TypedLines.AddLine()은 서로 다른 필요를 위한 두 개의 별도 API입니다. 차이는 겉모습이 아니라 구조적인 것입니다:

시작점 화살표 지원이 가장 중요한 차이입니다. Lines.AddLine()에서는 선의 끝에는 화살촉을 둘 수 있지만 시작점에는 둘 수 없으며, 이는 단방향 흐름에는 충분하지만 양방향 연결에는 충분하지 않습니다. TypedLines.AddLine()은 이러한 제약을 제거합니다.

화살표가 없는 기본 선 도형에 대해서는 JavaScript(React)에서 Excel에 선 도형 삽입하기에서 Lines.AddLine() API를 다룹니다.

픽셀 단위의 정밀한 위치 지정

TypedLines.AddLine()은 Top과 Left를 픽셀 단위로 사용하여 선을 배치하며, Width와 Height로 범위를 제어합니다:

let line = sheet.TypedLines.AddLine();
line.Top = 10;     // 10 pixels from the top of the sheet
line.Left = 20;    // 20 pixels from the left
line.Width = 100;  // 100 pixels wide
line.Height = 0;   // 0 height — a horizontal line

Height가 0이면 가로선이 되고, Width가 0이면 세로선이 됩니다. 둘 다 0이 아닌 값으로 설정하면 LineShapeType에 따라 대각선이나 꺾인 연결선이 만들어집니다.

행과 열에서 픽셀 좌표로의 전환은 선이 셀 경계에 맞춰지는 것이 아니라 셀 내부의 특정 지점 — 병합된 범위의 중앙, 테두리의 모서리 — 을 연결해야 할 때 가장 중요합니다. 픽셀 위치 지정을 사용하면 어느 행과 열이 가장 가까운지 추정하는 대신, 알고 있는 레이아웃에서 정확한 시작점과 끝점을 계산할 수 있습니다.

화살표 조합

BeginArrowHeadStyle과 EndArrowHeadStyle을 독립적으로 설정하면 네 가지 조합으로 일반적인 경우를 모두 포괄할 수 있습니다:

화살표 스타일은 양쪽 끝에서 채워진 삼각형이 아닌 열린 V자 모양인 LineArrowOpen일 수도 있습니다. 두 끝에 서로 다른 스타일을 섞는 것도 유효합니다. 한쪽 끝에 채워진 화살표를, 다른 쪽 끝에 열린 화살표를 두면 한 방향은 확정적이고 다른 방향은 잠정적임을 전달합니다.

화살표가 있는 선 삽입

이 예제는 일반적인 조합을 모두 포함하는 여섯 개의 화살표 선을 새 워크시트에 삽입합니다: 양방향 화살표 선, 단방향 화살표 선, 꺾인 화살표 연결선, 꺾인 양방향 화살표 연결선, 곡선 화살표 연결선, 곡선 양방향 화살표 연결선입니다. 단계는 다음과 같습니다:

1. Workbook 개체를 만들고 첫 번째 워크시트를 가져옵니다.
2. Worksheet.TypedLines.AddLine()을 호출하여 각 선을 만듭니다.
3. Top, Left, Width, Height(픽셀 단위)를 통해 선 위치를 설정합니다.
4. BeginArrowHeadStyle과 EndArrowHeadStyle을 통해 양쪽 끝의 화살표 스타일을 설정합니다.
5. LineShapeType(직선, 꺾인 선, 곡선 등)을 통해 선 유형을 지정합니다.
6. Workbook.SaveToFile()로 통합 문서를 저장합니다.

function App() {
  const addArrowLines = 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 double-arrow line - solid blue
    let line = sheet.TypedLines.AddLine();
    line.Top = 10;
    line.Left = 20;
    line.Width = 100;
    line.Height = 0;
    line.Color = xlsModule.Color.get_Blue();
    line.BeginArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;
    line.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;

    // Add a single-arrow line - solid red
    let line_1 = sheet.TypedLines.AddLine();
    line_1.Top = 50;
    line_1.Left = 30;
    line_1.Width = 100;
    line_1.Height = 100;
    line_1.Color = xlsModule.Color.get_Red();
    line_1.BeginArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineNoArrow;
    line_1.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;

    // Add an elbow arrow connector
    let line3 = sheet.TypedLines.AddLine();
    line3.LineShapeType = xlsModule.LineShapeType.ElbowLine;
    line3.Width = 30;
    line3.Height = 50;
    line3.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;
    line3.Top = 100;
    line3.Left = 50;

    // Add an elbow double-arrow connector
    let line2 = sheet.TypedLines.AddLine();
    line2.LineShapeType = xlsModule.LineShapeType.ElbowLine;
    line2.Width = 50;
    line2.Height = 50;
    line2.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;
    line2.BeginArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;
    line2.Left = 120;
    line2.Top = 100;

    // Add a curved arrow connector
    line3 = sheet.TypedLines.AddLine();
    line3.LineShapeType = xlsModule.LineShapeType.CurveLine;
    line3.Width = 30;
    line3.Height = 50;
    line3.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrowOpen;
    line3.Top = 100;
    line3.Left = 200;

    // Add a curved double-arrow connector
    line2 = sheet.TypedLines.AddLine();
    line2.LineShapeType = xlsModule.LineShapeType.CurveLine;
    line2.Width = 30;
    line2.Height = 50;
    line2.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrowOpen;
    line2.BeginArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrowOpen;
    line2.Left = 250;
    line2.Top = 100;

    // Save the workbook
    const outputFileName = 'AddArrowLines.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 Arrow Lines</h1>
      <button onClick={addArrowLines}>Start</button>
    </div>
  );
}

export default App;

여섯 개의 화살표 선: 양방향 화살표, 단방향 화살표, 꺾인 화살표, 꺾인 양방향 화살표, 곡선 화살표, 곡선 양방향 화살표

함수 후반부에서 line3와 line2 변수를 재사용한 점에 주목하세요. TypedLines.AddLine()을 호출할 때마다 이미 워크시트에 추가된 새로운 선 개체가 반환됩니다. 즉, 변수는 속성을 설정하기 위한 핸들일 뿐이며 보존해야 하는 컨테이너가 아닙니다. 이전 선은 이미 시트의 도형 컬렉션에 반영되어 있으므로 다음 선을 위해 변수 이름을 재사용해도 안전합니다.

기존 선 관리

여러분의 코드로 추가되었든, 파일에서 가져왔든, 사용자가 그렸든 이미 선이 포함된 워크시트는 sheet.Shapes 컬렉션을 통해 이를 노출합니다. 각 도형은 인덱스로 가져올 수 있고 속성을 통해 수정할 수 있습니다:

// Get the first shape in the worksheet
let shape = sheet.Shapes.get(0);
// Modify its properties — color, dash style, etc.
shape.Color = xlsModule.Color.get_Red();

삭제의 경우 sheet.Shapes.Remove(index)가 지정된 인덱스의 도형을 제거합니다. 이름, 유형 또는 위치별로 선을 선택적으로 제거하려면 컬렉션을 반복하면서 일치하는 도형을 제거하세요. 루프에서 삭제할 때는 마지막 인덱스부터 아래로 제거해야 합니다. 요소를 제거하면 그 뒤에 있는 모든 요소의 인덱스가 이동하기 때문입니다.

일반적인 문제

화살촉이 표시되지 않습니다. BeginArrowHeadStyle 또는 EndArrowHeadStyle이 설정되지 않았거나 LineNoArrow로 설정되었습니다. 화살표가 있어야 할 끝이 어느 쪽인지 확인하고 해당 속성을 할당하세요. 두 속성 모두 설정되지 않은 선은 양쪽 끝에 화살표가 없습니다.

선이 잘못된 위치에 나타납니다. Top과 Left는 행과 열이 아니라 픽셀 단위입니다. Top = 10이라는 값은 선을 10번째 행이 아니라 시트 위쪽에서 10픽셀 위치에 배치합니다. Lines.AddLine() API에 익숙하다면 이것이 가장 흔한 위치 오류의 원인입니다.

꺾인 연결선이 잘못된 방향으로 꺾입니다. 꺾이는 방향은 Width와 Height의 부호와 상대적 크기에 따라 달라집니다. 양수 Width와 양수 Height는 오른쪽 아래로 꺾입니다. 부호를 바꾸거나 두 값을 서로 바꾸어 꺾임을 변경하세요. 먼저 작은 값으로 테스트해 보세요.

곡선이 예상한 대로 휘어지지 않습니다. TypedLines를 통한 CurveLine은 시작점과 끝점 사이에 부드러운 호를 그리며, 호의 모양은 Width와 Height의 영향을 받습니다. 직각으로 한 번 꺾이는 꺾인 연결선과 달리 곡선은 연속적이지만, 정확한 경로는 크기에 따라 달라지므로 정밀한 레이아웃에 의존하기 전에 결과를 확인하세요.

FAQ

LineArrow와 LineArrowOpen의 차이는 무엇인가요?

LineArrow는 채워진 삼각형 화살촉을 그립니다. LineArrowOpen은 채움 없이 두 개의 획으로 이루어진 열린 V자 화살촉을 그립니다. 열린 스타일은 화살표가 특정 메커니즘을 암시하지 않고 방향만 나타내는 데이터 흐름도와 개체-관계 다이어그램에서 흔히 사용됩니다.

양쪽 끝에 서로 다른 화살표 스타일을 설정할 수 있나요?

네. BeginArrowHeadStyle과 EndArrowHeadStyle은 독립적인 속성입니다. 한쪽 끝에 LineArrow를, 다른 쪽 끝에 LineArrowOpen을 사용한 선은 유효하며, 한 방향은 확정적이고 다른 방향은 잠정적임을 전달합니다.

픽셀 좌표는 워크시트 레이아웃과 어떻게 관련되나요?

픽셀 좌표는 워크시트의 왼쪽 위 모서리에서 측정됩니다. Excel의 행 높이는 포인트로, 열 너비는 문자 수로 측정되므로, 셀 위치와 픽셀 좌표 사이를 변환하려면 현재 행 높이와 열 너비를 고려해야 합니다. 셀 경계에 맞춰야 하는 선에는 행과 열 매개변수를 사용하는 Lines.AddLine()이 더 간단할 수 있습니다.

같은 워크시트에서 Lines.AddLine()과 TypedLines.AddLine()을 함께 사용할 수 있나요?

네. 두 API 모두 동일한 워크시트의 도형 컬렉션에 도형을 추가합니다. 하나의 워크시트에 기본 선 도형과 화살표가 있는 선을 동시에 포함할 수 있습니다.

Excel이 설치되어 있어야 하나요?

아니요. 이 엔진은 브라우저에서 WebAssembly로 실행됩니다. 선과 화살표는 워크시트 XML에 표준 도형 개체로 기록되며, 파일을 열면 Excel이 기본적으로 렌더링합니다.

관련 항목

• JavaScript(React)에서 Excel에 선 도형 삽입하기
• React 프로젝트에 Spire.XLS for JavaScript 통합하기
• Spire.XLS for JavaScript 제품 페이지