数据格式规范与要求

数据格式规范与要求

ECharts作为一款强大的数据可视化库，对数据格式有严格的要求。正确的数据格式能确保图表正常渲染，错误的格式则可能导致图表无法显示或显示异常。数据格式的规范性与图表类型密切相关，不同类型图表对数据结构、字段命名、数值类型等有不同要求。

基础数据结构

ECharts支持两种基础数据结构：数组和对象。数组适用于简单数据集，对象适用于复杂数据结构。例如，折线图常用数组格式：

// 简单数组格式
const data = [10, 20, 30, 40, 50];

// 对象数组格式
const data = [
  { value: 10, name: 'A' },
  { value: 20, name: 'B' },
  { value: 30, name: 'C' }
];

对象格式通常用于包含额外属性的数据：

const data = {
  categories: ['A', 'B', 'C'],
  values: [10, 20, 30],
  units: 'kg'
};

常见图表数据格式

折线图/柱状图

折线图和柱状图通常需要x轴和y轴数据。ECharts支持两种格式：

// 格式1：分开的xAxis和series数据
option = {
  xAxis: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri']
  },
  series: [{
    data: [120, 200, 150, 80, 70]
  }]
};

// 格式2：数据集形式
option = {
  dataset: {
    source: [
      ['product', 'sales'],
      ['Mon', 120],
      ['Tue', 200],
      ['Wed', 150]
    ]
  }
};

饼图/环形图

饼图需要name-value对的数据格式：

option = {
  series: [{
    type: 'pie',
    data: [
      { value: 335, name: '直接访问' },
      { value: 310, name: '邮件营销' },
      { value: 234, name: '联盟广告' }
    ]
  }]
};

散点图

散点图需要二维或三维坐标数据：

option = {
  xAxis: {},
  yAxis: {},
  series: [{
    type: 'scatter',
    data: [
      [10, 5],
      [0, 8],
      [6, 10]
    ]
  }]
};

// 三维散点图
option = {
  grid3D: {},
  xAxis3D: {},
  yAxis3D: {},
  zAxis3D: {},
  series: [{
    type: 'scatter3D',
    data: [
      [10, 5, 3],
      [0, 8, 1],
      [6, 10, 5]
    ]
  }]
};

数据集(dataset)的使用

ECharts 4.0+推荐使用dataset管理数据，这种方式更灵活且便于数据复用：

option = {
  dataset: {
    // 二维数组形式
    source: [
      ['product', '2015', '2016', '2017'],
      ['Matcha Latte', 43.3, 85.8, 93.7],
      ['Milk Tea', 83.1, 73.4, 55.1]
    ]
  },
  xAxis: { type: 'category' },
  yAxis: {},
  series: [
    { type: 'bar' },
    { type: 'bar' },
    { type: 'bar' }
  ]
};

dataset也支持对象数组格式：

option = {
  dataset: {
    dimensions: ['product', '2015', '2016', '2017'],
    source: [
      { product: 'Matcha Latte', '2015': 43.3, '2016': 85.8, '2017': 93.7 },
      { product: 'Milk Tea', '2015': 83.1, '2016': 73.4, '2017': 55.1 }
    ]
  }
};

特殊数据格式要求

树形数据

树图需要特定的层级结构：

option = {
  series: [{
    type: 'tree',
    data: [{
      name: 'Node A',
      children: [{
        name: 'Node A1',
        children: [{ name: 'Node A11' }]
      }]
    }]
  }]
};

关系图数据

关系图需要nodes和links两个数组：

option = {
  series: [{
    type: 'graph',
    data: [{
      name: 'Node 1',
      category: 0
    }, {
      name: 'Node 2',
      category: 1
    }],
    links: [{
      source: 'Node 1',
      target: 'Node 2'
    }]
  }]
};

数据转换

ECharts提供transform功能对数据进行处理：

