Skip to content

Commit 3563c51

Browse files
committed
docs: update readme
1 parent 995d1fd commit 3563c51

File tree

3 files changed

+16
-28
lines changed

3 files changed

+16
-28
lines changed

README.md

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -151,11 +151,17 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/demo).
151151

152152
- `option: object`
153153

154-
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)
154+
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)
155+
156+
#### Smart Update
157+
158+
- If you supply `update-options` (via prop or injection), Vue ECharts forwards it directly to `setOption` and skips the planner.
159+
- Manual `setOption` calls (only available when `manual-update` is `true`) behave like native ECharts, honouring only the per-call override you pass in.
160+
- 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`.
155161

156162
- `update-options: object`
157163

158-
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)
164+
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)
159165

160166
Injection key: `UPDATE_OPTIONS_KEY`.
161167

@@ -181,17 +187,6 @@ See more examples [here](https://github.com/ecomfe/vue-echarts/tree/main/demo).
181187

182188
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`).
183189

184-
#### Smart updates
185-
186-
Vue ECharts analyses each change to `option` before invoking `setOption`:
187-
188-
- Removed config objects (`legend`, `tooltip`, etc.) are replaced with `null` automatically so ECharts clears them.
189-
- Removed arrays (`series`, `dataset`, …) are converted to empty arrays and marked via `replaceMerge` so old data disappears.
190-
- If the diff looks risky (shrinking `options`/`media`, dropping scalar values), the component falls back to `notMerge: true` to rebuild the chart safely.
191-
- Supplying `update-options` (or providing it via inject) bypasses the planner and uses your configuration as-is.
192-
193-
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.
194-
195190
### Events
196191

197192
You can bind events with Vue's `v-on` directive.

README.zh-Hans.md

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -153,9 +153,15 @@ app.component('v-chart', VueECharts)
153153

154154
ECharts 的万能接口。修改这个 prop 会触发 ECharts 实例的 `setOption` 方法。查看[详情 →](https://echarts.apache.org/zh/option.html)
155155

156+
#### 智能更新
157+
158+
- 如果提供了 `update-options`(或通过 inject 注入),Vue ECharts 会直接把它传给 `setOption`,不会执行智能计划。
159+
- 手动调用 `setOption`(仅当 `manual-update``true` 时可用)与原生 ECharts 保持一致,只使用本次调用传入的参数。
160+
- 其他情况下,Vue ECharts 会分析差异:删除的对象写入 `null`,删除的数组写入 `[]` 并加入 `replaceMerge`,ID/匿名项减少时追加 `replaceMerge`,风险较高的变更会退回 `notMerge: true`
161+
156162
- `update-options: object`
157163

158-
图表更新的配置项。一旦提供(或通过 inject 注入),Vue ECharts 会直接把它传给 `setOption`,并跳过[智能更新](#智能更新)。请参考 `echartsInstance.setOption``opts` 参数。[前往 →](https://echarts.apache.org/zh/api.html#echartsInstance.setOption)
164+
图表更新的配置项。一旦提供(或通过 inject 注入),Vue ECharts 会直接把它传给 `setOption` 并跳过智能更新。请参考 `echartsInstance.setOption``opts` 参数。[前往 →](https://echarts.apache.org/zh/api.html#echartsInstance.setOption)
159165

160166
Inject 键名:`UPDATE_OPTIONS_KEY`
161167

@@ -181,17 +187,6 @@ app.component('v-chart', VueECharts)
181187

182188
在性能敏感(数据量很大)的场景下,我们最好对于 `option` prop 绕过 Vue 的响应式系统。当将 `manual-update` 指定为 `true` 且不传入 `option` prop 时,数据将不会被监听。此时需要用 `ref` 获取组件实例并手动调用 `setOption` 来更新图表(当 `manual-update``false` 时,手动调用 `setOption` 会被忽略)。
183189

184-
### 智能更新
185-
186-
Vue ECharts 在调用 `setOption` 之前会分析每次 `option` 变化:
187-
188-
- 删除顶层对象(如 `legend``tooltip` 等)时,会自动写入 `null`,让 ECharts 清空旧配置。
189-
- 移除数组(如 `series``dataset` 等)时,会写入空数组并通过 `replaceMerge` 清除旧数据。
190-
- 如果检测到风险较高的变更(`options`/`media` 缩小、标量被删除等),会退回到 `notMerge: true` 以保证安全。
191-
- 如果提供了 `update-options`(或注入了默认值),会直接使用该配置并跳过智能计划。
192-
193-
默认情况下响应式更新都会使用这套逻辑。手动调用 `setOption`(仅当 `manual-update``true` 时可用)与原生 ECharts 一致,仅应用你在本次调用中传入的更新参数。
194-
195190
### 事件
196191

197192
可以使用 Vue 的 `v-on` 指令绑定事件。

src/ECharts.ts

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -108,9 +108,7 @@ export default defineComponent({
108108
override?: UpdateOptions,
109109
): UpdateOptions {
110110
const base = realUpdateOptions.value;
111-
const result: UpdateOptions = {
112-
...(override ?? {}),
113-
};
111+
const result: UpdateOptions = { ...override };
114112

115113
const replacements = [
116114
...(plan?.replaceMerge ?? []),

0 commit comments

Comments
 (0)