vue-echarts 8.2.0 → 8.3.1

package/README.md

@@ -121,8 +121,8 @@ Drop `<script>` inside your HTML file and access the component via `window.VueEC
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/echarts@6.1.0"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue@3.5.41"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue-echarts@8.2.0"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue@3.5.42"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue-echarts@8.3.1"></script>
 ```
 
 <!-- scripts:end -->
@@ -152,6 +152,8 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/demo).
 
   Pass an empty string to use ECharts' default theme while overriding an injected theme.
 
+  ECharts recreates its model when changing themes. Vue ECharts reapplies the latest automatic option, but uncontrolled interaction state (such as legend selection or data zoom) may reset. Keep state that must survive a rebuild in `option`.
+
   Injection key: `THEME_KEY`.
 
 - `option: object`
@@ -160,9 +162,14 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/demo).
   Temporarily removing the prop pauses automatic updates without letting a later theme change roll the chart back to its initial option.
 
   #### Smart update
-  - If you supply `update-options` (via prop or injection), Vue ECharts forwards it directly to `setOption` and skips the planner. After you remove it, the first smart update rebuilds once to establish a safe structural baseline.
+
+  Reactive updates describe the complete configuration. Vue ECharts preserves existing models where merging can apply that configuration, and rebuilds when necessary to remove stale settings. A rebuild can reset interaction state such as legend selections and data zoom.
+
+  - If you supply `update-options` (via prop or injection), Vue ECharts forwards it directly to `setOption` and skips the planner. After you remove it, the first smart source-option update rebuilds once to establish a safe structural baseline.
+  - A failed option or theme submission invalidates that baseline. The next smart update rebuilds instead of trusting a potentially partial update.
+  - Automatic option, theme, and slot changes are batched after Vue updates. `clear()` takes effect immediately and cancels already queued automatic work; later changes can populate the chart again.
   - Manual `setOption` calls (only available when `manual-update` is `true`) behave like native ECharts, honouring only the per-call override you pass in and are not carried across re-initializations.
-  - Updates containing a graphic element `$action` keep normal merge for `graphic` so the command can target the existing element tree; safe removals of unrelated components still use `replaceMerge`.
+  - Updates containing a graphic element `$action` keep normal merge for `graphic` so the command can target the existing element tree; safe removals of unrelated components still use `replaceMerge`. Changes requiring a full rebuild cannot be applied together with these commands. For complete snapshot semantics, describe the resulting graphic tree without `$action` commands.
   - Otherwise, Vue ECharts analyses the change: component removals, reordering, and deletions inside anonymous components use `replaceMerge` when it can reproduce the requested order; deletions inside ID-matched components, identity ordering that `replaceMerge` cannot reproduce, newly introduced or shrinking non-component arrays, first-time ARIA configuration, and other risky changes fall back to `notMerge: true`.
 
 - `update-options: object`
@@ -216,6 +223,10 @@ const chart = ref<InstanceType<typeof VChart> | null>(null);
 
 Vue 3.5's `useTemplateRef` can infer this type automatically.
 
+`Exposed` describes the chart methods and read-only `chart` and `root` properties exposed through a template ref. It includes `setOption` and the other methods listed below; use `InstanceType<typeof VChart>` when you also need Vue's component instance properties.
+
+Libraries can re-export or wrap `VChart` and the `vue-echarts/graphic` components while emitting their own TypeScript declarations. The root entry exports `Component`, the shared Vue component definition helper, and `Slots`, the Vue `SlotsType` metadata used by `VChart`, so inferred declarations can reference public types. The graphic entry exports its corresponding `GraphicComponent` type. For callable slots, use `InstanceType<typeof VChart>["$slots"]`; augment `VChartSlotsExtension` in `vue-echarts` to declare additional slots. The graphic entry re-exports the same extension interface.
+
 ### Events
 
 You can bind events with Vue's `v-on` directive.
