docs: update readme

This commit is contained in:
Justineo
2025-09-18 00:22:55 +08:00
committed by GU Yiling
parent 79932b65c0
commit 52938f4a03
3 changed files with 16 additions and 28 deletions

View File

@ -151,11 +151,17 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/demo).
- `option: object` - `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` - `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`. 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`). 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 ### Events
You can bind events with Vue's `v-on` directive. You can bind events with Vue's `v-on` directive.

View File

@ -153,9 +153,15 @@ app.component('v-chart', VueECharts)
ECharts 的万能接口。修改这个 prop 会触发 ECharts 实例的 `setOption` 方法。查看[详情 →](https://echarts.apache.org/zh/option.html) 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` - `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` 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` 会被忽略)。 在性能敏感(数据量很大)的场景下,我们最好对于 `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` 指令绑定事件。 可以使用 Vue 的 `v-on` 指令绑定事件。

View File

@ -108,9 +108,7 @@ export default defineComponent({
override?: UpdateOptions, override?: UpdateOptions,
): UpdateOptions { ): UpdateOptions {
const base = realUpdateOptions.value; const base = realUpdateOptions.value;
const result: UpdateOptions = { const result: UpdateOptions = { ...override };
...(override ?? {}),
};
const replacements = [ const replacements = [
...(plan?.replaceMerge ?? []), ...(plan?.replaceMerge ?? []),