Skip to content
GRAPHIC WALKER
快速开始

快速开始

本指南将引导你安装 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 { 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 属性在组件加载时展示特定的可视化：

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 属性控制外观：

// 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" />

下一步

Graphic WalkerGraphicWalker