Skip to content

시작하기

이 가이드에서는 Graphic Walker를 설치하고 첫 번째 인터랙티브 차트를 렌더링하는 과정을 안내합니다.

사전 요구 사항

  • Node.js 16+
  • React 17+ (React 18 권장)

설치

선호하는 패키지 매니저로 패키지를 설치하세요:

# npm
npm install @kanaries/graphic-walker
 
# yarn
yarn add @kanaries/graphic-walker
 
# pnpm
pnpm add @kanaries/graphic-walker

기본 사용법

GraphicWalker 컴포넌트를 import하고 데이터 및 필드 정의를 전달하세요:

import { GraphicWalker } from '@kanaries/graphic-walker';
 
const data = [
  { date: '2024-01-01', product: 'A', sales: 120, profit: 40 },
  { date: '2024-01-01', product: 'B', sales: 200, profit: 80 },
  { date: '2024-02-01', product: 'A', sales: 150, profit: 55 },
  { date: '2024-02-01', product: 'B', sales: 180, profit: 65 },
];
 
const fields = [
  { fid: 'date', name: 'Date', semanticType: 'temporal', analyticType: 'dimension' },
  { fid: 'product', name: 'Product', semanticType: 'nominal', analyticType: 'dimension' },
  { fid: 'sales', name: 'Sales', semanticType: 'quantitative', analyticType: 'measure' },
  { fid: 'profit', name: 'Profit', semanticType: 'quantitative', analyticType: 'measure' },
];
 
function App() {
  return <GraphicWalker data={data} fields={fields} />;
}
 
export default App;

이것만으로 완료입니다 -- 사용자가 필드를 드래그하여 차트를 만들 수 있는 완전한 인터랙티브 시각화 편집기가 렌더링됩니다.

필드 이해하기

모든 필드에는 두 가지 타입 어노테이션이 필요합니다:

시맨틱 타입

Graphic Walker에 이 필드에 어떤 종류의 데이터가 포함되어 있는지 알려줍니다:

시맨틱 타입용도예시
quantitative연속적인 숫자매출, 온도, 개수
nominal순서 없는 카테고리제품명, 국가, 색상
ordinal순서 있는 카테고리평점 (낮음/중간/높음), 학력
temporal날짜 및 시간주문일, 타임스탬프

분석 타입

Graphic Walker에 필드를 분석에서 어떻게 사용할지 알려줍니다:

분석 타입의미동작
dimension그룹화 필드데이터를 카테고리별로 분할하는 데 사용
measure집계 필드합계, 평균, 개수 등으로 처리

경험 법칙: SQL에서 GROUP BY로 사용할 필드는 dimension이고, SUM() 또는 AVG()로 사용할 필드는 measure입니다.

CSV에서 데이터 로드하기

모든 CSV 파싱 라이브러리를 사용할 수 있습니다. 다음은 Papa Parse (opens in a new tab)를 사용한 예시입니다:

import { GraphicWalker } from '@kanaries/graphic-walker';
import Papa from 'papaparse';
import { useState, useEffect } from 'react';
 
function App() {
  const [data, setData] = useState([]);
  const [fields, setFields] = useState([]);
 
  useEffect(() => {
    Papa.parse('/data.csv', {
      download: true,
      header: true,
      dynamicTyping: true,
      complete(results) {
        setData(results.data);
        // Auto-generate field definitions from columns
        const cols = Object.keys(results.data[0] || {});
        setFields(
          cols.map(col => ({
            fid: col,
            name: col,
            semanticType: typeof results.data[0][col] === 'number' ? 'quantitative' : 'nominal',
            analyticType: typeof results.data[0][col] === 'number' ? 'measure' : 'dimension',
          }))
        );
      },
    });
  }, []);
 
  if (!data.length) return <div>Loading...</div>;
  return <GraphicWalker data={data} fields={fields} />;
}

사전 구성된 차트 추가하기

chart prop을 전달하면 컴포넌트가 로드될 때 특정 시각화를 표시합니다:

import { GraphicWalker } from '@kanaries/graphic-walker';
import type { IChart } from '@kanaries/graphic-walker';
 
const charts: IChart[] = [
  {
    visId: 'chart-1',
    name: 'Sales by Product',
    encodings: {
      dimensions: [],
      measures: [],
      rows: [{ fid: 'sales', name: 'Sales', analyticType: 'measure', semanticType: 'quantitative' }],
      columns: [{ fid: 'product', name: 'Product', analyticType: 'dimension', semanticType: 'nominal' }],
      color: [],
      opacity: [],
      size: [],
      shape: [],
      theta: [],
      radius: [],
      longitude: [],
      latitude: [],
      geoId: [],
      details: [],
      filters: [],
      text: [],
    },
    config: {
      defaultAggregated: true,
      geoms: ['bar'],
      coordSystem: 'generic',
      limit: -1,
    },
    layout: {
      showTableSummary: false,
      stack: 'stack',
      showActions: false,
      interactiveScale: false,
      zeroScale: true,
      size: { mode: 'auto', width: 800, height: 600 },
      format: {},
      resolve: {},
    },
  },
];
 
function App() {
  return <GraphicWalker data={data} fields={fields} chart={charts} />;
}

다크 모드

appearance prop으로 외관을 제어하세요:

// Follow system preference
<GraphicWalker data={data} fields={fields} appearance="media" />
 
// Always light
<GraphicWalker data={data} fields={fields} appearance="light" />
 
// Always dark
<GraphicWalker data={data} fields={fields} appearance="dark" />

다음 단계