GraphicWalker

GraphicWalker는 드래그 앤 드롭 차트 구축, 필드 관리 및 다중 차트 탭을 갖춘 완전한 인터랙티브 데이터 탐색 인터페이스를 제공하는 주요 컴포넌트입니다.

import { GraphicWalker } from '@kanaries/graphic-walker';

Props

데이터 Props

Prop	타입	필수	설명
`data`	`Record<string, any>[]`	Yes*	데이터 레코드 배열. 클라이언트 측 연산에 사용.
`fields`	`IMutField[]`	Yes	데이터의 각 열을 설명하는 필드 정의.
`computation`	`IComputationFunction`	Yes*	서버 측 연산 함수. `data`의 대안.
`computationTimeout`	`number`	No	연산 요청의 타임아웃 (ms).

*data(클라이언트 측) 또는 computation(서버 측) 중 하나만 제공하세요. 둘 다 제공하지 마세요.

차트 구성 Props

Prop	타입	기본값	설명
`chart`	`IChart[]`	`undefined`	로드할 사전 구성된 차트 사양.
`defaultConfig`	`{ config?: Partial<IVisualConfigNew>; layout?: Partial<IVisualLayout> }`	`undefined`	새 차트에 적용되는 기본 설정.
`defaultRenderer`	`'vega-lite' \| 'observable-plot'`	`'vega-lite'`	새 차트의 기본 렌더링 엔진.

외관 Props

Prop	타입	기본값	설명
`appearance`	`'media' \| 'light' \| 'dark'`	`'media'`	다크 모드 설정. `'media'`는 시스템 설정을 따릅니다.
`vizThemeConfig`	`IThemeKey \| GWGlobalConfig`	`undefined`	차트 렌더링 테마. 내장 옵션: `'vega'`, `'g2'`, `'streamlit'`.
`uiTheme`	`IUIThemeConfig`	`undefined`	라이트 및 다크 모드의 커스텀 UI 색상 스키마.

UI 제어 Props

Prop	타입	기본값	설명
`hideChartNav`	`boolean`	`false`	차트 탭 내비게이션을 숨기고 단일 차트로 제한.
`hideSegmentNav`	`boolean`	`false`	데이터/시각화 세그먼트 내비게이션 숨기기.
`hideProfiling`	`boolean`	`false`	필드 프로파일링(분포 미리보기) 숨기기.
`toolbar`	`{ extra?: ToolbarItemProps[]; exclude?: string[] }`	`undefined`	툴바 커스터마이즈 -- 추가 버튼 또는 내장 버튼 제외.

데이터 기능 Props

Prop	타입	기본값	설명
`scales`	`IChannelScales`	`undefined`	시각적 채널의 커스텀 스케일 구성.
`geographicData`	`IGeographicData & { key: string }`	`undefined`	지리적 시각화를 위한 GeoJSON/TopoJSON 데이터.
`geoList`	`IGeoDataItem[]`	`undefined`	선택 가능한 지리적 데이터셋 목록.
`experimentalFeatures`	`{ computedField?: boolean }`	`undefined`	계산된 필드와 같은 실험적 기능 활성화.

i18n Props

Prop	타입	기본값	설명
`i18nLang`	`string`	`undefined`	언어 코드 (예: `'en-US'`, `'zh-CN'`, `'ja-JP'`).
`i18nResources`	`Record<string, Record<string, string>>`	`undefined`	커스텀 번역 리소스.

Ref 및 상태 Props

Prop	타입	설명
`ref`	`React.Ref<IGWHandler>`	핸들러 API에 접근하기 위한 Ref (차트 내보내기, 탭 이동 등).
`storeRef`	`React.RefObject<CommonStore>`	내부 상태 스토어에 대한 Ref.
`keepAlive`	`boolean \| string`	언마운트 시 컴포넌트 상태 유지. 다중 인스턴스의 경우 문자열을 고유 키로 전달.
`onMetaChange`	`(fid: string, meta: Partial<IMutField>) => void`	필드 메타데이터 변경 시 콜백.

오류 처리

Prop	타입	설명
`onError`	`(err: Error) => void`	오류 처리 콜백.

스타일링

Prop	타입	설명
`className`	`string`	루트 요소에 적용되는 CSS 클래스.
`style`	`React.CSSProperties`	루트 요소에 적용되는 인라인 스타일.

Ref 핸들러 (IGWHandler)

React ref를 통해 핸들러에 접근하여 컴포넌트를 프로그래밍 방식으로 제어할 수 있습니다:

import { useRef } from 'react';
import { GraphicWalker } from '@kanaries/graphic-walker';
import type { IGWHandler } from '@kanaries/graphic-walker';
 
function App() {
  const gwRef = useRef<IGWHandler>(null);
 
  return <GraphicWalker ref={gwRef} data={data} fields={fields} />;
}

핸들러 속성 및 메서드

멤버	타입	설명
`chartCount`	`number`	총 차트 탭 수.
`chartIndex`	`number`	현재 선택된 차트 탭 인덱스.
`openChart(index)`	`(index: number) => void`	특정 차트 탭으로 전환.
`renderStatus`	`'computing' \| 'rendering' \| 'idle' \| 'error'`	활성 차트의 현재 렌더 상태.
`onRenderStatusChange(cb)`	`(cb: Function) => () => void`	렌더 상태 변경 수신. dispose 함수 반환.
`exportChart(mode?)`	`(mode?: 'svg' \| 'data-url') => Promise<IChartExportResult>`	현재 차트 내보내기. 기본값: `'svg'`.
`exportChartList(mode?)`	`(mode?: 'svg' \| 'data-url') => AsyncGenerator`	각 차트의 내보내기 데이터를 yield하는 Async generator.

내보내기 예시

async function handleExport() {
  if (!gwRef.current) return;
 
  // Export current chart as SVG
  const result = await gwRef.current.exportChart('svg');
  console.log(result.title, result.charts);
 
  // Export all charts
  for await (const item of gwRef.current.exportChartList('data-url')) {
    console.log(`Chart ${item.index + 1}/${item.total}:`, item.data.title);
  }
}

예시

기본 탐색기

import { GraphicWalker } from '@kanaries/graphic-walker';
 
function Explorer({ data, fields }) {
  return <GraphicWalker data={data} fields={fields} />;
}

다크 모드 및 테마 적용

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

툴바 커스터마이즈

<GraphicWalker
  data={data}
  fields={fields}
  toolbar={{
    exclude: ['export_chart'],
    extra: [
      {
        key: 'custom-save',
        label: 'Save',
        icon: SaveIcon,
        onClick: handleSave,
      },
    ],
  }}
/>

서버 측 연산

import { GraphicWalker } from '@kanaries/graphic-walker';
import type { IComputationFunction } from '@kanaries/graphic-walker';
 
const computation: IComputationFunction = async (payload) => {
  const response = await fetch('/api/compute', {
    method: 'POST',
    body: JSON.stringify(payload),
    headers: { 'Content-Type': 'application/json' },
  });
  return response.json();
};
 
function App() {
  return (
    <GraphicWalker
      computation={computation}
      fields={fields}
    />
  );
}

시작하기 GraphicRenderer