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`	启用实验性功能，如计算字段。

国际化属性

属性	类型	默认值	说明
`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`	监听渲染状态变化。返回一个销毁函数。
`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}
    />
  );
}