option = {
  dataset: [{
    source: [
      ['Product', 'Sales', 'Price', 'Year'],
      ['Cake', 123, 32, 2011],
      ['Cereal', 231, 14, 2011]
    ]
  }, {
    transform: {
      type: 'filter',
      config: { dimension: 'Year', value: 2011 }
    }
  }],
  series: {
    type: 'pie',
    datasetIndex: 1
  }
};

大数据量优化

处理大数据量时，可采用以下格式优化性能：

// 使用扁平数组代替对象数组
const largeData = new Float64Array(1000000);
for (let i = 0; i < largeData.length; i++) {
  largeData[i] = Math.random() * 100;
}

option = {
  series: [{
    type: 'line',
    data: largeData
  }]
};

异步数据加载

ECharts支持异步数据加载，常见格式：

// 使用Promise
fetch('data.json')
  .then(response => response.json())
  .then(data => {
    myChart.setOption({
      series: [{
        type: 'line',
        data: data.values
      }]
    });
  });

// 使用回调函数
$.get('data.json', function(data) {
  myChart.setOption({
    dataset: {
      source: data
    }
  });
});

数据错误处理

当数据格式不符合要求时，ECharts会抛出警告或错误。常见问题包括：

1. 数据项缺少必要字段
2. 数值类型不正确（如字符串代替数字）
3. 数据结构不符合图表类型要求
4. 数据维度不匹配

// 错误示例：饼图数据缺少name字段
option = {
  series: [{
    type: 'pie',
    data: [
      { value: 335 },  // 缺少name字段
      { value: 310, name: '邮件营销' }
    ]
  }]
};

自定义数据解析

对于特殊数据格式，可通过encode属性指定字段映射：

option = {
  dataset: {
    source: [
      { month: 'Jan', temperature: 2.3, rainfall: 45 },
      { month: 'Feb', temperature: 4.5, rainfall: 30 }
    ]
  },
  series: [{
    type: 'line',
    encode: {
      x: 'month',  // 指定x轴数据字段
      y: 'temperature'  // 指定y轴数据字段
    }
  }]
};

时间类型数据处理

处理时间数据时需要特别注意格式：

option = {
  xAxis: {
    type: 'time',
    data: [
      '2023-01-01',
      '2023-01-02',
      '2023-01-03'
    ]
  },
  series: [{
    data: [
      ['2023-01-01', 100],
      ['2023-01-02', 200],
      ['2023-01-03', 150]
    ]
  }]
};

// 或者使用时间戳
option = {
  xAxis: {
    type: 'time'
  },
  series: [{
    data: [
      [1672531200000, 100],  // 2023-01-01
      [1672617600000, 200]   // 2023-01-02
    ]
  }]
};

多维数据分析

ECharts支持多维数据分析，通过dataset的dimensions属性定义：

option = {
  dataset: {
    dimensions: ['date', 'open', 'close', 'highest', 'lowest'],
    source: [
      ['2023-01-01', 120, 220, 240, 110],
      ['2023-01-02', 150, 250, 270, 130]
    ]
  },
  series: [{
    type: 'candlestick',
    encode: {
      x: 'date',
      y: ['open', 'close', 'lowest', 'highest']
    }
  }]
};

地理数据格式

地图数据有特殊格式要求：

// GeoJSON格式
option = {
  series: [{
    type: 'map',
    data: [
      { name: '北京', value: 100 },
      { name: '上海', value: 200 }
    ],
    geoJSON: geoJsonData  // 外部加载的GeoJSON数据
  }]
};

// 简单格式
option = {
  series: [{
    type: 'map',
    map: 'china',
    data: [
      { name: '广东', value: 500 },
      { name: '浙江', value: 300 }
    ]
  }]
};

动态数据更新

ECharts支持动态数据更新，但需要保持数据结构一致：

// 初始数据
option = {
  series: [{
    type: 'line',
    data: [10, 20, 30]
  }]
};

// 更新数据
setInterval(() => {
  const newData = option.series[0].data.map(v => v + Math.random() * 10 - 5);
  myChart.setOption({
    series: [{
      data: newData
    }]
  });
}, 1000);