TypeScript类型定义完全指南

📋 概述

TypeScript类型定义为ECharts提供完整的类型安全和智能提示。通过精确的类型定义，可以在编译时捕获错误、提升开发体验、减少运行时bug。

核心价值

• 类型安全：编译时捕获配置错误
• 智能提示：IDE自动补全和文档
• 重构友好：修改配置时自动更新引用
• 文档即代码：类型定义本身就是文档
• 团队协作：明确的接口契约

---

🎯 核心类型

1. 基础类型

import type {
  EChartsOption,
  LineSeriesOption,
  BarSeriesOption,
  PieSeriesOption,
  ScatterSeriesOption,
  XAXisOption,
  YAXisOption,
  TooltipComponentOption,
  LegendComponentOption
} from 'echarts';

// 使用示例
const lineOption: LineSeriesOption = {
  type: 'line',
  data: [10, 20, 30],
  smooth: true // ✅ 类型检查通过
  // smoth: true // ❌ 拼写错误，编译失败
};

2. 完整图表配置类型

import type { EChartsOption } from 'echarts';

const option: EChartsOption = {
  title: {
    text: '销售统计',
    left: 'center'
  },
  
  tooltip: {
    trigger: 'axis'
  },
  
  legend: {
    data: ['销售额']
  },
  
  xAxis: {
    type: 'category',
    data: ['一月', '二月', '三月']
  },
  
  yAxis: {
    type: 'value'
  },
  
  series: [
    {
      name: '销售额',
      type: 'bar',
      data: [120, 200, 150]
    }
  ]
};

---

🔧 自定义类型工具

1. 图表配置工厂

type ChartType = 'line' | 'bar' | 'pie' | 'scatter';

interface ChartConfig {
  type: ChartType;
  data: number[];
  labels?: string[];
  title?: string;
}

function createChartOption(config: ChartConfig): EChartsOption {
  const baseOption: EChartsOption = {
    title: config.title ? { text: config.title } : undefined,
    xAxis: {
      type: 'category',
      data: config.labels || []
    },
    yAxis: {
      type: 'value'
    }
  };
  
  const seriesMap: Record<ChartType, any> = {
    line: { type: 'line', data: config.data, smooth: true },
    bar: { type: 'bar', data: config.data },
    pie: { 
      type: 'pie',
      data: config.data.map((value, index) => ({
        value,
        name: config.labels?.[index] || `项${index}`
      }))
    },
    scatter: { type: 'scatter', data: config.data }
  };
  
  return {
    ...baseOption,
    series: [seriesMap[config.type]]
  };
}

// 使用
const option = createChartOption({
  type: 'bar',
  data: [10, 20, 30],
  labels: ['A', 'B', 'C'],
  title: '测试图表'
});

2. 类型守卫

function isLineSeries(option: any): option is LineSeriesOption {
  return option?.type === 'line';
}

function processSeries(series: any) {
  if (isLineSeries(series)) {
    // TypeScript知道这里是LineSeriesOption
    console.log(series.smooth); // ✅ 智能提示
  }
}

---

💡 实战案例

案例1：React组件类型

import React from 'react';
import type { EChartsOption } from 'echarts';

interface EChartsProps {
  option: EChartsOption;
  theme?: string;
  onChartReady?: (chart: any) => void;
  style?: React.CSSProperties;
}

const ECharts: React.FC<EChartsProps> = ({
  option,
  theme,
  onChartReady,
  style
}) => {
  // 实现...
  return <div style={style} />;
};

// 使用 - 有完整的类型检查
<ECharts
  option={{
    xAxis: { type: 'category', data: ['A', 'B'] },
    yAxis: { type: 'value' },
    series: [{ type: 'bar', data: [10, 20] }]
  }}
  theme="dark"
  style={{ width: '100%', height: '400px' }}
/>

案例2：Vue组合式API类型

import { ref } from 'vue';
import type { EChartsOption } from 'echarts';

const chartOption = ref<EChartsOption>({
  title: { text: '销售统计' },
  xAxis: { type: 'category', data: ['一月', '二月'] },
  yAxis: { type: 'value' },
  series: [{ type: 'bar', data: [120, 200] }]
});

// ✅ 类型安全，智能提示
chartOption.value.title = { text: '新标题' };

---

⚠️ 常见问题

问题1：类型过于严格

解决：

// 使用Partial允许部分配置
const partialOption: Partial<EChartsOption> = {
  title: { text: '测试' }
  // 其他属性可选
};

// 或使用any绕过检查（不推荐）
const flexibleOption: any = dynamicConfig;

问题2：联合类型推断失败

解决：

// ❌ 错误：TypeScript无法推断具体类型
const series = Math.random() > 0.5
  ? { type: 'line', data: [10] }
  : { type: 'bar', data: [10] };

// ✅ 正确：使用类型断言
const series = (Math.random() > 0.5
  ? { type: 'line', data: [10] }
  : { type: 'bar', data: [10] }) as LineSeriesOption | BarSeriesOption;

---

🎯 最佳实践

1. 导出常用类型

// types/echarts.ts
export type {
  EChartsOption,
  LineSeriesOption,
  BarSeriesOption,
  PieSeriesOption,
  XAXisOption,
  YAXisOption
} from 'echarts';

export type ChartTheme = 'light' | 'dark' | 'vintage';
export type ChartRenderer = 'canvas' | 'svg';

export interface ChartConfig {
  theme?: ChartTheme;
  renderer?: ChartRenderer;
  autoResize?: boolean;
}

2. 泛型工具函数

function createSeries<T extends 'line' | 'bar'>(
  type: T,
  data: number[]
): T extends 'line' ? LineSeriesOption : BarSeriesOption {
  return {
    type,
    data
  } as any;
}

// 使用
const lineSeries = createSeries('line', [10, 20]); // 类型为LineSeriesOption
const barSeries = createSeries('bar', [10, 20]);   // 类型为BarSeriesOption

---

📊 性能指标

操作	影响	说明
类型检查	编译时	无运行时开销
类型推断	编译时	复杂类型可能增加编译时间
类型声明文件	包体积+500KB	仅开发环境

---

🔗 相关链接

• React Hook封装
• Vue3 Composition API

---

💎 总结

TypeScript核心价值：

• ✅ 编译时类型安全
• ✅ IDE智能提示
• ✅ 重构友好
• ✅ 文档即代码

关键原则：

1. 始终使用类型：避免any
2. 利用推断：让TS自动推断
3. 自定义工具类型：简化重复配置
4. 导出公共类型：团队共享

掌握TypeScript，让ECharts开发更安全！🔒