react-use-echarts 1.0.1 → 1.0.3

package/README.md

@@ -1,5 +1,7 @@
 # react-use-echarts
 
+> [中文](./README.zh-CN.md) | [English](./README.md)
+
 [![NPM version](https://img.shields.io/npm/v/react-use-echarts.svg)](https://www.npmjs.com/package/react-use-echarts)
 [![NPM downloads](https://img.shields.io/npm/dm/react-use-echarts.svg)](https://www.npmjs.com/package/react-use-echarts)
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/chensid/react-use-echarts/npm-publish.yml)](https://github.com/chensid/react-use-echarts/actions/workflows/npm-publish.yml)
@@ -52,26 +54,12 @@ import type { EChartsOption } from 'echarts';
 function MyChart() {
   const chartRef = useRef<HTMLDivElement>(null);
 
-  const options: EChartsOption = {
-    title: {
-      text: 'Basic Line Chart Example'
-    },
-    xAxis: {
-      type: 'category',
-      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
-    },
-    yAxis: {
-      type: 'value'
-    },
-    series: [{
-      data: [820, 932, 901, 934, 1290, 1330, 1320],
-      type: 'line',
-      smooth: true
-    }]
-  };
-
   useEcharts(chartRef, {
-    option: options
+    option: {
+      xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] },
+      yAxis: { type: 'value' },
+      series: [{ data: [820, 932, 901, 934, 1290, 1330, 1320], type: 'line' }]
+    }
   });
 
   return <div ref={chartRef} style={{ width: '100%', height: '400px' }} />;
@@ -184,15 +172,16 @@ function DynamicChart() {
 }
 ```
 
-### Built-in Themes
+### Themes
 
-The library includes three built-in themes: `light`, `dark`, and `macarons`.
+Built-in themes: `light`, `dark`, `macarons`, or pass a custom theme object.
 
 ```tsx
-import { useRef } from 'react';
+import { useRef, useMemo } from 'react';
 import { useEcharts } from 'react-use-echarts';
 
-function ThemedChart() {
+// Using built-in theme
+function BuiltinThemeChart() {
   const chartRef = useRef<HTMLDivElement>(null);
 
   useEcharts(chartRef, {
@@ -206,21 +195,14 @@ function ThemedChart() {
 
   return <div ref={chartRef} style={{ width: '100%', height: '400px' }} />;
 }
-```
-
-### Custom Theme
-
-```tsx
-import { useRef } from 'react';
-import { useEcharts } from 'react-use-echarts';
 
-function CustomThemedChart() {
+// Using custom theme (recommend using useMemo to avoid unnecessary re-renders)
+function CustomThemeChart() {
   const chartRef = useRef<HTMLDivElement>(null);
-
-  const customTheme = {
+  const customTheme = useMemo(() => ({
     color: ['#fc8452', '#9a60b4', '#ea7ccc'],
     backgroundColor: '#1e1e1e'
-  };
+  }), []);
 
   useEcharts(chartRef, {
     option: {
@@ -237,7 +219,7 @@ function CustomThemedChart() {
 
 ### Chart Linkage
 
-Connect multiple charts to synchronize their interactions (e.g., tooltip, highlight).
+Connect multiple charts using the `group` option to enable synchronized interactions (e.g., tooltip, highlight).
 
 ```tsx
 import { useRef } from 'react';
@@ -246,7 +228,6 @@ import { useEcharts } from 'react-use-echarts';
 function LinkedCharts() {
   const chartRef1 = useRef<HTMLDivElement>(null);
   const chartRef2 = useRef<HTMLDivElement>(null);
-
   const xAxisData = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
 
   useEcharts(chartRef1, {
@@ -280,12 +261,13 @@ function LinkedCharts() {
 
 ### Lazy Initialization
 
-Only initialize charts when they enter the viewport, great for pages with many charts.
+Initialize charts only when they enter the viewport. Suitable for pages with multiple charts. Default parameters: `rootMargin: '50px'`, `threshold: 0.1`.
 
 ```tsx
 import { useRef } from 'react';
 import { useEcharts } from 'react-use-echarts';
 
+// Using default configuration
 function LazyChart() {
   const chartRef = useRef<HTMLDivElement>(null);
 
@@ -295,13 +277,13 @@ function LazyChart() {
       yAxis: { type: 'value' },
       series: [{ data: [120, 200, 150], type: 'bar' }]
     },
-    lazyInit: true // Chart will only initialize when scrolled into view
+    lazyInit: true
   });
 
   return <div ref={chartRef} style={{ width: '100%', height: '400px' }} />;
 }
 
-// With custom IntersectionObserver options
+// Custom IntersectionObserver configuration
 function LazyChartWithOptions() {
   const chartRef = useRef<HTMLDivElement>(null);
 
@@ -312,7 +294,7 @@ function LazyChartWithOptions() {
       series: [{ data: [120, 200, 150], type: 'bar' }]
     },
     lazyInit: {
-      rootMargin: '100px', // Pre-load when 100px away from viewport
+      rootMargin: '100px',
       threshold: 0.1
     }
   });
@@ -323,7 +305,7 @@ function LazyChartWithOptions() {
 
 ### SVG Renderer
 
-Use SVG renderer instead of Canvas for better accessibility and print quality.
+Use SVG renderer for better accessibility and print quality.
 
 ```tsx
 import { useRef } from 'react';
@@ -338,7 +320,7 @@ function SVGChart() {
       yAxis: { type: 'value' },
       series: [{ data: [120, 200, 150], type: 'bar' }]
     },
-    renderer: 'svg'
+    renderer: 'svg' // Default is 'canvas'
   });
 
   return <div ref={chartRef} style={{ width: '100%', height: '400px' }} />;
@@ -347,6 +329,8 @@ function SVGChart() {
 
 ### Accessing ECharts Instance
 
+Access the ECharts instance via `getInstance()` to perform advanced operations like exporting images.
+
 ```tsx
 import { useRef } from 'react';
 import { useEcharts } from 'react-use-echarts';
@@ -365,12 +349,7 @@ function ChartWithInstance() {
   const exportImage = () => {
     const instance = getInstance();
     if (instance) {
-      const url = instance.getDataURL({
-        type: 'png',
-        pixelRatio: 2,
-        backgroundColor: '#fff'
-      });
-      // Download or use the image URL
+      const url = instance.getDataURL({ type: 'png', pixelRatio: 2, backgroundColor: '#fff' });
       const link = document.createElement('a');
       link.download = 'chart.png';
       link.href = url;
@@ -389,6 +368,8 @@ function ChartWithInstance() {
 
 ### Manual Resize
 
+Manually trigger chart resize (usually handled automatically by ResizeObserver).
+
 ```tsx
 import { useRef } from 'react';
 import { useEcharts } from 'react-use-echarts';
@@ -404,75 +385,73 @@ function ResizableChart() {
     }
   });
 
-  // Manually trigger resize after some container size change
-  const handleContainerResize = () => {
-    resize();
-  };
-
   return (
     <div>
-      <button onClick={handleContainerResize}>Trigger Resize</button>
+      <button onClick={resize}>Trigger Resize</button>
       <div ref={chartRef} style={{ width: '100%', height: '400px' }} />
     </div>
   );
 }
 ```
 
+### Utilities
+
+Advanced scenarios can directly use exported utility functions:
+
+```tsx
+import {
+  getCachedInstance,
+  clearInstanceCache,
+  getGroupInstances,
+  updateGroup,
+  addToGroup,
+  removeFromGroup,
+} from 'react-use-echarts';
+```
+
+- `getCachedInstance` / `clearInstanceCache`: Query or clear internal instance cache
+- `getGroupInstances` / `addToGroup` / `removeFromGroup` / `updateGroup`: Manually manage ECharts group linkage
+
 ## 📖 API
 
 ### useEcharts
 
-The main hook for using ECharts in React components.
+The main Hook for using ECharts in React components.
 
 #### Parameters
 
 ```tsx
-import { useRef } from 'react';
-import type { EChartsOption } from 'echarts';
-import type { UseEchartsOptions } from 'react-use-echarts';
-import { useEcharts } from 'react-use-echarts';
-
 const chartRef = useRef<HTMLDivElement>(null);
 
-const someEchartsOption: EChartsOption = {
-  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
-  yAxis: { type: 'value' },
-  series: [{ type: 'line', data: [120, 200, 150] }],
-};
-
-const options: UseEchartsOptions = {
-  option: someEchartsOption, // Required: ECharts options
-  theme: 'dark', // Optional: 'light' | 'dark' | 'macarons' | custom object | null
-  renderer: 'canvas', // Optional: 'canvas' | 'svg' (default: 'canvas')
-  lazyInit: false, // Optional: boolean | IntersectionObserverInit
-  group: 'my-group', // Optional: Group ID for chart linkage
-  setOptionOpts: { notMerge: false }, // Optional: Default setOption options
-  showLoading: false, // Optional: Show loading state
-  loadingOption: { text: 'Loading…' }, // Optional: Loading options
+const { setOption, getInstance, resize } = useEcharts(chartRef, {
+  option: { /* EChartsOption */ }, // Required
+  theme: 'dark', // 'light' | 'dark' | 'macarons' | custom object | null
+  renderer: 'canvas', // 'canvas' | 'svg', default 'canvas'
+  lazyInit: false, // boolean | IntersectionObserverInit
+  group: 'my-group', // Group ID for chart linkage
+  setOptionOpts: { notMerge: false }, // Default options for setOption
+  showLoading: false, // Whether to show loading state
+  loadingOption: { text: 'Loading…' }, // Loading configuration
   onEvents: {
     click: {
-      handler: (params) => {
-        console.log(params);
-      },
-      query: 'series', // Optional: Event query
+      handler: (params) => console.log(params),
+      query: 'series', // Optional: event query condition
     },
   },
-};
-
-const { setOption, getInstance, resize } = useEcharts(chartRef, options);
+});
 ```
 
 #### Options
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `option` | `EChartsOption` | **required** | ECharts configuration options |
+| `option` | `EChartsOption` | **Required** | ECharts configuration option |
 | `theme` | `'light' \| 'dark' \| 'macarons' \| object \| null` | `null` | Theme name or custom theme object |
 | `renderer` | `'canvas' \| 'svg'` | `'canvas'` | Renderer type |
-| `lazyInit` | `boolean \| IntersectionObserverInit` | `false` | Lazy initialization config |
-| `group` | `string` | - | Group ID for chart linkage |
+| `lazyInit` | `boolean \| IntersectionObserverInit` | `false` | Lazy initialization configuration |
+| `group` | `string` | - | Chart linkage group ID |
 | `setOptionOpts` | `SetOptionOpts` | - | Default options for setOption |
-| `showLoading` | `boolean` | `false` | Show loading state |
+| `showLoading` | `boolean` | `false` | Whether to show loading state |
 | `loadingOption` | `object` | - | Loading configuration |
 | `onEvents` | `EChartsEvents` | - | Event handlers |
 
@@ -486,8 +465,8 @@ const { setOption, getInstance, resize } = useEcharts(chartRef, options);
 }
 ```
 
-- **`setOption`**: Update chart options dynamically
-- **`getInstance`**: Get the ECharts instance (returns `undefined` before initialization)
+- **`setOption`**: Dynamically update chart configuration
+- **`getInstance`**: Get ECharts instance (returns `undefined` before initialization)
 - **`resize`**: Manually trigger chart resize
 
 ### Theme Utilities
@@ -501,26 +480,16 @@ import {
   registerBuiltinThemes,
 } from 'react-use-echarts';
 
-// Get all available built-in theme names
-const themes = getAvailableThemes(); // ['light', 'dark', 'macarons']
-
-// Check if a theme name is built-in
+getAvailableThemes(); // ['light', 'dark', 'macarons']
 isBuiltinTheme('dark'); // true
-isBuiltinTheme('custom'); // false
-
-// Get built-in theme configuration
-const darkTheme = getBuiltinTheme('dark');
-
-// Register a custom theme globally
-registerCustomTheme('my-theme', { color: ['#ff0000', '#00ff00'] });
-
-// Register built-in themes to ECharts (auto-called on module load, rarely needed manually)
-registerBuiltinThemes();
+getBuiltinTheme('dark'); // Get built-in theme configuration
+registerCustomTheme('my-theme', { color: ['#ff0000', '#00ff00'] }); // Register custom theme
+registerBuiltinThemes(); // Register built-in themes (automatically called on module load, usually no need to call manually)
 ```
 
 ### useLazyInit
 
-A standalone hook for lazy initialization using IntersectionObserver.
+Standalone lazy initialization Hook based on IntersectionObserver.
 
 ```tsx
 import { useRef } from 'react';
@@ -528,8 +497,6 @@ import { useLazyInit } from 'react-use-echarts';
 
 function MyComponent() {
   const elementRef = useRef<HTMLDivElement>(null);
-
-  // Returns true when element enters viewport
   const isInView = useLazyInit(elementRef, {
     rootMargin: '50px',
     threshold: 0.1
@@ -547,77 +514,6 @@ function MyComponent() {
 
 We welcome all contributions. Please read our [contributing guidelines](CONTRIBUTING.md) first. You can submit any ideas as [pull requests](https://github.com/chensid/react-use-echarts/pulls) or as [GitHub issues](https://github.com/chensid/react-use-echarts/issues).
 
-## 🔄 Migration Guide
-
-### From v0.0.11 to v1.0
-
-#### Breaking Change: External Ref Management
-
-The `useEcharts` hook no longer returns a `chartRef`. Instead, you now create and manage the ref externally:
-
-**Before (v0.0.11):**
-```tsx
-import { useEcharts } from 'react-use-echarts';
-
-function MyChart() {
-  const { chartRef, setOption, getInstance } = useEcharts({
-    option: { /* ... */ }
-  });
-
-  return <div ref={chartRef} style={{ width: '100%', height: '400px' }} />;
-}
-```
-
-**After (v1.0):**
-```tsx
-import { useRef } from 'react';
-import { useEcharts } from 'react-use-echarts';
-
-function MyChart() {
-  const chartRef = useRef<HTMLDivElement>(null);
-
-  const { setOption, getInstance, resize } = useEcharts(chartRef, {
-    option: { /* ... */ }
-  });
-
-  return <div ref={chartRef} style={{ width: '100%', height: '400px' }} />;
-}
-```
-
-#### New Features in v1.0
-
-- **Built-in themes**: Use `theme: 'light' | 'dark' | 'macarons'` or pass a custom theme object
-- **Chart linkage**: Connect charts using the `group` option
-- **Lazy initialization**: Use `lazyInit: true` or custom `IntersectionObserverInit` options
-- **SVG renderer**: Use `renderer: 'svg'` for better accessibility and print quality
-- **Manual resize**: New `resize()` function returned from the hook
-
-#### Important Notes for Custom Themes
-
-When using custom theme objects, **memoize them** to avoid unnecessary chart recreation:
-
-```tsx
-import { useRef, useMemo } from 'react';
-import { useEcharts } from 'react-use-echarts';
-
-function MyChart() {
-  const chartRef = useRef<HTMLDivElement>(null);
-
-  // ✅ Good: Memoized theme object
-  const customTheme = useMemo(() => ({
-    color: ['#fc8452', '#9a60b4', '#ea7ccc'],
-    backgroundColor: '#1e1e1e'
-  }), []);
-
-  useEcharts(chartRef, {
-    option: { /* ... */ },
-    theme: customTheme
-  });
-
-  return <div ref={chartRef} style={{ width: '100%', height: '400px' }} />;
-}
-```
-
 ## 📝 Changelog
 
 Detailed changes for each release are documented in the [release notes](https://github.com/chensid/react-use-echarts/releases).