GraphicWalker

GraphicWalkerは、ドラッグ＆ドロップによるチャート作成、フィールド管理、複数チャートタブを備えた、完全なインタラクティブデータ探索インターフェースを提供するプライマリコンポーネントです。

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

プロパティ

データプロパティ

プロパティ	型	必須	説明
`data`	`Record<string, any>[]`	はい*	データレコードの配列。クライアント側計算に使用。
`fields`	`IMutField[]`	はい	データの各列を記述するフィールド定義。
`computation`	`IComputationFunction`	はい*	サーバー側計算関数。`data`の代替。
`computationTimeout`	`number`	いいえ	計算リクエストのタイムアウト（ミリ秒）。

*data（クライアント側）またはcomputation（サーバー側）のいずれかを指定してください。両方は指定しないでください。

チャート設定プロパティ

プロパティ	型	デフォルト	説明
`chart`	`IChart[]`	`undefined`	読み込む事前設定されたチャート仕様。
`defaultConfig`	`{ config?: Partial<IVisualConfigNew>; layout?: Partial<IVisualLayout> }`	`undefined`	新しいチャートに適用されるデフォルト設定。
`defaultRenderer`	`'vega-lite' \| 'observable-plot'`	`'vega-lite'`	新しいチャートのデフォルトレンダリングエンジン。

外観プロパティ

プロパティ	型	デフォルト	説明
`appearance`	`'media' \| 'light' \| 'dark'`	`'media'`	ダークモード設定。`'media'`はシステム設定に従います。
`vizThemeConfig`	`IThemeKey \| GWGlobalConfig`	`undefined`	チャートレンダリングテーマ。組み込みオプション: `'vega'`、`'g2'`、`'streamlit'`。
`uiTheme`	`IUIThemeConfig`	`undefined`	ライトモードとダークモードのカスタムUIカラースキーム。

UIコントロールプロパティ

プロパティ	型	デフォルト	説明
`hideChartNav`	`boolean`	`false`	チャートタブナビゲーションを非表示にし、単一チャートに制限。
`hideSegmentNav`	`boolean`	`false`	データ/可視化セグメントナビゲーションを非表示。
`hideProfiling`	`boolean`	`false`	フィールドプロファイリング（分布プレビュー）を非表示。
`toolbar`	`{ extra?: ToolbarItemProps[]; exclude?: string[] }`	`undefined`	ツールバーのカスタマイズ — 追加ボタンや組み込みボタンの除外。

データ機能プロパティ

プロパティ	型	デフォルト	説明
`scales`	`IChannelScales`	`undefined`	ビジュアルチャネルのカスタムスケール設定。
`geographicData`	`IGeographicData & { key: string }`	`undefined`	地理的可視化用のGeoJSON/TopoJSONデータ。
`geoList`	`IGeoDataItem[]`	`undefined`	選択可能な地理データセットのリスト。
`experimentalFeatures`	`{ computedField?: boolean }`	`undefined`	計算フィールドなどの実験的機能を有効化。

i18nプロパティ

プロパティ	型	デフォルト	説明
`i18nLang`	`string`	`undefined`	言語コード（例: `'en-US'`、`'zh-CN'`、`'ja-JP'`）。
`i18nResources`	`Record<string, Record<string, string>>`	`undefined`	カスタム翻訳リソース。

Refと状態プロパティ

プロパティ	型	説明
`ref`	`React.Ref<IGWHandler>`	ハンドラーAPIにアクセスするためのref（チャートエクスポート、タブ切り替えなど）。
`storeRef`	`React.RefObject<CommonStore>`	内部状態ストアへのref。
`keepAlive`	`boolean \| string`	アンマウント時にコンポーネントの状態を保持。複数インスタンスの場合は文字列をユニークキーとして渡す。
`onMetaChange`	`(fid: string, meta: Partial<IMutField>) => void`	フィールドメタデータ変更時のコールバック。

エラーハンドリング

プロパティ	型	説明
`onError`	`(err: Error) => void`	エラーハンドリング用コールバック。

スタイリング

プロパティ	型	説明
`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`	各チャートのエクスポートデータを返す非同期ジェネレーター。

エクスポート例

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