Update docs

Ayideyia · Ayideyia · commit 5f36e80e9f1b · 2025-05-28T23:30:36.000+08:00
diff --git a/en/guide/index.md b/en/guide/index.md
@@ -68,5 +68,3 @@ The applications based on this project are neither VPN nor proxy applications. T
 - <CheckBox /> Better installation and upgrade experience on macOS and GNU/Linux
 
 - <CheckBox checked /> Rewrite some functions for GUI.for.SingBox
-
-- <CheckBox /> GUI applications for Android™
diff --git a/zh/guide/02-uninstall.md b/zh/guide/02-uninstall.md
@@ -4,14 +4,18 @@
 
 1、请再次运行程序、取消一些设置
 
-在设置里关闭`以管理员身份运行`，关闭`开机时启动`。
+在设置里关闭`以管理员身份运行`(如果开启过)，关闭`开机时启动`(如果开启过)。
+
+> 这一步是为了删除注册表、清除计划任务。
 
 然后彻底退出程序，包括关闭 core 的运行。
 
 2、 删除目录：`%APPDATA%\[BinaryName.exe]`
 
 BinaryName 是程序的名称。
 
+> 这一步是为了删除 Webview2 运行产生的缓存文件。
+
 3、删除`data`目录（可保留）
 
 data 目录与程序同级，是程序运行时生成的，存放着 core 二进制文件、订阅文件、配置文件、规则集文件、插件文件、计划任务文件。
diff --git a/zh/guide/03-how-it-works.md b/zh/guide/03-how-it-works.md
@@ -1,6 +1,6 @@
 # 运行原理
 
-下面从程序的正常使用流程来介绍程序的运行原理。
+> GUI 维护自己的一套配置文件（保存位置 data/profiles.yaml），是对 core 配置文件的进一步包装。这样做的好处是你不必再理会 core 的 breaking change（破坏性修改），因为 GUI 会处理这一切，包括配置文件的自动升级、以及生成适用于稳定版、测试版的配置。
 
 ## 1、快速开始
 
@@ -12,15 +12,13 @@
 
 3. 拉取订阅，更新上一步的订阅信息，读取节点，保存到 `subscribes/ID_xxxxxx.yaml`文件，文件以随机 ID 命名。
 
-4. 如果拉取订阅成功，则提示初始化完成，此时可以启动内核程序，如果拉取订阅失败，则需要手动到`订阅`菜单里更新对应的订阅。
-
 ## 2、运行配置
 
 选中一个配置，点击`启动内核`按钮，GUI 会根据当前的配置生成一份 `config.yaml` 或 `config.json` 文件，然后调用内核程序运行。如果你创建了多个配置，也可以在`配置`页面，右键某个配置，在更多里选择`使用此配置启动/重启`。排列顺序靠前的会展示在`概览`页，概览页最多展示`4`个配置。
 
 ## 3、配置系统代理
 
-默认的设置下，GUI 不会主动的为你设置系统代理，当你点击主页的`系统代理`按钮时，GUI 会从配置中获取 http 代理端口、混合代理端口，并选择一个将其设置为系统代理，混合代理端口总是优先于 http 代理端口。
+GUI 的设计理念是不主动修改你系统的任何设置，除非得到你的授权。当你点击主页的`系统代理`按钮时，GUI 会从配置中获取 http 代理端口、混合代理端口，并选择一个将其设置为系统代理，混合代理端口总是优先于 http 代理端口。
 
 ## 4、TUN 模式
 
diff --git a/zh/guide/04-plugins.md b/zh/guide/04-plugins.md
@@ -20,9 +20,9 @@
 
 - `手动触发`：点击运行按钮时会被触发，GUI 会执行源码中的 `onRun` 方法。
 
-- `更新订阅时`：更新订阅时会被触发，GUI 会执行源码中的 `onSubscribe` 方法，并传递一个参数，其值是节点列表数组。此方法需要返回一个节点列表的数组。
+- `更新订阅时`：更新订阅时会被触发，GUI 会执行源码中的 `onSubscribe` 方法，并传递 2 个参数，分别是节点列表数组、订阅元数据。此方法需要返回一个节点列表的数组。
 
-- `生成配置时`：生成配置文件时会被触发，GUI 会执行源码中的 `onGenerate` 方法，并传递一个参数，其值是一个对象，里面包含了 core 的配置，此方法需要将处理后的参数返回，或原样返回。
+- `生成配置时`：生成配置文件时会被触发，GUI 会执行源码中的 `onGenerate` 方法，并传递 2 个参数，分别是 core 的配置、配置元数据，此方法需要将处理后的参数返回，或原样返回。
 
 - `启动 APP 时`：启动 APP 时会被触发，GUI 会执行源码中的 `onStartup` 方法，没有传递参数，此方法无需返回任何值。
 
