常见问题

概述

什么是 Graphic Walker？

Graphic Walker 是一个开源的 React 组件，用于交互式数据可视化。它提供了类似 Tableau 的拖拽界面来构建图表，基于图形语法（grammar of graphics）方法驱动。与传统 BI 平台不同，它可以直接嵌入到你的 React（或任何 Web）应用中。

Graphic Walker 使用什么许可证？

Graphic Walker 基于 Apache-2.0 许可证 (opens in a new tab) 发布。

支持哪些浏览器？

Graphic Walker 支持所有现代浏览器：Chrome、Firefox、Safari 和 Edge（最新两个版本）。不支持 Internet Explorer。

包体大小是多少？

@kanaries/graphic-walker 压缩后大约 1.5MB（包含 Vega-Lite 渲染引擎）。经过 gzip 压缩后，传输大小约为 400KB。

可以不使用 React 来使用 Graphic Walker 吗？

可以。该包导出了 embedGraphicWalker、embedGraphicRenderer、embedPureRenderer 和 embedTableWalker 函数，可以将组件挂载到任意 DOM 元素上。详见原生 JS 嵌入文档。

数据

Graphic Walker 能处理多大的数据？

在客户端模式下（传递 data 属性），性能取决于浏览器内存。参考指标如下：

对于大型数据集，使用 computation 属性将处理任务委托给服务端。

支持哪些数据格式？

Graphic Walker 接受 JavaScript 对象数组（Record<string, any>[]）作为数据。你可以从任何格式转换：

• CSV：使用 Papa Parse (opens in a new tab) 或内置的文件上传功能
• JSON：直接解析
• 数据库：查询数据库并将结果传给 computation 属性
• API：获取数据后传给 data 属性

能直接连接数据库吗？

浏览器组件无法直接连接。使用服务端计算模式：实现一个 computation 函数来查询数据库并返回结果。详见计算指南。

渲染

Graphic Walker 支持 SSR（服务端渲染）吗？

Graphic Walker 需要浏览器环境来渲染。在 Next.js 等 SSR 框架中，使用 ssr: false 的动态导入：

import dynamic from 'next/dynamic';
 
const GraphicWalker = dynamic(
  () => import('@kanaries/graphic-walker').then(m => m.GraphicWalker),
  { ssr: false }
);

可以使用 SVG 代替 Canvas 渲染吗？

可以。在布局配置或 defaultConfig 属性中设置 useSvg: true：

<GraphicWalker
  data={data}
  fields={fields}
  defaultConfig={{
    layout: { useSvg: true },
  }}
/>

SVG 渲染输出更清晰，但对大数据集可能较慢。

如何设置固定的图表大小？

使用 defaultConfig 属性：

<GraphicWalker
  data={data}
  fields={fields}
  defaultConfig={{
    layout: {
      size: { mode: 'fixed', width: 800, height: 600 },
    },
  }}
/>

自定义

可以隐藏部分 UI 吗？

可以。使用以下属性控制 UI 可见性：

如何保存和恢复图表配置？

chart 属性接受 IChart[] — 图表规格数组。将此数组保存到后端或 localStorage，再传回即可恢复状态：

// Save
const charts = storeRef.current?.exportAllCharts();
localStorage.setItem('gw-charts', JSON.stringify(charts));
 
// Restore
const saved = JSON.parse(localStorage.getItem('gw-charts') || '[]');
<GraphicWalker data={data} fields={fields} chart={saved} />

故障排查

图表不渲染 — 显示空白区域

常见原因：

1. 缺少数据：确保 data 是一个非空数组
2. 缺少字段：确保 fields 数组中的键与数据匹配
3. SSR 问题：如果使用 Next.js，用 ssr: false 导入（见上文）
4. 容器大小：父元素必须有明确的高度

"Field not found" 错误

确保 fields 数组中的 fid 值与数据对象中的属性名完全匹配。字段 ID 区分大小写。

暗色模式不生效

确保使用的是 appearance 属性（而非已废弃的 dark 属性）：

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

性能较慢

• 减小数据集大小或切换到服务端计算
• 使用 hideProfiling={true} 禁用数据分析
• 使用 Canvas 渲染（默认）而非 SVG