@@ -542,6 +553,8 @@ Read more at [ECharts `option.graphic` →](https://echarts.apache.org/en/option
 > - Path components accept `auto-batch` to opt into ZRender's Canvas path batching.
 > - The `option` prop may be omitted for graphic-only charts.
 > - `#graphic` overrides `option.graphic`. In `manual-update` mode, call `chartRef.setOption(...)` to apply changes.
+> - Wrapper components and Fragments preserve their rendered graphic order. Compatible property changes update only changed elements, preserving unchanged elements and their running animations. Removing fields, changing types, or changing tree structure rebuilds the graphic component.
+> - Graphic-only changes omit unrelated source options when safe. Explicit `notMerge` or `replaceMerge` targeting other components still submits the full source option.
 
 <details>
 <summary>Usage</summary>

package/README.zh-Hans.md

@@ -121,8 +121,8 @@ import "echarts";
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/echarts@6.1.0"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue@3.5.41"></script>
-<script src="https://cdn.jsdelivr.net/npm/vue-echarts@8.2.0"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue@3.5.42"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue-echarts@8.3.1"></script>
 ```
 
 <!-- scripts:end -->
@@ -150,6 +150,8 @@ app.component('VChart', VueECharts)
 
   要应用的主题。请参考 `echarts.init` 的 `theme` 参数。[前往 →](https://echarts.apache.org/zh/api.html#echarts.init)
 
+  ECharts 在切换主题时会重建模型。Vue ECharts 会重新应用最新的自动更新配置，但未受控的交互状态（如图例选择、数据缩放）可能重置。需要跨重建保留的状态应维护在 `option` 中。
+
   传入空字符串可以在覆盖注入主题的同时使用 ECharts 默认主题。
 
   Inject 键名：`THEME_KEY`。
@@ -160,9 +162,15 @@ app.component('VChart', VueECharts)
   暂时移除该 prop 会暂停自动更新，之后的主题变更也不会让图表回退到初始 option。
 
   #### 智能更新
-  - 如果提供了 `update-options`（或通过 inject 注入），Vue ECharts 会直接把它传给 `setOption`，不会执行智能计划。移除它之后，首次智能更新会重建一次，以建立可靠的结构基线。
+
+  自动 option、theme 和插槽变化会在 Vue 更新后合并处理。`clear()` 立即生效并取消已经排队的自动更新，后续变化仍可重新填充图表。
+
+  响应式更新描述完整配置。Vue ECharts 会在合并能够正确应用配置时保留现有模型，并在必要时通过重建清除旧配置。重建可能重置图例选择、数据缩放等交互状态。
+
+  - 如果提供了 `update-options`（或通过 inject 注入），Vue ECharts 会直接把它传给 `setOption`，不会执行智能计划。移除它之后，首次源 option 智能更新会重建一次，以建立可靠的结构基线。
+  - option 或主题提交失败会使结构基线失效。下一次智能更新会重建，避免依赖可能只完成了一部分的更新。
   - 手动调用 `setOption`（仅当 `manual-update` 为 `true` 时可用）与原生 ECharts 保持一致，只使用本次调用传入的参数，重新初始化后不会保留这些调用的效果。
-  - 如果更新中有 graphic 元素使用 `$action`，`graphic` 会保留普通合并，让命令能够作用于现有元素树；无关组件的安全删除仍会使用 `replaceMerge`。
+  - 如果更新中有 graphic 元素使用 `$action`，`graphic` 会保留普通合并，让命令能够作用于现有元素树；无关组件的安全删除仍会使用 `replaceMerge`。需要完整重建的变更无法与这些命令一起应用。若需要完整快照语义，请直接描述更新后的 graphic 元素树，不使用 `$action` 命令。
   - 其他情况下，Vue ECharts 会分析差异：组件删除、重排及匿名组件内部的属性删除会在 `replaceMerge` 能还原目标顺序时使用它；已按 ID 匹配的组件内部属性删除、`replaceMerge` 无法还原的身份顺序变化、新增或缩短的非组件数组、首次 ARIA 配置及其他高风险变更会退回 `notMerge: true`。
 
 - `update-options: object`
@@ -216,6 +224,10 @@ const chart = ref<InstanceType<typeof VChart> | null>(null);
 
 Vue 3.5 的 `useTemplateRef` 可以自动推导此类型。
 
+`Exposed` 描述通过模板 ref 暴露的图表方法及只读的 `chart`、`root` 属性，包含 `setOption` 和下文列出的其它方法。如果还需要 Vue 组件实例属性，请使用 `InstanceType<typeof VChart>`。
+
+组件库可以重新导出或包装 `VChart` 及 `vue-echarts/graphic` 组件，并生成自己的 TypeScript 声明。根入口导出共享的 Vue 组件定义辅助类型 `Component` 和 `VChart` 使用的 Vue `SlotsType` 元数据 `Slots`，使推导出的声明能够引用公开类型。graphic 入口导出对应的 `GraphicComponent` 类型。需要可调用的插槽类型时，使用 `InstanceType<typeof VChart>["$slots"]`；需要声明额外插槽时，在 `vue-echarts` 模块中扩展 `VChartSlotsExtension`。graphic 入口重新导出的是同一个扩展接口。
+
 ### 事件
 
 可以使用 Vue 的 `v-on` 指令绑定事件。
@@ -540,6 +552,8 @@ import { GGroup, GRect, GText } from "vue-echarts/graphic";
 > - 路径组件支持通过 `auto-batch` 启用 ZRender 的 Canvas 路径批处理。
 > - 仅使用 graphic 插槽时可以省略 `option` prop。
 > - `#graphic` 会覆盖 `option.graphic`。`manual-update` 模式下需调用 `chartRef.setOption(...)` 提交变更。
+> - 包装组件和 Fragment 中的图形遵循实际渲染顺序。可合并的属性变化只更新变更节点，保留未变更元素及其正在运行的动画。删除字段、改变类型或树结构时，会重建 graphic 组件。
+> - 仅 graphic 变化时，会在安全的情况下省略无关的源配置。显式指定 `notMerge` 或针对其他组件的 `replaceMerge` 时，仍会提交完整源配置。
 
 <details>
 <summary>用法示例</summary>

package/dist/graphic.d.ts

@@ -1,13 +1,7 @@
-import { c as ElementEventAlias, f as PublicComponent, l as FontStyle, p as WithOnce, t as VChartSlotsExtension, u as FontWeight } from "./index-BujxhN-1.js";
+import { d as ElementEventAlias, f as FontStyle, h as WithOnce, p as FontWeight, t as VChartSlotsExtension, u as Component } from "./index-GjFScMW2.js";
 import { ExtractPublicPropTypes, PropType, Slot, SlotsType } from "vue";
 import { ElementEvent } from "echarts/core";
 import { Color, CustomSeriesRenderItemReturn, GraphicComponentOption, PatternObject, TooltipComponentOption } from "echarts";
-//#region src/graphic/types.d.ts
-type GraphicEventName = Exclude<ElementEvent["type"], "globalout">;
-type GraphicOnEventName = `on${GraphicEventName}`;
-type GraphicEventAlias = Exclude<ElementEventAlias, "globalOut">;
-type GraphicEmits = WithOnce<{ [key in GraphicEventName | GraphicEventAlias]: (params: ElementEvent) => boolean | void; }>;
-//#endregion
 //#region src/graphic/props-common.d.ts
 type GraphicDuring = NonNullable<NonNullable<CustomSeriesRenderItemReturn>["during"]>;
 type GraphicExtra = Record<string, unknown> & {
@@ -190,6 +184,9 @@ declare const textPropOverrides: {
 };
 type GraphicCommonProps = Omit<ExtractPublicPropTypes<typeof commonProps>, "width"> & Pick<ExtractPublicPropTypes<typeof textPropOverrides>, "width">;
 //#endregion
+//#region src/graphic/component-type.d.ts
+type GraphicComponentType = "group" | "rect" | "circle" | "ellipse" | "text" | "line" | "polyline" | "polygon" | "image" | "sector" | "ring" | "arc" | "bezierCurve";
+//#endregion
 //#region src/graphic/props-shape.d.ts
 declare const SHAPE_KEYS_BY_TYPE: {
   readonly rect: readonly ["x", "y", "width", "height", "r"];
@@ -234,8 +231,11 @@ declare const shapeProps: {
 };
 type GraphicShapeProps = ExtractPublicPropTypes<typeof shapeProps>;
 //#endregion
-//#region src/graphic/marker.d.ts
-type GraphicComponentType = "group" | "rect" | "circle" | "ellipse" | "text" | "line" | "polyline" | "polygon" | "image" | "sector" | "ring" | "arc" | "bezierCurve";
+//#region src/graphic/types.d.ts
+type GraphicEventName = Exclude<ElementEvent["type"], "globalout">;
+type GraphicOnEventName = `on${GraphicEventName}`;
+type GraphicEventAlias = Exclude<ElementEventAlias, "globalOut">;
+type GraphicEmits = WithOnce<{ [key in GraphicEventName | GraphicEventAlias]: (params: ElementEvent) => boolean | void; }>;
 //#endregion
 //#region src/graphic/component-factory.d.ts
 declare const componentProps: {
@@ -266,7 +266,7 @@ declare const componentProps: {
     default: undefined;
   };
   readonly cornerRadius: import("vue").PropType<number | number[]>;
-  readonly image: import("vue").PropType<string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement>;
+  readonly image: import("vue").PropType<string | HTMLCanvasElement | HTMLImageElement | HTMLVideoElement>;
   readonly sx: NumberConstructor;
   readonly sy: NumberConstructor;
   readonly sWidth: NumberConstructor;
@@ -283,7 +283,7 @@ declare const componentProps: {
   readonly lineHeight: NumberConstructor;
   readonly tag: StringConstructor;
   readonly backgroundColor: import("vue").PropType<string | {
-    image: string | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement;
+    image: string | HTMLCanvasElement | HTMLImageElement | HTMLVideoElement;
   }>;
   readonly padding: import("vue").PropType<number | number[]>;
   readonly margin: import("vue").PropType<number | number[]>;
@@ -406,8 +406,7 @@ declare const componentProps: {
 };
 type NestedShapePropKey = "shape" | "shapeTransition";
 type NestedStylePropKey = "style" | "styleTransition";
-type SpecializedPropKey = GraphicCommonStyleKey | GraphicDisplayablePropKey | GraphicPathPropKey | GraphicPathStyleKey | GraphicTextStyleKey | GraphicImageStyleKey | NestedShapePropKey | NestedStylePropKey | keyof typeof shapeProps;
-type SharedPropKey<T extends GraphicComponentType> = Exclude<Exclude<keyof typeof componentProps, SpecializedPropKey> | GraphicCommonPropKey, T extends "text" ? GraphicTextAttachmentPropKey : never>;
+type SharedPropKey<T extends GraphicComponentType> = Exclude<GraphicCommonPropKey, T extends "text" ? GraphicTextAttachmentPropKey : never>;
 type StylePropKey<T extends GraphicComponentType> = T extends "group" ? never : NestedStylePropKey | (T extends "text" ? GraphicTextCommonStyleKey : GraphicCommonStyleKey) | (T extends keyof typeof SHAPE_KEYS_BY_TYPE ? GraphicPathStyleKey : T extends "text" ? GraphicTextStyleKey : T extends "image" ? GraphicImageStyleKey : never);
 type PathPropKey<T extends GraphicComponentType> = T extends keyof typeof SHAPE_KEYS_BY_TYPE ? NestedShapePropKey | GraphicPathPropKey | (typeof SHAPE_KEYS_BY_TYPE)[T][number] : never;
 type GroupPropKey<T extends GraphicComponentType> = T extends "group" ? GraphicGroupPropKey : never;
@@ -419,22 +418,22 @@ type ComponentProps<T extends GraphicComponentType> = Pick<ComponentPropDefiniti
 type ComponentSlots<T extends GraphicComponentType> = SlotsType<T extends "group" ? {
   default?: Slot;
 } : Record<never, never>>;
-type GraphicComponent<T extends GraphicComponentType> = PublicComponent<ComponentProps<T>, Record<never, never>, GraphicEmits, ComponentSlots<T>>;
+type GraphicComponent<T extends GraphicComponentType> = Component<ComponentProps<T>, Record<never, never>, GraphicEmits, ComponentSlots<T>>;
 //#endregion
 //#region src/graphic/components.d.ts
-declare const GGroup: GraphicComponent<"group">;
-declare const GRect: GraphicComponent<"rect">;
-declare const GCircle: GraphicComponent<"circle">;
-declare const GEllipse: GraphicComponent<"ellipse">;
-declare const GText: GraphicComponent<"text">;
-declare const GLine: GraphicComponent<"line">;
-declare const GPolyline: GraphicComponent<"polyline">;
-declare const GPolygon: GraphicComponent<"polygon">;
-declare const GImage: GraphicComponent<"image">;
-declare const GSector: GraphicComponent<"sector">;
-declare const GRing: GraphicComponent<"ring">;
-declare const GArc: GraphicComponent<"arc">;
-declare const GBezierCurve: GraphicComponent<"bezierCurve">;
+export declare const GGroup: GraphicComponent<"group">;
+export declare const GRect: GraphicComponent<"rect">;
+export declare const GCircle: GraphicComponent<"circle">;
+export declare const GEllipse: GraphicComponent<"ellipse">;
+export declare const GText: GraphicComponent<"text">;
+export declare const GLine: GraphicComponent<"line">;
+export declare const GPolyline: GraphicComponent<"polyline">;
+export declare const GPolygon: GraphicComponent<"polygon">;
+export declare const GImage: GraphicComponent<"image">;
+export declare const GSector: GraphicComponent<"sector">;
+export declare const GRing: GraphicComponent<"ring">;
+export declare const GArc: GraphicComponent<"arc">;
+export declare const GBezierCurve: GraphicComponent<"bezierCurve">;
 //#endregion
-export { GArc, GBezierCurve, GCircle, GEllipse, GGroup, GImage, GLine, GPolygon, GPolyline, GRect, GRing, GSector, GText, type GraphicCommonProps, type GraphicEmits, type GraphicEventName, type GraphicOnEventName, type GraphicShapeProps, type VChartSlotsExtension };
+export type { GraphicCommonProps, GraphicComponent, GraphicEmits, GraphicEventName, GraphicOnEventName, GraphicShapeProps, VChartSlotsExtension };
 //# sourceMappingURL=graphic.d.ts.map