From 945fd1cd3f0f840e8d0c0f3f73531bc8c9f12e92 Mon Sep 17 00:00:00 2001
From: kyuiazusa <kyuiazusa@gmail.com>
Date: Tue, 4 Aug 2026 01:23:07 +0800
Subject: [PATCH] docs: add applyStyle tutorial

---
 src/.vuepress/sidebar/zh.ts      |  1 +
 src/webgal-script/apply-style.md | 66 ++++++++++++++++++++++++++++++++
 src/webgal-script/custom-ui.md   |  2 +-
 3 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 src/webgal-script/apply-style.md

diff --git a/src/.vuepress/sidebar/zh.ts b/src/.vuepress/sidebar/zh.ts
index 84525f50..e618a251 100644
--- a/src/.vuepress/sidebar/zh.ts
+++ b/src/.vuepress/sidebar/zh.ts
@@ -39,6 +39,7 @@ export const zhSidebar = sidebar({
         "variable",
         "animation",
         "special-effect",
+        "apply-style",
         "custom-ui",
       ]
     },
diff --git a/src/webgal-script/apply-style.md b/src/webgal-script/apply-style.md
new file mode 100644
index 00000000..f0e0e506
--- /dev/null
+++ b/src/webgal-script/apply-style.md
@@ -0,0 +1,66 @@
+# 使用 applyStyle 动态切换界面样式
+
+`applyStyle` 可以在游戏运行时，把模板中的一个 CSS 类替换为另一个类。它适合制作角色专属文本框、危险选项、高亮按钮和临时主题等效果。
+
+## 准备样式类
+
+先打开游戏目录中的模板样式文件。例如，要改变选项样式，可以编辑：
+
+``` text
+game/template/UI/Choose/choose.scss
+```
+
+保留模板原有的 `.Choose_item`，再添加一个包含完整样式的变体：
+
+``` scss
+.Choose_item_danger {
+  color: #ffffff;
+  background: #b42318;
+  border: 2px solid #f97066;
+}
+```
+
+::: warning
+新类应包含替换后需要的完整样式。`applyStyle` 会替换类名，不会自动继承原类的规则。
+:::
+
+## 在脚本中切换
+
+类名之间使用 `->`：左边始终是模板原始类名，右边是要应用的变体类名。
+
+``` webgal
+角色A:接下来是危险选项。;
+applyStyle:Choose_item->Choose_item_danger;
+choose:继续:continue|离开:leave;
+```
+
+要恢复原样式，把原始类名同时写在两侧：
+
+``` webgal
+applyStyle:Choose_item->Choose_item;
+```
+
+## 同时替换多个类
+
+多个替换之间使用英文逗号分隔：
+
+``` webgal
+applyStyle:TextBox_main->TextBox_main_dark,TextBox_ShowName_Background->TextBox_ShowName_Background_red;
+```
+
+恢复时仍以原始类名为左侧：
+
+``` webgal
+applyStyle:TextBox_main->TextBox_main,TextBox_ShowName_Background->TextBox_ShowName_Background;
+```
+
+不要把当前变体写在左侧。下面第二句不能正确切换：
+
+``` webgal
+applyStyle:Choose_item->Choose_item_danger;
+applyStyle:Choose_item_danger->Choose_item_blue; // 错误
+```
+
+## 查找可替换类名
+
+常用类名可以在 [applyStyle 命令参考](../script-reference/commands/applyStyle.md)中查询。其他组件的类名以当前游戏模板的 SCSS 文件为准；自定义模板可能使用不同的类名。
diff --git a/src/webgal-script/custom-ui.md b/src/webgal-script/custom-ui.md
index 50477128..bd75b9fb 100644
--- a/src/webgal-script/custom-ui.md
+++ b/src/webgal-script/custom-ui.md
@@ -230,7 +230,7 @@ WebGAL 称这套方案为「模板」。您可以在 `您的游戏名称目录/g
 
 ## 动态切换 {#dynamic-switching}
 
-WebGAL 允许用户在游戏运行时动态切换不同的模板样式。请参考[applyStyle](../webgal-script/api.md#applystyle)命令的文档。
+WebGAL 允许用户在游戏运行时动态切换不同的模板样式。请参考 [applyStyle 教程](./apply-style.md)。
 
 ``` scss
 .outer {