zan-grid-charts

zan-grid 与 zan-charts 的桥接包，用来把网格选区、客户端透视结果或已有表格数据快速转换成图表。

适用范围

• 表格右键“打开图表”
• 选区即图表的分析型页面
• 客户端透视结果转柱图/折线图/组合图
• 想复用 zan-charts 的导出、缩放、tooltip、图例联动能力

安装

npm install zan-grid-charts

依赖关系：

• zan-grid-charts 依赖 zan-charts
• 如果图表数据来自 zan-grid 的选区或透视，通常会和 zan-grid 一起使用

核心概念

这个包主要提供三类能力：

1. buildGridRangeChartCandidate

把 zan-grid 的 getSelectedRangeData() 转成标准图表候选结构：

type GridRangeChartCandidate = {
  columns: Array<{ field: string; header?: string }>
  rows: Array<Record<string, any>>
  categoryField: string
  valueFields: string[]
}

2. buildGridPivotChartCandidate

把 zan-grid 的客户端透视输出转成图表候选结构。

3. createGridRangeChart

直接把候选数据或手工拼装的数据渲染成图表，并返回统一句柄。

快速开始

import { createGridRangeChart } from 'zan-grid-charts'

const container = document.getElementById('chart') as HTMLElement

const handle = createGridRangeChart({
  columns: [
    { field: 'department', header: '部门' },
    { field: 'sales', header: '销售额' },
    { field: 'trend', header: '趋势' }
  ],
  categoryField: 'department',
  valueFields: ['sales', 'trend'],
  data: [
    { department: '技术', sales: 120, trend: 110 },
    { department: '人事', sales: 80, trend: 90 }
  ],
  options: {
    container,
    type: 'combo',
    title: '部门销售对比',
    chartSeriesTypes: ['bar', 'line'],
    orientation: 'horizontal',
    referenceLines: [{ value: 100, label: '目标值' }],
    enableZoom: true,
    toolbar: {
      enabled: true,
      showResetZoom: true,
      showExportPng: true,
      showExportSvg: true
    }
  }
})

handle.update?.([
  { department: '技术', sales: 132, trend: 118 },
  { department: '人事', sales: 86, trend: 95 }
])

与 zan-grid 配合

1. 从当前选区生成图表

import { buildGridRangeChartCandidate, createGridRangeChart } from 'zan-grid-charts'

const selected = gridRef.value?.getSelectedRangeData() || null
const candidate = buildGridRangeChartCandidate(selected)

if (candidate) {
  createGridRangeChart({
    columns: candidate.columns,
    categoryField: candidate.categoryField,
    valueFields: candidate.valueFields,
    data: candidate.rows,
    options: {
      container,
      type: 'bar',
      title: '选区图表'
    }
  })
}

候选生成规则：

• 第一列非数值列会被当作 categoryField
• 剩余 type === 'number' 的列会被当作值列
• 如果没有非数值列，或没有数值列，会返回 null

2. 从客户端透视结果生成图表

import { buildGridPivotChartCandidate } from 'zan-grid-charts'

const pivotData = gridRef.value?.getPivotChartData() || null
const candidate = buildGridPivotChartCandidate(pivotData)

适用前提：

• 输入必须来自 zan-grid 的客户端透视结果
• 必须存在透视分组列
• 必须存在数值透视列

以下情况会返回 null：

• 没有 __pivot_group__: 分组列
• 没有数值透视列
• 行数据不是客户端透视生成的 pivot 行

createGridRangeChart 输入结构

interface GridRangeChartPayload {
  columns?: Array<{ field: string; header?: string }>
  categoryField: string
  valueFields: string[]
  data: Array<Record<string, any>>
  options?: {
    container?: HTMLElement | null
    type?: 'bar' | 'line' | 'area' | 'combo'
    chartSeriesTypes?: Array<'bar' | 'line' | 'area'>
    title?: string
    orientation?: 'vertical' | 'horizontal'
    hiddenSeries?: string[]
    enableZoom?: boolean
    xAxisFormatter?: (value: string, index: number) => string
    yAxisFormatter?: (value: number) => string
    yAxes?: Array<{ name?: string; min?: number; max?: number; formatter?: (value: number) => string }>
    referenceLines?: Array<{ value: number; label?: string; color?: string; lineDash?: string; yAxisIndex?: 0 | 1 }>
    referenceAreas?: Array<{ start: number; end: number; label?: string; color?: string; opacity?: number; yAxisIndex?: 0 | 1 }>
    emptyState?: { text?: string; subtext?: string }
    tooltip?: { shared?: boolean; crosshair?: boolean }
    toolbar?: {
      enabled?: boolean
      showResetZoom?: boolean
      showExportPng?: boolean
      showExportSvg?: boolean
      pngFilename?: string
      svgFilename?: string
    }
    hooks?: {
      onZoomChange?: (startIndex: number, endIndex: number) => void
      onLegendToggle?: (field: string, visible: boolean) => void
      onPointClick?: (payload: {
        category: string
        value: number
        field: string
        label: string
        index: number
        shiftKey: boolean
        ctrlKey: boolean
        metaKey: boolean
      }) => void
    }
  }
}

最关键的字段：

• categoryField：类目字段
• valueFields：值字段列表
• data：图表数据
• options.container：挂载容器，必填
• options.type：图表类型
• options.chartSeriesTypes：组合图下每个序列的具体类型

Handle API

createGridRangeChart() 返回 GridRangeChartHandle：

• update(data)：仅更新数据
• resetZoom()：重置缩放
• toSvgString()：导出 SVG 字符串
• toDataUrl(type?)：导出 data URL
• download(filename?, type?)：下载图片
• destroy()：销毁图表

典型集成方式

1. 在弹层中打开图表

常见组合：

• zan-grid：提供选区和透视数据
• zan-grid-charts：把数据转成图表
• zan-layer：弹层承载图表

2. 列表分析页的常驻图表区

适合：

• 左侧是表格
• 右侧是当前选区统计图
• 表格选区变化时，用 handle.update() 增量刷新

3. 透视分析页

流程：

1. zan-grid 做客户端透视
2. getPivotChartData() 取透视结果
3. buildGridPivotChartCandidate() 转图表候选
4. createGridRangeChart() 真正渲染

使用建议

• 网格列里请把值列明确声明成 type: 'number'，这样候选构造才稳定
• 组合图请显式传 chartSeriesTypes
• 如果图表打开在小弹层内，记得给容器一个稳定的宽高
• update(data) 只更新数据，不会替你改 categoryField 或 valueFields

边界与限制

• 只桥接当前支持的 bar / line / area / combo
• 不负责图表弹层、图表布局管理，这部分建议交给宿主 UI 或 zan-layer
• buildGridPivotChartCandidate() 只接受客户端透视结果，不承诺服务端透视兼容
• createGridRangeChart() 依赖真实 DOM 容器，options.container 不能为空

开发命令

npm run test
npm run build