数据格式规范与要求

数据格式规范与要求

ECharts作为一款强大的数据可视化库，对数据格式有严格的要求。不同类型图表需要不同结构的数据，正确理解这些规范能避免渲染错误并提升开发效率。数据格式主要分为数组、对象、树形结构等几种形式，每种形式适用于特定图表类型。

基础数据结构

一维数组

最简单的数据格式，适用于折线图、柱状图等基础图表。数组元素可以是数值或对象：

// 纯数值数组
const data = [12, 28, 55, 18, 49]

// 对象数组（带名称）
const dataWithName = [
  { value: 12, name: '周一' },
  { value: 28, name: '周二' },
  { value: 55, name: '周三' }
]

二维数组

常用于散点图、气泡图等多维数据展示：

const scatterData = [
  [10, 25], 
  [20, 36],
  [30, 18]
]

// 带额外属性的二维数据
const bubbleData = [
  [10, 25, 5],  // 第三位表示气泡大小
  [20, 36, 8],
  [30, 18, 3]
]

特殊图表数据结构

关系图数据格式

关系图（graph）需要节点（nodes）和边（links）的复合结构：

const graphData = {
  nodes: [
    { id: '1', name: '节点A', symbolSize: 30 },
    { id: '2', name: '节点B', symbolSize: 20 }
  ],
  links: [
    { source: '1', target: '2' }
  ]
}

树形结构数据

树图（tree）要求递归嵌套格式：

const treeData = {
  name: '根节点',
  children: [
    { 
      name: '子节点1',
      children: [
        { name: '叶子节点1' },
        { name: '叶子节点2' }
      ]
    }
  ]
}

时间序列处理

时间轴数据

时间轴系列需要特定格式的时间字符串或时间戳：

const timeData = [
  ['2023-01-01', 312],
  ['2023-01-02', 298],
  ['2023-01-03', 401]
]

// 使用Date对象
const timestampData = [
  [new Date(2023,0,1).getTime(), 312],
  [new Date(2023,0,2).getTime(), 298]
]

时区处理建议

为避免时区问题，推荐使用ISO格式字符串：

// 推荐格式
const isoTimeData = [
  ['2023-01-01T00:00:00Z', 412],
  ['2023-01-02T00:00:00Z', 387]
]

大数据优化格式

扁平化数据结构

处理万级以上数据点时建议使用 typed array：

// 使用Float32Array提升性能
const largeData = new Float32Array(100000)
for(let i=0; i<100000; i++){
  largeData[i] = Math.random() * 100
}

分块加载格式

增量渲染时需要特定分块格式：

const chunkedData = {
  chunks: [
    { offset: 0, data: [/* 第一批数据 */] },
    { offset: 1000, data: [/* 第二批数据 */] }
  ],
  total: 50000
}

自定义系列数据

自定义形状数据

需要提供顶点坐标和绘制指令：

const customData = {
  type: 'path',
  shape: {
    pathData: 'M10,10 L50,50 L10,50 Z', // SVG路径
    points: [[10,10], [50,50], [10,50]] // 坐标点
  },
  style: { fill: '#c23531' }
}

混合图表数据

组合不同系列时需要统一数据索引：

const combinedData = {
  xAxis: ['品类1', '品类2', '品类3'],
  series: [
    { type: 'bar', data: [12, 25, 18] },
    { type: 'line', data: [8, 22, 30] }
  ]
}

数据转换工具

使用dataset管理

推荐使用dataset进行数据管理：

const option = {
  dataset: {
    source: [
      ['product', 'sales', 'profit'],
      ['手机', 4321, 1234],
      ['电脑', 2865, 987]
    ]
  },
  series: [
    { type: 'bar', encode: { x: 'product', y: 'sales' } },
    { type: 'line', encode: { x: 'product', y: 'profit' } }
  ]
}

数据转换示例

使用transform进行数据预处理：

dataset: [{
  source: [...原始数据...]
}, {
  transform: {
    type: 'filter',
    config: { dimension: 'sales', '>': 1000 }
  }
}]

错误数据示例

常见格式错误

避免以下错误格式：

// 错误1：混合类型数组
const wrongData1 = [10, '20', 30]

// 错误2：不完整的树结构
const wrongTree = {
  name: '根节点',
  children: [null, undefined, {}]
}

// 错误3：缺少必要字段的关系图
const wrongGraph = {
  nodes: [{ id: 1 }],
  links: [{ source: 1 }] // 缺少target
}

空数据处理

正确表示空值的方式：

// 正确做法
const correctNullData = [
  [1, null],  // 使用null
  [2, undefined],  // 或undefined
  [3, '-']  // 或特定占位符
]

// 错误做法 - 会导致解析失败
const wrongNullData = [
  [1, 'null'],  // 字符串
  [2, 'N/A']    // 自定义字符串
]