This is an automated email from the ASF dual-hosted git repository.
sushuang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
The following commit(s) were added to refs/heads/master by this push:
new 43ce6920 fix: fix the setTheme doc to add a caveat.
43ce6920 is described below
commit 43ce692053bff74ef6545742dc557133255cc6f6
Author: 100pah <[email protected]>
AuthorDate: Sun Sep 28 17:06:29 2025 +0800
fix: fix the setTheme doc to add a caveat.
---
en/api/echarts-instance.md | 46 +++++++++++++++++++++++++++++++++++++-------
zh/api/echarts-instance.md | 48 +++++++++++++++++++++++++++++++++++++++-------
2 files changed, 80 insertions(+), 14 deletions(-)
diff --git a/en/api/echarts-instance.md b/en/api/echarts-instance.md
index 7c9f34d5..c9ac20b9 100644
--- a/en/api/echarts-instance.md
+++ b/en/api/echarts-instance.md
@@ -258,17 +258,49 @@ Sets the theme for the chart instance.
Here is a demo of dynamically setting a theme after initialization:
+Method 1: Register and apply a named theme; the theme can be used in multiple
charts.
```js
-const chart = echarts.init(...);
-chart.setOption(...);
-// Method 1: Register and apply a named theme
echarts.registerTheme('myTheme', { backgroundColor: 'red' });
-chart.setTheme('myTheme');
-// Method 2: Apply an anonymous theme directly
-chart.setTheme({ backgroundColor: 'red' });
+const chart1 = echarts.init(mainDOMElement1);
+chart1.setTheme('myTheme');
+chart1.setOption(...);
+const chart2 = echarts.init(mainDOMElement2);
+chart2.setTheme('myTheme');
+chart2.setOption(...);
+```
+
+Method 2: Apply an anonymous theme directly, which only serves the current
chart.
+```js
+const chart1 = echarts.init(mainDOMElement);
+chart1.setTheme({ backgroundColor: 'red' });
+chart1.setOption(...);
+```
+
+**[CAVEAT]:**
+
+In the current implementation, calling `setOption` multiple times in merge
mode is not supported when using `setTheme`. That is,
+```js
+// --- Bad (May be unexpected) ---
+const chart1 = echarts.init(mainDOMElement);
+chart1.setOption(option1);
+chart1.setOption(option2); // call `setOption` in "merge mode"
+chart1.setOption(option3);
+chart1.setTheme('dark');
+// After calling `setTheme`, the previous options (option1 and option2) are
discarded.
+// Only the last option (option3) is retained.
+
+// --- Solution ---
+const chart1 = echarts.init(mainDOMElement);
+// Make sure every option contains all the information and using `notMerge
mode` in `setOption`.
+chart1.setOption(option1, {notMerge: true});
+chart1.setOption(option2, {notMerge: true});
+chart1.setOption(option3, {notMerge: true});
+chart1.setTheme('dark');
+// The previous options (option1 and option2) are also discarded.
+// But the last option (option3) contains all the information and is retained,
+// so the finall effect is correct.
```
-If there are no other charts using this theme, the above two methods are the
same. If not, you should use the former one, so that `setTheme('myTheme')` can
be used in other charts.
## resize(Function)
```ts
diff --git a/zh/api/echarts-instance.md b/zh/api/echarts-instance.md
index 00674ce9..af640b24 100644
--- a/zh/api/echarts-instance.md
+++ b/zh/api/echarts-instance.md
@@ -256,17 +256,51 @@ myChart.setOption({
以下是一个动态设置主题的例子：
+方式 1：注册一个具名主题，可以被多个 chart 实例使用。
```js
-const chart = echarts.init(...);
-chart.setOption(...);
-// 图表已经初始化了，也可以调用 registerTheme 和 setTheme
echarts.registerTheme('myTheme', { backgroundColor: 'red' });
-chart.setTheme('myTheme');
-// 或者直接
-chart.setTheme({ backgroundColor: 'red' });
+const chart1 = echarts.init(mainDOMElement1);
+chart1.setTheme('myTheme');
+chart1.setOption(...);
+const chart2 = echarts.init(mainDOMElement2);
+chart2.setTheme('myTheme');
+chart2.setOption(...);
```
-如果这个主题不在其他图表中使用，那么这两种方式是等价的，否则应使用前一种，这样在其他图表中也可以使用 `setTheme('myTheme')` 使用该主题。
+方式 2：注册一个匿名主题，只被当前 chart 实例使用。
+```js
+const chart1 = echarts.init(mainDOMElement);
+chart1.setTheme({ backgroundColor: 'red' });
+chart1.setOption(...);
+```
+
+注意：当前的实现中，如果在 `chart.setOption` 后调用
+
+**[注意]：**
+
+当前的实现中，并不支持使用 "merge 模式" 调用 `chart.setOption` 后调用 `setTheme`。即，
+```js
+// --- 可能不符合预期 ---
+const chart1 = echarts.init(mainDOMElement);
+chart1.setOption(option1);
+chart1.setOption(option2); // 使用 “merge 模式” 调用 `setOption`
+chart1.setOption(option3);
+chart1.setTheme('dark');
+// 调用 `setTheme` 后，之前的 options （option1 and option2）被丢弃了，
+// 只有最后的 option （option3）被留了下来。
+
+// --- 解决方案 ---
+const chart1 = echarts.init(mainDOMElement);
+// 保证每个 option 都含有全量信息，然后使用 “notMerge 模式” 调用 `setOption`
+chart1.setOption(option1, {notMerge: true});
+chart1.setOption(option2, {notMerge: true});
+chart1.setOption(option3, {notMerge: true});
+chart1.setTheme('dark');
+// 调用 `setTheme` 后，之前的 options （option1 and option2）仍然被丢弃了，
+// 但因为最后的 option （option3）中含有全量信息且被留了下来，最终效果是正确的。
+```
+
+
## resize(Function)
```ts
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
