This guide covers legacy components, deprecated features, and upgrade paths for BizCharts users migrating from older versions or transitioning from other visualization libraries.
BizCharts maintains backward compatibility by providing legacy component aliases and wrappers for deprecated features.
The Guide component was the legacy annotation system, now replaced by the more powerful Annotation namespace.
/**
* Legacy Guide component (deprecated)
* @deprecated Use Annotation components instead
*/
declare const Guide: {
Arc: React.FC<any>;
DataMarker: React.FC<any>;
DataRegion: React.FC<any>;
Html: React.FC<any>;
Image: React.FC<any>;
Line: React.FC<any>;
Region: React.FC<any>;
Text: React.FC<any>;
RegionFilter: React.FC<any>;
};Migration Example:
// ❌ Old way (deprecated)
import { Guide } from "bizcharts";
function OldChart() {
return (
<Chart height={400} data={data}>
<Guide.Text
position={['50%', '10%']}
content="Title"
style={{ fontSize: 16 }}
/>
<Guide.Line
start={['min', 'mean']}
end={['max', 'mean']}
lineStyle={{ stroke: '#red' }}
/>
</Chart>
);
}
// ✅ New way (recommended)
import { Annotation } from "bizcharts";
function NewChart() {
return (
<Chart height={400} data={data}>
<Annotation.Text
position={['50%', '10%']}
content="Title"
style={{ fontSize: 16 }}
/>
<Annotation.Line
start={['min', 'mean']}
end={['max', 'mean']}
style={{ stroke: '#red' }}
/>
</Chart>
);
}The Coord component was the legacy coordinate system, now replaced by the Coordinate component.
/**
* Legacy Coord component (deprecated)
* @deprecated Use Coordinate component instead
*/
declare const Coord: React.FC<{
type?: string;
rotate?: number;
scale?: [number, number];
translate?: [number, number];
reflect?: 'x' | 'y';
transpose?: boolean;
[key: string]: any;
}>;Migration Example:
// ❌ Old way (deprecated)
import { Coord } from "bizcharts";
function OldChart() {
return (
<Chart height={400} data={data}>
<Coord type="polar" transpose />
<Interval position="x*y" />
</Chart>
);
}
// ✅ New way (recommended)
import { Coordinate } from "bizcharts";
function NewChart() {
return (
<Chart height={400} data={data}>
<Coordinate type="polar" transpose />
<Interval position="x*y" />
</Chart>
);
}The useRootChart hook has been renamed to useChartInstance for better clarity.
/**
* Legacy useRootChart hook (deprecated)
* @deprecated Use useChartInstance instead
*/
function useRootChart(): Chart;
/**
* Current useChartInstance hook (recommended)
*/
function useChartInstance(): Chart;Migration Example:
// ❌ Old way (deprecated)
import { useRootChart } from "bizcharts";
function ChartComponent() {
const chart = useRootChart();
// Use chart instance
}
// ✅ New way (recommended)
import { useChartInstance } from "bizcharts";
function ChartComponent() {
const chart = useChartInstance();
// Use chart instance
}Major changes when upgrading from version 3.x to 4.x:
// ❌ BizCharts 3.x
import { Chart, Geom, Axis, Tooltip, Legend } from "bizcharts";
// ✅ BizCharts 4.x
import { Chart, Line, Interval, Point, Axis, Tooltip, Legend } from "bizcharts";// ❌ BizCharts 3.x
<Chart>
<Geom type="line" position="x*y" />
<Geom type="point" position="x*y" />
</Chart>
// ✅ BizCharts 4.x
<Chart>
<Line position="x*y" />
<Point position="x*y" />
</Chart>// ❌ BizCharts 3.x
<Chart scale={{ x: { type: 'time' }, y: { min: 0 } }}>
// ✅ BizCharts 4.x - Use meta prop
<Chart data={data} scale={{ x: { type: 'time' }, y: { min: 0 } }}>
// or configure in chart components
<Chart data={data}>
<Axis name="x" type="time" />
<Axis name="y" min={0} />
</Chart>// ❌ BizCharts 3.x
<Tooltip crosshairs={{ type: 'line' }} />
// ✅ BizCharts 4.x
<Tooltip showCrosshairs crosshairs={{ type: 'line' }} />Migrating from pure @antv/g2 to BizCharts React components:
// ❌ Pure G2
import { Chart } from '@antv/g2';
const chart = new Chart({
container: 'container',
width: 400,
height: 300
});
chart.data(data);
chart.line().position('x*y');
chart.render();
// ✅ BizCharts
import { Chart, Line } from "bizcharts";
function MyChart() {
return (
<Chart width={400} height={300} data={data}>
<Line position="x*y" />
</Chart>
);
}// ❌ Pure G2
chart.on('plot:click', (ev) => {
console.log('Clicked:', ev);
});
// ✅ BizCharts
function MyChart() {
const handlePlotClick = (ev) => {
console.log('Clicked:', ev);
};
return (
<Chart onPlotClick={handlePlotClick}>
<Line position="x*y" />
</Chart>
);
}// ❌ Pure G2
const chart = new Chart({ /* config */ });
// Direct access to chart methods
// ✅ BizCharts
import { useChartInstance } from "bizcharts";
function MyChart() {
const chart = useChartInstance();
useEffect(() => {
if (chart) {
// Access G2 chart methods
chart.annotation().text({ /* config */ });
}
}, [chart]);
return <Chart><Line position="x*y" /></Chart>;
}// ❌ Common mistake
<Geom type="interval" position="x*y" />
// ✅ Correct approach
<Interval position="x*y" />// ❌ Old event format
<Chart onPlotClick={(ev) => console.log(ev)}>
// ✅ New event format
<Chart
onEvent={(chart, event) => {
if (event.type === 'plot:click') {
console.log(event);
}
}}
>// ❌ Deprecated scale prop
<Chart scale={{ x: { type: 'time' } }}>
// ✅ Use Axis components or meta
<Chart meta={{ x: { type: 'time' } }}>
// or
<Chart>
<Axis name="x" type="time" />
</Chart>BizCharts provides a compatibility layer for most legacy features:
// Legacy imports still work
import { Guide, Coord, useRootChart } from "bizcharts";
// But show deprecation warnings in development mode
console.warn('Guide component is deprecated. Use Annotation instead.');For large codebases, consider using automated migration tools:
# Example migration script usage (hypothetical)
npx bizcharts-migrate --from=3.x --to=4.x --path=./srcUse ESLint rules to catch deprecated usage:
{
"rules": {
"bizcharts/no-deprecated-guide": "warn",
"bizcharts/no-deprecated-coord": "warn",
"bizcharts/prefer-new-hooks": "error"
}
}For migration assistance:
Remember to test thoroughly after migration and update your dependencies gradually to ensure compatibility.