fix: ref unable to obtain chart instance

packages/plots/src/components/base/index.tsx

@@ -19,12 +19,23 @@ export const BaseChart: ForwardRefExoticComponent<PropsWithoutRef<CommonConfig>
     loading,
     loadingTemplate,
     errorTemplate,
+    onReady,
     ...rest
   } = config;
 
-  const { chart, container } = useChart<Chart, CommonConfig>(Plots[chartType], rest);
-
-  useImperativeHandle(ref, () => chart.current!, [chart.current]);
+  const { chart, container } = useChart<Chart, CommonConfig>(Plots[chartType], {
+    ...rest,
+    onReady: (chartInstance) => {
+      if (ref) {
+        if (typeof ref === 'function') {
+          ref(chartInstance);
+        } else {
+          (ref as React.MutableRefObject<Chart>).current = chartInstance;
+        }
+      }
+      onReady?.(chartInstance);
+    },
+  });
 
   return (
     <ErrorBoundary errorTemplate={errorTemplate}>

packages/plots/tests/plots/ref-spec.tsx

@@ -0,0 +1,45 @@
+import { render } from '@ant-design/charts-util';
+import React, { act } from 'react';
+import { Column } from '../../src';
+
+const ref = React.createRef();
+
+describe('get chart instance by ref', () => {
+  let container;
+  const data = [
+    {
+      date: '2010-01',
+      scales: 1998,
+    },
+    {
+      date: '2010-02',
+      scales: 1850,
+    },
+    {
+      date: '2010-03',
+      scales: 1250,
+    },
+  ];
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+  afterEach(() => {
+    document.body.removeChild(container);
+    container = null;
+  });
+
+  it('chart render', async () => {
+    const config = {
+      data,
+      xField: 'date',
+      yField: 'scales',
+      width: 600,
+      height: 300,
+    };
+    act(() => {
+      render(<Column {...config} ref={ref} />, container);
+    });
+    expect(ref.current).not.toBeUndefined();
+  });
+});

site/docs/manual/getting-started.zh.md

@@ -91,3 +91,28 @@ const Page: React.FC = () => {
 };
 export default Page;
 ```
+
+## 获取图表实例
+
+图表实例用于后续事件监听、绑定、图表下载等，目前提供 2 种获取方式。
+
+```tsx | pure
+// 通过 onReady 配置获取
+const config = {
+  onReady: ( plot ) => {
+    const { chart } = plot;
+    chart.on('element:click', (evt) => {
+      console.log(evt.target)
+    })
+  }
+}
+
+// 通过 ref 获取
+const ref = useRef(null);
+return (
+  <div>
+    <button onClick={() => console.log(ref.current)}>点我</button>
+    <Line {...config} ref={ref} />
+  </div>
+);
+```