@zaofan/dsh-qqbot 1.11.4 → 1.11.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/USER-GUIDE.md +17 -0
- package/docs/extension-contract.md +22 -0
- package/package.json +1 -1
package/docs/USER-GUIDE.md
CHANGED
|
@@ -832,6 +832,23 @@ if (finallyDone) {
|
|
|
832
832
|
|
|
833
833
|
### 自定义界面卡片: 给面板/悬浮球加自己的窗口 (v1.11.0+)
|
|
834
834
|
|
|
835
|
+
> ⚠️ **别和「扩展设置页」搞混** —— 那是两套不同的东西：
|
|
836
|
+
> - **扩展设置页**（`qqbotSettingsPage`）：扩展在 `.mjs` 里声明 `schema`，面板自动渲染出
|
|
837
|
+
> 开关/输入框表单，入口是扩展卡片上的 **⚙ 设置** 按钮。适合"填几个配置项"。
|
|
838
|
+
> - **界面卡片**（本节）：独立的 `ui/<id>/card.html`，你写任意 HTML，入口是
|
|
839
|
+
> **设置页顶栏 / 悬浮球面板的页签**。适合"画一个真正的界面"。
|
|
840
|
+
>
|
|
841
|
+
> 两者可以并存：一个扩展既能用 schema 让用户填 API Key，也能给一张卡片展示运行状态。
|
|
842
|
+
|
|
843
|
+
**两张图一眼分清**（看各自框住的那块，不是整页）：
|
|
844
|
+
|
|
845
|
+
| ① `ui/` 界面卡片 | ② `qqbotSettingsPage` 设置表单 |
|
|
846
|
+
|---|---|
|
|
847
|
+
|  |  |
|
|
848
|
+
| **右边那个悬浮球面板** —— 顶栏多出一个「🔌 扩展示例」页签，<br>里面是扩展自己写的 HTML（五个子标签、输入框、按钮全自己画）。<br>入口：**设置页顶栏 / 悬浮球面板的页签** | 点扩展包上的 **⚙ 设置** 弹出的这个 ——<br>面板按 `schema` **自动渲染**出下拉 / 输入框 / 复选框，<br>长什么样不是扩展决定的。入口：**扩展卡片上的 ⚙ 按钮** |
|
|
849
|
+
|
|
850
|
+
|
|
851
|
+
|
|
835
852
|
不想只加命令和工具、还想**加个界面**？放三个文件进去，设置页顶栏或悬浮球里就多一个页签。
|
|
836
853
|
|
|
837
854
|
```
|
|
@@ -46,6 +46,28 @@
|
|
|
46
46
|
|
|
47
47
|
### 第六套：`ui/` —— 自定义界面卡片（2026-10-26 新增）
|
|
48
48
|
|
|
49
|
+
> ⚠️ **先分清两件事，别混**：
|
|
50
|
+
>
|
|
51
|
+
> | | `qqbotSettingsPage`（老，§2 末尾那个 schema） | `ui/` 卡片（本节的） |
|
|
52
|
+
> |---|---|---|
|
|
53
|
+
> | 写在哪 | 扩展 `.mjs` 里 `export const qqbotSettingsPage = { schema }` | 独立目录 `ui/<id>/card.html` |
|
|
54
|
+
> | 长什么样 | 面板按 schema **自动渲染表单**（开关/输入框/下拉） | 你写的**任意 HTML** |
|
|
55
|
+
> | 入口在哪 | 扩展卡片上的 **⚙ 设置** 按钮 → 弹窗 | **设置页顶栏** 或 **悬浮球面板**的页签 |
|
|
56
|
+
> | 数据怎么存 | 面板帮你存成 JSON，扩展里 `ctx.config` 读 | 自己管（`getConfig` / `store` / 自己写文件） |
|
|
57
|
+
> | 适合什么 | 几个配置项，越快越好 | 复杂界面（列表、按钮、图表、实时数据） |
|
|
58
|
+
>
|
|
59
|
+
> 简言之：**设置表单是"填空"，UI 卡片是"画图"**。两者可以同时存在 ——
|
|
60
|
+
> 一个扩展既能声明 schema 让用户填 API Key，也能给一张卡片展示运行状态。
|
|
61
|
+
|
|
62
|
+
**两张图一眼分清**（看各自框住的那块，不是整页）：
|
|
63
|
+
|
|
64
|
+
| ① `ui/` 界面卡片 | ② `qqbotSettingsPage` 设置表单 |
|
|
65
|
+
|---|---|
|
|
66
|
+
|  |  |
|
|
67
|
+
| **右边那个悬浮球面板** —— 顶栏多出一个「🔌 扩展示例」页签，<br>里面是扩展自己写的 HTML（五个子标签、输入框、按钮全自己画）。<br>入口：**设置页顶栏 / 悬浮球面板的页签** | 点扩展包上的 **⚙ 设置** 弹出的这个 ——<br>面板按 `schema` **自动渲染**出下拉 / 输入框 / 复选框，<br>长什么样不是扩展决定的。入口：**扩展卡片上的 ⚙ 按钮** |
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
|
|
49
71
|
前五套是「代码模块」，`ui/` 是**静态资源**（html/css/js），由面板加载到 **Shadow DOM** 里跑。
|
|
50
72
|
它不参与 `import()`，所以放错位置只会被静默跳过，不会报错。
|
|
51
73
|
|