From 52938f4a0346fe8da6ec395cbde3cb8ad3d54bc0 Mon Sep 17 00:00:00 2001 From: Justineo Date: Thu, 18 Sep 2025 00:22:55 +0800 Subject: [PATCH] docs: update readme --- README.md | 21 ++++++++------------- README.zh-Hans.md | 19 +++++++------------ src/ECharts.ts | 4 +--- 3 files changed, 16 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 6e18b2b..88dafc7 100644 --- a/README.md +++ b/README.md @@ -151,11 +151,17 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/demo). - `option: object` - ECharts' universal interface. Modifying this prop triggers Vue ECharts to compute an [update plan](#smart-updates) and call `setOption`. Read more [here →](https://echarts.apache.org/en/option.html) + ECharts' universal interface. Modifying this prop triggers Vue ECharts to compute an update plan and call `setOption`. Read more [here →](https://echarts.apache.org/en/option.html) + + #### Smart Update + + - If you supply `update-options` (via prop or injection), Vue ECharts forwards it directly to `setOption` and skips the planner. + - Manual `setOption` calls (only available when `manual-update` is `true`) behave like native ECharts, honouring only the per-call override you pass in. + - Otherwise, Vue ECharts analyses the change: removed objects become `null`, removed arrays become `[]` with `replaceMerge`, ID/anonymous deletions trigger `replaceMerge`, and risky changes fall back to `notMerge: true`. - `update-options: object` - Options for updating chart option. If supplied (or injected), Vue ECharts forwards it directly to `setOption`, skipping the [smart plan](#smart-updates). See `echartsInstance.setOption`'s `opts` parameter [here →](https://echarts.apache.org/en/api.html#echartsInstance.setOption) + Options for updating chart option. If supplied (or injected), Vue ECharts forwards it directly to `setOption`, skipping the [smart update](#smart-update). See `echartsInstance.setOption`'s `opts` parameter [here →](https://echarts.apache.org/en/api.html#echartsInstance.setOption) Injection key: `UPDATE_OPTIONS_KEY`. @@ -181,17 +187,6 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/demo). For performance critical scenarios (having a large dataset) we'd better bypass Vue's reactivity system for `option` prop. By specifying `manual-update` prop with `true` and not providing `option` prop, the dataset won't be watched any more. After doing so, you need to retrieve the component instance with `ref` and manually call `setOption` method to update the chart (manual `setOption` calls are ignored when `manual-update` is `false`). -#### Smart updates - -Vue ECharts analyses each change to `option` before invoking `setOption`: - -- Removed config objects (`legend`, `tooltip`, etc.) are replaced with `null` automatically so ECharts clears them. -- Removed arrays (`series`, `dataset`, …) are converted to empty arrays and marked via `replaceMerge` so old data disappears. -- If the diff looks risky (shrinking `options`/`media`, dropping scalar values), the component falls back to `notMerge: true` to rebuild the chart safely. -- Supplying `update-options` (or providing it via inject) bypasses the planner and uses your configuration as-is. - -Reactive updates use this logic by default. Manual `setOption` calls (only available when `manual-update` is `true`) behave like native ECharts (apart from slot patching) and honour only the per-call override you provide. - ### Events You can bind events with Vue's `v-on` directive. diff --git a/README.zh-Hans.md b/README.zh-Hans.md index f7ecb04..8df31c8 100644 --- a/README.zh-Hans.md +++ b/README.zh-Hans.md @@ -153,9 +153,15 @@ app.component('v-chart', VueECharts) ECharts 的万能接口。修改这个 prop 会触发 ECharts 实例的 `setOption` 方法。查看[详情 →](https://echarts.apache.org/zh/option.html) + #### 智能更新 + + - 如果提供了 `update-options`（或通过 inject 注入），Vue ECharts 会直接把它传给 `setOption`，不会执行智能计划。 + - 手动调用 `setOption`（仅当 `manual-update` 为 `true` 时可用）与原生 ECharts 保持一致，只使用本次调用传入的参数。 + - 其他情况下，Vue ECharts 会分析差异：删除的对象写入 `null`，删除的数组写入 `[]` 并加入 `replaceMerge`，ID/匿名项减少时追加 `replaceMerge`，风险较高的变更会退回 `notMerge: true`。 + - `update-options: object` - 图表更新的配置项。一旦提供（或通过 inject 注入），Vue ECharts 会直接把它传给 `setOption`，并跳过[智能更新](#智能更新)。请参考 `echartsInstance.setOption` 的 `opts` 参数。[前往 →](https://echarts.apache.org/zh/api.html#echartsInstance.setOption) + 图表更新的配置项。一旦提供（或通过 inject 注入），Vue ECharts 会直接把它传给 `setOption` 并跳过智能更新。请参考 `echartsInstance.setOption` 的 `opts` 参数。[前往 →](https://echarts.apache.org/zh/api.html#echartsInstance.setOption) Inject 键名：`UPDATE_OPTIONS_KEY`。 @@ -181,17 +187,6 @@ app.component('v-chart', VueECharts) 在性能敏感（数据量很大）的场景下，我们最好对于 `option` prop 绕过 Vue 的响应式系统。当将 `manual-update` 指定为 `true` 且不传入 `option` prop 时，数据将不会被监听。此时需要用 `ref` 获取组件实例并手动调用 `setOption` 来更新图表（当 `manual-update` 为 `false` 时，手动调用 `setOption` 会被忽略）。 -### 智能更新 - -Vue ECharts 在调用 `setOption` 之前会分析每次 `option` 变化： - -- 删除顶层对象（如 `legend`、`tooltip` 等）时，会自动写入 `null`，让 ECharts 清空旧配置。 -- 移除数组（如 `series`、`dataset` 等）时，会写入空数组并通过 `replaceMerge` 清除旧数据。 -- 如果检测到风险较高的变更（`options`/`media` 缩小、标量被删除等），会退回到 `notMerge: true` 以保证安全。 -- 如果提供了 `update-options`（或注入了默认值），会直接使用该配置并跳过智能计划。 - -默认情况下响应式更新都会使用这套逻辑。手动调用 `setOption`（仅当 `manual-update` 为 `true` 时可用）与原生 ECharts 一致，仅应用你在本次调用中传入的更新参数。 - ### 事件 可以使用 Vue 的 `v-on` 指令绑定事件。 diff --git a/src/ECharts.ts b/src/ECharts.ts index 89b38d5..5154dcd 100644 --- a/src/ECharts.ts +++ b/src/ECharts.ts @@ -108,9 +108,7 @@ export default defineComponent({ override?: UpdateOptions, ): UpdateOptions { const base = realUpdateOptions.value; - const result: UpdateOptions = { - ...(override ?? {}), - }; + const result: UpdateOptions = { ...override }; const replacements = [ ...(plan?.replaceMerge ?? []),