docs(ConfigProvider): update the guide of modify CSS vars (#12246)

* docs(ConfigProvider): update the guide of modify CSS vars

* docs: update

packages/vant/src/config-provider/README.md

@@ -161,7 +161,17 @@ export default {
 };
 ```
 
-> Tips: ConfigProvider by default only affects its child components. set to `global` for the entire page to take effect.
+#### Scope of CSS Variables
+
+By default, the CSS variables generated by `themeVars` are applied to the root node of the component, thereby only affecting the styles of its child components and not the entire page.
+
+You can modify the scope of CSS variables using the `theme-vars-scope` prop. For example, by setting `theme-vars-scope` to `global`, the CSS variables generated by `themeVars` will be applied to the root node of the HTML and affect all components within the entire page.
+
+```html
+<van-config-provider :theme-vars="themeVars" theme-vars-scope="global">
+  ...
+</van-config-provider>
+```
 
 #### Use In TypeScript
 
@@ -214,20 +224,64 @@ export default {
 };
 ```
 
+#### Using Class Names
+
+In addition, you can also use the class selectors `.van-theme-light` and `.van-theme-dark` to individually modify the base variables and component variables in the light or dark mode.
+
+```css
+.van-theme-light {
+  --van-white: white;
+}
+
+.van-theme-dark {
+  --van-white: black;
+}
+```
+
 ## Variables
 
-### Basic Variables
+### Variable Types
 
-CSS variables in Vant are divided into **basic variables** and **component variables**. Component variables will inherit the basic variables. After modifying the basic variables, all related components will be affected.
+In Vant, CSS variables are divided into **basic variables** and **component variables**. Component variables inherit from basic variables, so modifying a basic variable will affect all related components.
 
-#### Modify Basic Variables
+#### Modifying Variables
 
-- The basic variables can only be modified through the `:root` selector.
-- The component variables can be modified through the `:root` selector and `ConfigProvider` component.
+CSS variables have an inheritance relationship, where component variables inherit from the nearest parent basic variable.
 
-You can also use the `.van-theme-light` and `.van-theme-dark` class selector to modify basic or component variables in light or dark mode individually.
+Therefore, there are certain limitations when modifying basic variables. You need to use the `:root` selector or the global mode of the ConfigProvider component to modify basic variables. Otherwise, component variables may not inherit basic variables correctly.
 
-#### Variables List
+Taking the `--van-primary-color` basic variable as an example:
+
+- You can modify it using the `:root` selector:
+
+```css
+:root {
+  --van-primary-color: red;
+}
+```
+
+- You can modify it using the global mode of the ConfigProvider component:
+
+```html
+<van-config-provider
+  :theme-vars="{ primaryColor: 'red' }"
+  theme-vars-scope="global"
+>
+  ...
+</van-config-provider>
+```
+
+- You cannot modify it using the default `local` mode of the ConfigProvider component:
+
+```html
+<van-config-provider :theme-vars="{ primaryColor: 'red' }">
+  ...
+</van-config-provider>
+```
+
+As for component variables, there are no such limitations, and you can modify them in any way you want.
+
+### Basic Variables List
 
 There are all **Basic Variables** below, for component CSS Variables, please refer to the documentation of each component.
 

packages/vant/src/config-provider/README.zh-CN.md

@@ -159,7 +159,17 @@ export default {
 };
 ```
 
-> 注意：ConfigProvider 默认仅影响它的子组件的样式，不影响全局 root 节点。设置为 `global` 整个页面生效。
+#### CSS 变量生效范围
+
+默认情况下，themeVars 产生的 CSS 变量是设置在组件根节点上的，因此只会影响它的子组件的样式，不会影响整个页面。
+
+你可以通过 `theme-vars-scope` 属性来修改 CSS 变量的生效范围。比如将 `theme-vars-scope` 设置为 `global`，此时 themeVars 产生的 CSS 变量会设置到 HTML 的根节点，并对整个页面内的所有组件生效。
+
+```html
+<van-config-provider :theme-vars="themeVars" theme-vars-scope="global">
+  ...
+</van-config-provider>
+```
 
 #### 在 TypeScript 中使用
 
@@ -212,22 +222,64 @@ export default {
 };
 ```
 
+#### 使用类名
+
+此外，你也可以使用 `.van-theme-light` 和 `.van-theme-dark` 这两个类名选择器来单独修改浅色或深色模式下的基础变量和组件变量。
+
+```css
+.van-theme-light {
+  --van-white: white;
+}
+
+.van-theme-dark {
+  --van-white: black;
+}
+```
+
 ## 主题变量
 
-### 基础变量
+### 变量类型
 
 Vant 中的 CSS 变量分为 **基础变量** 和 **组件变量**。组件变量会继承基础变量，因此在修改基础变量后，会影响所有相关的组件。
 
 #### 修改变量
 
-由于 CSS 变量继承机制的原因，两者的修改方式有一定差异：
+CSS 变量存在继承关系，组件变量会寻找最近的父级基础变量进行继承。
 
-- 基础变量只能通过 `:root 选择器` 修改，不能通过 `ConfigProvider 组件` 修改。
-- 组件变量可以通过 `:root 选择器` 和 `ConfigProvider 组件` 修改。
+因此修改基础变量存在一定限制，你需要使用 `:root` 选择器或 ConfigProvider 组件的 global 模式来修改基础变量。否则，组件变量可能会无法正确继承基础变量。
 
-你也可以使用 `.van-theme-light` 和 `.van-theme-dark` 这两个类名选择器来单独修改浅色或深色模式下的基础变量和组件变量。
+以 `--van-primary-color` 这个基础变量为例：
 
-#### 变量列表
+- 可以通过 `:root` 选择器修改：
+
+```css
+:root {
+  --van-primary-color: red;
+}
+```
+
+- 可以通过 ConfigProvider 组件的 global 模式修改：
+
+```html
+<van-config-provider
+  :theme-vars="{ primaryColor: 'red' }"
+  theme-vars-scope="global"
+>
+  ...
+</van-config-provider>
+```
+
+- 不可以通过 ConfigProvider 组件默认的 `local` 模式修改：
+
+```html
+<van-config-provider :theme-vars="{ primaryColor: 'red' }">
+  ...
+</van-config-provider>
+```
+
+对于组件变量，则没有上述限制，可以通过任意方式修改。
+
+### 基础变量列表
 
 下面是所有的基础变量：