@@ -216,6 +216,137 @@ const onShutdown = () => {
 
 在上面我们演示了 Plugins.message、Plugins.HttpGet，那么插件对象 Plugins 还有哪些能力呢，你可以在软件界面按下 Ctrl+Shift+F12 打开开发者面板，切换到控制台，输入 Plugins 并回车查看，具体的使用示例可以看源码。
 
+## 高级 API
+
+### 1、添加自定义 UI
+
+现在，你可以使用 `addCustomActions` 方法在 GUI 中添加自定义操作。
+
+方法签名：
+
+```ts
+interface CustomActionApi {
+  h: typeof h;
+  ref: typeof ref;
+}
+type CustomActionProps = Recordable;
+type CustomActionSlots = Recordable<
+  | ((api: CustomActionApi) => VNode | string | number | boolean)
+  | VNode
+  | string
+  | number
+  | boolean
+>;
+interface CustomAction<P = CustomActionProps, S = CustomActionSlots> {
+  id?: string;
+  component: string;
+  componentProps?: P | ((api: CustomActionApi) => P);
+  componentSlots?: S | ((api: CustomActionApi) => S);
+}
+type CustomActionFn = ((api: CustomActionApi) => CustomAction) & {
+  id?: string;
+};
+
+function addCustomActions(
+  target: string,
+  actions: CustomAction | CustomAction[] | CustomActionFn | CustomActionFn[]
+): () => void;
+```
+
+参数说明：
+
+- target: 目标位置，目前可选值为`core_state`，表示添加的概览页的`核心状态`面板中
+
+- actions: 组件列表，通过对象配置或方法返回对象配置
+
+使用示例
+
+```js
+const appStore = Plugins.useAppStore();
+
+// 添加单个组件：按钮
+appStore.addCustomActions("core_state", {
+  component: "Button",
+  componentProps: {
+    type: "link",
+    size: "small",
+  },
+  componentSlots: {
+    default: "一个按钮",
+  },
+});
+
+// 添加多个组件：开关、计数器
+appStore.addCustomActions("core_state", [
+  {
+    component: "Switch",
+    componentProps: ({ ref }) => {
+      const checked = ref(false);
+      return {
+        modelValue: checked.value,
+        onChange: (val) => {
+          checked.value = val;
+          console.log(val, checked.value);
+        },
+      };
+    },
+    componentSlots: {
+      default: "一个开关",
+    },
+  },
+  ({ h, ref }) => {
+    const count = ref(0);
+    return {
+      component: "Button",
+      componentProps: {
+        type: "link",
+        size: "small",
+        onClick: () => (count.value += 1),
+      },
+      componentSlots: {
+        default: () => "+" + count.value,
+      },
+    };
+  },
+]);
+```
+
+注：`componentProps`、`componentSlots`以及`actions`数组项可以是对象也可以是方法，方法时需返回`CustomAction`结构的对象。
+
+- 可用的 component 取值：所有 HTML 元素、[组件库](https://github.com/GUI-for-Cores/GUI.for.SingBox/tree/main/frontend/src/components)下的组件。
+
+- 可用的 componentProps 取值：所有的 HTML 属性、[组件库](https://github.com/GUI-for-Cores/GUI.for.SingBox/tree/main/frontend/src/components)中组件支持的属性(Props)
+
+- 可用的 componentSlots 取值：default、[组件库](https://github.com/GUI-for-Cores/GUI.for.SingBox/tree/main/frontend/src/components)中组件支持的插槽(Slots)
+
+- 可用的 CustomActionApi 取值：ref(Vue 中定义响应式变量的 API)、h(Vue 中定义 Vnode 的 API)
+
+### 2、移除自定义 UI
+
+方法签名：
+
+```ts
+function removeCustomActions(target: string, id: string | string[]): void;
+```
+
+使用示例
+
+```js
+const appStore = Plugins.useAppStore();
+
+const remove = appStore.addCustomActions('core_state', {
+  id: 'first-action'
+  component: 'xxx',
+  // ...
+})
+
+// 方式1：通过添加时指定的id删除
+appStore.removeCustomActions("core_state", 'first-action');
+
+// 方法2：通过添加时返回的删除方法删除
+remove()
+```
+
 ## 更多的示例
 
 ```javascript
diff --git a/zh/guide/gfc/how-to-use.md b/zh/guide/gfc/how-to-use.md
@@ -22,7 +22,7 @@
 
 ![](/zh/resources/gfc/207_how_to_use.png)
 
-默认设置下，GUI 不会改变你系统的任何设置，所以你需要手动开启`系统代理`，当然也可以在`设置`里打开`自动配置系统代理`，如果想使用 TUN 模式，则需要打开`以管理员身份运行`。TUN 模式和系统代理应该保证只有一个处于开启状态。
+默认设置下，GUI 不会改变你系统的任何设置，所以你需要手动开启`系统代理`，当然也可以在`设置`里打开`自动配置系统代理`，如果想使用 TUN 模式，则需要打开`以管理员身份运行`。
 
 ![](/zh/resources/gfc/208_how_to_use.png)
 
diff --git a/zh/guide/index.md b/zh/guide/index.md
@@ -68,5 +68,3 @@ GUI.for.Cores 项目旨在快速生成 core 的配置文件，并将其参数以
 - <CheckBox /> 优化 macOS、 GNU/Linux 下的安装升级体验
 
 - <CheckBox checked /> 重构 GUI.for.SingBox 的部分功能
-
-- <CheckBox /> 开发安卓端的 GUI 系列
