ECharts 时间格式化完全指南

文档类型: 工具指南
难度等级: ⭐⭐
源码版本: ECharts 5.x
本文行数: 约350行

---

📋 目录

1. 时间轴类型
2. 格式化器详解
3. 时区处理
4. 实战案例

---

🎯 时间轴类型

time类型坐标轴

const option = {
  xAxis: {
    type: 'time',
    
    // 时间范围
    min: new Date('2024-01-01'),
    max: new Date('2024-12-31'),
    
    // 自动分割
    splitNumber: 12
  },
  
  series: [{
    type: 'line',
    data: [
      [new Date('2024-01-01'), 100],
      [new Date('2024-02-01'), 120],
      [new Date('2024-03-01'), 150]
    ]
  }]
};

---

📐 格式化器详解

内置格式占位符

const option = {
  xAxis: {
    type: 'time',
    axisLabel: {
      formatter: '{yyyy}-{MM}-{dd} {HH}:{mm}:{ss}'
    }
  }
};

可用占位符:

• {yyyy} - 四位年份
• {MM} - 月份 (01-12)
• {dd} - 日期 (01-31)
• {HH} - 小时 (00-23)
• {mm} - 分钟 (00-59)
• {ss} - 秒 (00-59)

---

自定义格式化函数

const option = {
  xAxis: {
    type: 'time',
    axisLabel: {
      formatter: (value: number, index?: number) => {
        const date = new Date(value);
        
        // 工作日显示"周X"
        const weekdays = ['周日', '周一', '周二', '周三', '周四', '周五', '周六'];
        const weekday = weekdays[date.getDay()];
        
        return `${date.getMonth() + 1}/${date.getDate()} ${weekday}`;
      }
    }
  }
};

---

tooltip时间格式化

const option = {
  tooltip: {
    trigger: 'axis',
    formatter: (params: any) => {
      const date = new Date(params[0].value[0]);
      const formattedDate = date.toLocaleString('zh-CN', {
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
        hour: '2-digit',
        minute: '2-digit'
      });
      
      return `
        <strong>${formattedDate}</strong><br/>
        数值: ${params[0].value[1]}
      `;
    }
  }
};

---

🌍 时区处理

UTC时间转换

// UTC时间转本地时间
function utcToLocal(utcTimestamp: number): Date {
  return new Date(utcTimestamp);
}

// 本地时间转UTC
function localToUTC(localDate: Date): number {
  return localDate.getTime() - localDate.getTimezoneOffset() * 60000;
}

// 在ECharts中使用
const option = {
  series: [{
    type: 'line',
    data: utcData.map(([utc, value]) => [
      utcToLocal(utc),  // 转换为本地时间
      value
    ])
  }]
};

---

💻 实战案例

多时区展示

class MultiTimezoneChart {
  private chart: echarts.ECharts;
  
  constructor(container: HTMLElement) {
    this.chart = echarts.init(container);
    this.render();
  }
  
  private render() {
    const baseTime = new Date('2024-01-01T00:00:00Z').getTime();
    
    const option = {
      title: { text: '全球服务器延迟监控' },
      legend: { data: ['北京', '纽约', '伦敦', '东京'] },
      xAxis: {
        type: 'time',
        axisLabel: {
          formatter: '{HH}:{mm}'
        }
      },
      yAxis: {
        type: 'value',
        name: '延迟(ms)'
      },
      series: [
        {
          name: '北京',
          type: 'line',
          data: this.generateTimezoneData(baseTime, 'Asia/Shanghai', 50),
          smooth: true
        },
        {
          name: '纽约',
          type: 'line',
          data: this.generateTimezoneData(baseTime, 'America/New_York', 150),
          smooth: true
        },
        {
          name: '伦敦',
          type: 'line',
          data: this.generateTimezoneData(baseTime, 'Europe/London', 100),
          smooth: true
        },
        {
          name: '东京',
          type: 'line',
          data: this.generateTimezoneData(baseTime, 'Asia/Tokyo', 30),
          smooth: true
        }
      ]
    };
    
    this.chart.setOption(option);
  }
  
  private generateTimezoneData(baseTime: number, timezone: string, baseLatency: number) {
    const data: [Date, number][] = [];
    
    for (let i = 0; i < 24; i++) {
      const time = new Date(baseTime + i * 3600000);
      const latency = baseLatency + Math.random() * 50;
      data.push([time, latency]);
    }
    
    return data;
  }
  
  resize() {
    this.chart.resize();
  }
  
  dispose() {
    this.chart.dispose();
  }
}

// 使用
const multiTZ = new MultiTimezoneChart(document.getElementById('chart')!);
window.addEventListener('resize', () => multiTZ.resize());

---

🎯 最佳实践总结

✅ DO - 推荐做法

1. 使用time类型而非category

   xAxis: { type: 'time' }  // ✅ 自动处理时间

2. 合理设置时间粒度

   // 根据数据范围自动调整
   splitNumber: 10

3. 本地化时间显示

   date.toLocaleString('zh-CN')

❌ DON'T - 避免做法

1. 避免手动计算时间间隔

   // ❌ 不好
   data: labels.map((label, i) => [i * 3600000, value])
   
   // ✅ 好
   data: timestamps.map(ts => [new Date(ts), value])

---

🔗 相关资源

• JavaScript Date API
• day.js轻量级时间库

---

✅ 时间序列模块完成!