FAQ

일반

Graphic Walker란 무엇인가요?

Graphic Walker는 인터랙티브 데이터 시각화를 위한 오픈소스 React 컴포넌트입니다. 그래픽 문법 접근 방식을 기반으로 차트를 구축할 수 있는 Tableau과 유사한 드래그 앤 드롭 인터페이스를 제공합니다. 기존 BI 플랫폼과 달리 React(또는 모든 웹) 애플리케이션에 직접 임베드할 수 있습니다.

Graphic Walker는 어떤 라이선스를 사용하나요?

Graphic Walker는 Apache-2.0 라이선스 (opens in a new tab)로 배포됩니다.

어떤 브라우저를 지원하나요?

Graphic Walker는 모든 최신 브라우저에서 동작합니다: Chrome, Firefox, Safari, Edge (최신 두 버전). Internet Explorer는 지원되지 않습니다.

번들 크기는 얼마인가요?

@kanaries/graphic-walker 패키지는 약 1.5MB (Vega-Lite 렌더링 엔진 포함, minified 기준)입니다. gzip 압축 시 전송 크기는 약 400KB입니다.

React 없이 Graphic Walker를 사용할 수 있나요?

네. 패키지는 모든 DOM 요소에 컴포넌트를 마운트하는 embedGraphicWalker, embedGraphicRenderer, embedPureRenderer, embedTableWalker 함수를 내보냅니다. Vanilla JS 임베딩 문서를 참조하세요.

데이터

Graphic Walker는 얼마나 많은 데이터를 처리할 수 있나요?

클라이언트 측 모드(data prop 전달)에서의 성능은 브라우저 메모리에 따라 달라집니다. 가이드라인:

대규모 데이터셋의 경우 computation prop을 사용하여 서버에 처리를 위임하세요.

어떤 데이터 형식을 지원하나요?

Graphic Walker는 JavaScript 객체 배열(Record<string, any>[])로 데이터를 받습니다. 모든 형식에서 변환할 수 있습니다:

• CSV: Papa Parse (opens in a new tab) 또는 내장 파일 업로드 사용
• JSON: 직접 파싱
• 데이터베이스: 데이터베이스를 쿼리하고 결과를 computation prop에 전달
• API: 데이터를 가져와 data prop에 전달

데이터베이스에 직접 연결할 수 있나요?

브라우저 컴포넌트에서 직접 연결하는 것은 불가능합니다. 서버 측 연산 모드를 사용하세요: 데이터베이스를 쿼리하고 결과를 반환하는 computation 함수를 구현합니다. 연산 가이드를 참조하세요.

렌더링

Graphic Walker는 SSR(서버 사이드 렌더링)을 지원하나요?

Graphic Walker는 렌더링을 위해 브라우저 환경이 필요합니다. Next.js와 같은 SSR 프레임워크에서는 ssr: false로 동적 import를 사용하세요:

import dynamic from 'next/dynamic';
 
const GraphicWalker = dynamic(
  () => import('@kanaries/graphic-walker').then(m => m.GraphicWalker),
  { ssr: false }
);

렌더링에 Canvas 대신 SVG를 사용할 수 있나요?

네. 레이아웃 구성 또는 defaultConfig prop에서 useSvg: true를 설정하세요:

<GraphicWalker
  data={data}
  fields={fields}
  defaultConfig={{
    layout: { useSvg: true },
  }}
/>

SVG 렌더링은 더 선명한 출력을 생성하지만 대규모 데이터셋에서는 더 느릴 수 있습니다.

차트 크기를 고정하려면 어떻게 하나요?

defaultConfig prop을 사용하세요:

<GraphicWalker
  data={data}
  fields={fields}
  defaultConfig={{
    layout: {
      size: { mode: 'fixed', width: 800, height: 600 },
    },
  }}
/>

커스터마이즈

UI의 일부를 숨길 수 있나요?

네. 다음 props를 사용하여 UI 가시성을 제어하세요:

차트 구성을 저장하고 복원하려면 어떻게 하나요?

chart prop은 IChart[] -- 차트 사양의 배열을 받습니다. 이 배열을 백엔드나 localStorage에 저장하고, 다시 전달하여 상태를 복원하세요:

// Save
const charts = storeRef.current?.exportAllCharts();
localStorage.setItem('gw-charts', JSON.stringify(charts));
 
// Restore
const saved = JSON.parse(localStorage.getItem('gw-charts') || '[]');
<GraphicWalker data={data} fields={fields} chart={saved} />

문제 해결

차트가 렌더링되지 않음 -- 빈 흰색 영역

일반적인 원인:

1. 데이터 누락: data가 비어 있지 않은 배열인지 확인
2. 필드 누락: fields 배열이 데이터의 키와 일치하는지 확인
3. SSR 문제: Next.js를 사용하는 경우 ssr: false로 import (위 참조)
4. 컨테이너 크기: 부모 요소에 정의된 높이가 있어야 함

"Field not found" 오류

fields 배열의 fid 값이 데이터 객체의 속성명과 정확히 일치하는지 확인하세요. 필드 ID는 대소문자를 구분합니다.

다크 모드가 작동하지 않음

더 이상 사용되지 않는 dark prop 대신 appearance prop을 사용하고 있는지 확인하세요:

<GraphicWalker appearance="dark" data={data} fields={fields} />

성능이 느림

• 데이터셋 크기를 줄이거나 서버 측 연산으로 전환
• hideProfiling={true}로 프로파일링 비활성화
• SVG 대신 Canvas 렌더링(기본값) 사용