@bwg-lsu/bwg-itam-canvas

React + Ant Design 기반의 ITAM(인프라 자산) 도면 편집 캔버스 컴포넌트입니다. 구역(area) / 랙(rack) / 텍스트(text) 배치, 배경(grid / 이미지), 확대/축소, 이동, 히스토리(Undo/Redo), 속성 편집 등을 제공합니다.

설치

peerDependencies를 앱에서 함께 설치해야 합니다.

npm i @bwg-lsu/bwg-itam-canvas antd @ant-design/icons react-konva konva
# (프로젝트에 없다면) React도 설치
npm i react react-dom

Ant Design v5를 사용한다면 전역 reset CSS를 함께 적용하는 것을 권장합니다.

// 예) src/main.tsx 또는 앱 엔트리에서
import 'antd/dist/reset.css';

빠른 시작

아래 예시는 src/App.tsx를 단순화한 형태로, BwgItamCanvas를 렌더링하고 JSON으로 저장/불러오기, 신규 생성 흐름을 보여줍니다.

import React, { useRef } from 'react';
import { App as AntdApp, Button, Space, Tooltip } from 'antd';
import { SaveOutlined, FolderOpenOutlined, FileOutlined } from '@ant-design/icons';
import BwgItamCanvas from '@bwg-lsu/bwg-itam-canvas';
import type { CanvasData, BwgItamCanvasRef } from '@bwg-lsu/bwg-itam-canvas';

export default function MyCanvasPage() {
  const canvasRef = useRef<BwgItamCanvasRef | null>(null);
  const { message, modal } = AntdApp.useApp();

  const handleSaveData = () => {
    const data = canvasRef.current?.getCanvasData();
    if (!data) return message.error('캔버스 데이터를 가져올 수 없습니다.');

    const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = `bwg-itam-canvas-${Date.now()}.json`;
    a.click();
    URL.revokeObjectURL(url);
    message.success('데이터가 저장되었습니다.');
  };

  const handleNewCanvas = () => {
    modal.confirm({
      title: '새 캔버스 생성',
      content: '현재 작업 중인 내용이 모두 삭제됩니다. 계속하시겠습니까?',
      okText: '새로 만들기',
      cancelText: '취소',
      onOk: () => {
        const empty: CanvasData = {
          objects: [],
          backgroundSettings: {
            type: 'grid',
            gridSettings: {
              size: 'default',
              customWidth: 1000,
              customHeight: 1000,
              backgroundColor: '#ffffff',
              lineColor: '#e0e0e0',
              subLineColor: '#f0f0f0',
            },
            imageSettings: { url: undefined, scale: 1, opacity: 1 },
          },
          metadata: { version: '1.0.0', savedAt: 0 },
        };
        canvasRef.current?.setCanvasData(empty);
        message.success('새 캔버스가 생성되었습니다.');
      },
    });
  };

  const handleLoadData = () => {
    const input = document.createElement('input');
    input.type = 'file';
    input.accept = '.json';
    input.onchange = (e) => {
      const file = (e.target as HTMLInputElement).files?.[0];
      if (!file) return;
      const reader = new FileReader();
      reader.onload = () => {
        try {
          const data = JSON.parse(reader.result as string) as CanvasData;
          canvasRef.current?.setCanvasData(data);
          message.success('데이터가 성공적으로 로드되었습니다.');
        } catch {
          message.error('데이터 불러오기에 실패했습니다. 파일 형식을 확인해주세요.');
        }
      };
      reader.readAsText(file);
    };
    input.click();
  };

  return (
    <AntdApp>
      <div style={{ marginBottom: 16, display: 'flex', justifyContent: 'flex-end', padding: '0 10px' }}>
        <Space size="middle">
          <Tooltip title="새 캔버스 생성">
            <Button icon={<FileOutlined />} onClick={handleNewCanvas}>신규</Button>
          </Tooltip>
          <Tooltip title="데이터 불러오기">
            <Button icon={<FolderOpenOutlined />} onClick={handleLoadData}>데이터 불러오기</Button>
          </Tooltip>
          <Tooltip title="데이터를 JSON으로 저장">
            <Button icon={<SaveOutlined />} onClick={handleSaveData}>데이터 저장</Button>
          </Tooltip>
        </Space>
      </div>

      <BwgItamCanvas ref={canvasRef} />
    </AntdApp>
  );
}

주의: 상위 트리 어딘가에 Ant Design의 App(AntdApp) 컨텍스트가 있어야 메시지/모달을 쉽게 쓸 수 있습니다. 컴포넌트 내부는 자체 ConfigProvider를 사용하여 테마를 적용합니다.

Ref API

BwgItamCanvas는 forwardRef로 다음 메서드를 제공합니다.

• getCanvasData: 현재 상태를 CanvasData로 반환
• setCanvasData: 전달한 CanvasData로 상태 초기화

import type { BwgItamCanvasRef, CanvasData } from '@bwg/itam-canvas';
const ref = useRef<BwgItamCanvasRef | null>(null);
const data: CanvasData | undefined = ref.current?.getCanvasData();
ref.current?.setCanvasData(data!);

데이터 스키마 개요

CanvasData는 배경 설정과 객체 목록을 포함합니다. 세부 타입은 패키지 타입 정의를 참고하세요.

interface CanvasData {
  objects: ComponentObject[];
  backgroundSettings: {
    type: 'grid' | 'image';
    gridSettings: {
      size: 'default' | 'custom';
      customWidth?: number;
      customHeight?: number;
      backgroundColor: string;
      lineColor: string;
      subLineColor: string;
    };
    imageSettings: {
      url?: string;
      filename?: string | null;
      scale: number;
      opacity: number;
    };
  };
  metadata: { version: string; savedAt: number };
}

사용 팁

• 배경 설정 모달: 컴포넌트 상단 UI에서 배경(Grid/Image), 그리드 크기/색상, 이미지 URL/스케일/투명도 등을 설정할 수 있습니다.
• 확대/축소/맞춤: 툴바에서 확대/축소(+1%/+10%), 배경 맞춤, 캔버스 중앙정렬을 제공합니다.
• 객체 편집: 좌측(또는 하단) 속성 패널에서 선택된 객체의 색상/테두리/폰트/슬롯(RACK) 등을 수정할 수 있습니다.
• Undo/Redo/복사/삭제/전체삭제: 캔버스 컨트롤에서 제공됩니다.

요구 사항

• React 18+
• Ant Design 5+
• react-konva 19+, konva 9+

peerDependencies에 선언되어 있으므로, 호스트 앱에서 해당 패키지를 설치해야 합니다.

라이선스

MIT License. 자세한 내용은 LICENSE 파일을 참고하세요. Copyright (c) 2025 BankwareGlobal