JavaScript(React)로 Excel에 선 도형 삽입

워크시트는 항상 숫자 그리드만 있는 것은 아닙니다. 때로는 캔버스입니다. 데이터 블록 사이에 스케치된 순서도, 팀을 프로젝트에 연결하는 관계 다이어그램, 노트에서 주석이 달린 셀을 가리키는 콜아웃 등이 있습니다. 이 모든 경우에 빠진 요소는 선입니다. 두 상자 사이의 직선, 영역 주위의 곡선 호, 한 번 구부러지고 계속되는 엘보 커넥터 등이 있습니다.

Spire.XLS for JavaScript는 React 앱에 sheet.Lines.AddLine() 메서드를 제공하여 지정된 위치에 선 도형을 삽입할 수 있으며, LineShapeType 열거형을 통해 네 가지 선 유형을 사용할 수 있고 대시 스타일, 색상 및 두께를 완전히 제어할 수 있습니다. 모든 것이 브라우저에서 WebAssembly로 실행됩니다. 백엔드, Excel 자동화, 파일 업로드가 필요 없습니다.

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

워크시트에 선이 필요할 때

워크시트의 선은 크게 세 가지 목적을 수행하며, 어떤 선 유형을 선택할지는 앞에 놓인 목적에 따라 달라집니다:

화살표가 있는 경우(선이 방향을 표시해야 하는 경우)는 다른 API인 TypedLines.AddLine()을 사용하며, 양쪽 끝에 화살표 스타일을 지원하고 픽셀 단위로 정확한 위치 지정이 가능합니다. 이는 JavaScript(React)에서 Excel에 화살표 커넥터 추가에서 별도로 다룹니다. 이 문서는 네 가지 핵심 선 모양과 시각적 스타일을 처리하는 Lines.AddLine()에 중점을 둡니다.

필수 조건

Spire.XLS for JavaScript가 설치되고 WebAssembly 모듈이 초기화된 React 프로젝트가 필요하며, 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()을 사용하며, 이는 JavaScript(React)에서 Excel에 화살표 커넥터 추가에서 다룹니다.

선 모양 사용자 지정

선의 모양을 제어하는 세 가지 속성이 있으며, 이들은 독립적입니다. 하나를 변경해도 다른 속성이 재설정되지 않습니다:

대시 스타일은 실험해 볼 가치가 있습니다. 실선은 영구적인 연결로 읽히고, 점선은 임시적이거나 선택적인 연결로 읽히며, 파선은 경계로 읽힙니다. 일부 연결이 조건부인 순서도에서 주요 흐름에는 Solid를, 조건부 분기에는 Dashed를 사용하면 범례 없이도 구분을 전달할 수 있습니다.

행과 열로 위치 지정

Lines.AddLine()은 행과 열 좌표, 그리고 너비와 높이를 사용하여 선을 배치합니다:

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

• row와 column은 앵커 포인트(선이 시작되는 위치)를 설정합니다.
• width는 가로 범위를 픽셀 단위로 설정합니다.
• height는 세로 범위를 픽셀 단위로 설정합니다. height가 1이면 가로선이 생성되고, width가 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 이상씩 오프셋하세요.

FAQ

Lines.AddLine()과 TypedLines.AddLine()의 차이점은 무엇인가요?

Lines.AddLine()은 행과 열로 위치를 지정하고 끝에만 화살촉을 지원합니다. TypedLines.AddLine()은 픽셀 좌표로 위치를 지정하고 양쪽 끝에 화살촉을 지원합니다. 방향 화살표가 없는 기본 선 모양에는 Lines.AddLine()이 더 간단합니다. 정밀한 배치나 양방향 화살표가 필요한 커넥터는 JavaScript(React)에서 Excel에 화살표 커넥터 추가를 참조하세요.

세로선을 만들 수 있나요?

예. width를 1로 설정하고 height를 양수로 설정하세요. 선은 앵커 포인트에서 아래쪽으로 확장됩니다.

단일 워크시트에 몇 개의 선을 넣을 수 있나요?

API에는 엄격한 제한이 없습니다. 각 선은 워크시트의 도형 컬렉션에 저장되는 도형 객체이며, 실제 제약은 수백 개의 도형이 있을 때 파일 크기와 렌더링 성능입니다.

파일을 Excel에서 열면 선이 유지되나요?

예. 선은 워크시트 XML에 표준 도형 객체로 저장됩니다. Excel은 이를 기본적으로 읽고 렌더링합니다. 이는 Spire.XLS에 특정된 렌더링 결과물이 아닙니다.

통합 문서에 이미 존재하는 선을 검색하고 수정할 수 있나요?

예. sheet.Shapes 컬렉션을 순회하여 선 도형 객체에 액세스한 다음 ILineShape 인터페이스를 통해 해당 속성을 수정합니다. 삭제하려면 sheet.Shapes.Remove(index)를 사용하세요.

참조 항목

• JavaScript(React)에서 Excel에 화살표 커넥터 추가
• React 프로젝트에 Spire.XLS for JavaScript 통합
• Spire.XLS for JavaScript 제품 페이지