mirror of
https://github.com/ecomfe/vue-echarts.git
synced 2025-10-27 19:13:59 +08:00
docs: update readme
This commit is contained in:
21
README.md
21
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.
|
||||
|
||||
@ -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` 指令绑定事件。
|
||||
|
||||
@ -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 ?? []),
|
||||
|
||||
Reference in New Issue
Block a user