@binblink/wasmnest-plugin-sdk-mobile 0.0.0-stage → 0.0.2
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/README.md +439 -2
- package/README_en.md +415 -0
- package/bin/build.js +271 -0
- package/bin/cli.js +96 -0
- package/bin/lib.js +349 -0
- package/bin/manifest-gen.js +327 -0
- package/bin/package.js +151 -0
- package/bin/scaffold.js +299 -0
- package/dev-shell/README.md +151 -0
- package/dev-shell/index.html +27 -0
- package/dev-shell/package.json +27 -0
- package/dev-shell/pnpm-workspace.yaml +9 -0
- package/dev-shell/postcss.config.js +6 -0
- package/dev-shell/src/App.vue +90 -0
- package/dev-shell/src/apps/mock-terminal/MockTerminalSlotCard.vue +43 -0
- package/dev-shell/src/apps/mock-terminal/MockTerminalView.vue +168 -0
- package/dev-shell/src/apps/mock-terminal/index.ts +50 -0
- package/dev-shell/src/components/DevToolbar.vue +100 -0
- package/dev-shell/src/components/DialogHost.vue +119 -0
- package/dev-shell/src/components/LogPanel.vue +80 -0
- package/dev-shell/src/i18n.ts +22 -0
- package/dev-shell/src/loader.ts +239 -0
- package/dev-shell/src/locale.ts +29 -0
- package/dev-shell/src/locales/en-shell.ts +332 -0
- package/dev-shell/src/locales/index.ts +70 -0
- package/dev-shell/src/locales/shell.ts +331 -0
- package/dev-shell/src/main.ts +58 -0
- package/dev-shell/src/mock/dialog-service.ts +58 -0
- package/dev-shell/src/mock/file-transfer.ts +390 -0
- package/dev-shell/src/mock/mobile-api.ts +369 -0
- package/dev-shell/src/mock/preset-tasks.ts +186 -0
- package/dev-shell/src/mock/session.ts +121 -0
- package/dev-shell/src/mock-context.ts +374 -0
- package/dev-shell/src/registry.ts +151 -0
- package/dev-shell/src/shared-runtime.ts +44 -0
- package/dev-shell/src/shell/ShellView.vue +52 -0
- package/dev-shell/src/shell/adapters/devAppSource.ts +144 -0
- package/dev-shell/src/shell/components/PluginContextHost.vue +40 -0
- package/dev-shell/src/shell/components/ShellAppCell.vue +75 -0
- package/dev-shell/src/shell/components/ShellAppIcon.vue +111 -0
- package/dev-shell/src/shell/components/ShellAppSurface.vue +46 -0
- package/dev-shell/src/shell/components/ShellBrandTile.vue +27 -0
- package/dev-shell/src/shell/components/ShellCapsuleMenu.vue +123 -0
- package/dev-shell/src/shell/components/ShellChip.vue +49 -0
- package/dev-shell/src/shell/components/ShellGroupCard.vue +17 -0
- package/dev-shell/src/shell/components/ShellHost.vue +75 -0
- package/dev-shell/src/shell/components/ShellNotificationShade.vue +501 -0
- package/dev-shell/src/shell/components/ShellPermissionPrompt.vue +127 -0
- package/dev-shell/src/shell/components/ShellPlaceholderSurface.vue +33 -0
- package/dev-shell/src/shell/components/ShellSection.vue +27 -0
- package/dev-shell/src/shell/components/ShellSheet.vue +74 -0
- package/dev-shell/src/shell/components/ShellStatusbar.vue +84 -0
- package/dev-shell/src/shell/components/screens/PluginRoutePage.vue +98 -0
- package/dev-shell/src/shell/components/screens/ShellAppDetailScreen.vue +359 -0
- package/dev-shell/src/shell/components/screens/ShellAppRunScreen.vue +90 -0
- package/dev-shell/src/shell/components/screens/ShellAppsScreen.vue +195 -0
- package/dev-shell/src/shell/components/screens/ShellHomeScreen.vue +357 -0
- package/dev-shell/src/shell/components/screens/ShellPermissionsScreen.vue +376 -0
- package/dev-shell/src/shell/components/screens/ShellSettingsScreen.vue +240 -0
- package/dev-shell/src/shell/components/screens/ShellSwitcherScreen.vue +559 -0
- package/dev-shell/src/shell/components/ui/ConfirmDialog.vue +137 -0
- package/dev-shell/src/shell/components/ui/Toggle.vue +53 -0
- package/dev-shell/src/shell/composables/useShellApps.ts +417 -0
- package/dev-shell/src/shell/composables/useShellNavigation.ts +197 -0
- package/dev-shell/src/shell/composables/useShellNotifications.ts +115 -0
- package/dev-shell/src/shell/composables/useShellOpen.ts +44 -0
- package/dev-shell/src/shell/composables/useShellOverlays.ts +101 -0
- package/dev-shell/src/shell/composables/useShellPreferences.ts +143 -0
- package/dev-shell/src/shell/composables/useShellRecent.ts +84 -0
- package/dev-shell/src/shell/composables/useSlotCarousel.ts +238 -0
- package/dev-shell/src/shell/composables/useToast.ts +33 -0
- package/dev-shell/src/shell/index.ts +88 -0
- package/dev-shell/src/shell/logger.ts +45 -0
- package/dev-shell/src/shell/permissions.ts +145 -0
- package/dev-shell/src/shell/registry.ts +220 -0
- package/dev-shell/src/shell/slotCards.ts +47 -0
- package/dev-shell/src/shell/styles/shell.css +1155 -0
- package/dev-shell/src/shell/surfaceIntent.ts +107 -0
- package/dev-shell/src/shell/types.ts +152 -0
- package/dev-shell/src/shell/utils.ts +54 -0
- package/dev-shell/src/styles/main.css +153 -0
- package/dev-shell/src/styles/mobile.css +981 -0
- package/dev-shell/src/styles/wallpaper.css +130 -0
- package/dev-shell/src/theme.ts +71 -0
- package/dev-shell/src/vite-env.d.ts +20 -0
- package/dev-shell/tailwind.config.js +101 -0
- package/dev-shell/tsconfig.json +16 -0
- package/dev-shell/vite.config.ts +130 -0
- package/dist/index.d.ts +124 -0
- package/dist/index.js +229 -0
- package/dist/types.d.ts +738 -0
- package/dist/types.js +0 -0
- package/dist/vite-plugin.d.ts +16 -0
- package/dist/vite-plugin.js +95 -0
- package/package.json +88 -3
- package/src/constants.ts +6 -0
- package/src/global-dialog.ts +168 -0
- package/src/index.ts +96 -0
- package/src/runtime.ts +44 -0
- package/src/types.ts +822 -0
- package/src/ui/AppUpdateSection.d.ts +44 -0
- package/src/ui/AppUpdateSection.vue +253 -0
- package/src/ui/PluginGlobalDialog.vue +388 -0
- package/src/ui/QuickCard.d.ts +33 -0
- package/src/ui/QuickCard.vue +167 -0
- package/src/ui/Select.d.ts +37 -0
- package/src/ui/Select.vue +307 -0
- package/src/ui/plugin-global-dialog.d.ts +11 -0
- package/src/ui/useSwipeTabs.d.ts +20 -0
- package/src/ui/useSwipeTabs.ts +53 -0
- package/src/update.ts +123 -0
- package/src/vite-plugin.ts +132 -0
- package/template/.gitignore +4 -0
- package/template/README.md +46 -0
- package/template/package.json +23 -0
- package/template/plugin.json +13 -0
- package/template/rust/Cargo.toml +19 -0
- package/template/rust/src/lib.rs +33 -0
- package/template/src/env.d.ts +24 -0
- package/template/src/index.ts +37 -0
- package/template/tsconfig.json +17 -0
- package/template/vite.config.ts +21 -0
package/README.md
CHANGED
|
@@ -1,3 +1,440 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @binblink/wasmnest-plugin-sdk-mobile
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
WasmNest 移动端 wasm 应用开发工具包 — 提供应用所需的**类型定义**、**运行时代理**、**Vite 构建插件**与**共享 UI 组件**。相比桌面端 SDK,额外封装了移动端专属能力:SAF 存储访问、对话框 / 系统通知、动态路由、生命周期钩子与 dev-shell 演示数据协议。
|
|
4
|
+
|
|
5
|
+
> 术语:本仓把「插件」称为 wasm 应用;包名 / CLI 名 / 标识符保留 `plugin` 原词(`plugin.json`、`wasmnest-plugin-api-mobile`)。
|
|
6
|
+
>
|
|
7
|
+
> 完整开发指南见仓库文档 [`wasm-app-dev-mobile.md`](../../docs/wasm-app-dev-mobile.md);开发红线清单 [`wasm-app-development-checklist.md`](../../../docs/knowledge/wasm-app-development-checklist.md)。
|
|
8
|
+
|
|
9
|
+
[English](README_en.md) | 简体中文
|
|
10
|
+
|
|
11
|
+
## 安装
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pnpm add -D @binblink/wasmnest-plugin-sdk-mobile
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Peer 依赖(宿主已在运行时提供,插件侧安装用于构建与类型检查):
|
|
18
|
+
|
|
19
|
+
| 依赖 | 版本 |
|
|
20
|
+
|------|------|
|
|
21
|
+
| vite | ^5.0.0 |
|
|
22
|
+
| vue | ^3.4.0 |
|
|
23
|
+
|
|
24
|
+
## 快速开始(推荐:脚手架)
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# 创建 wasm 应用工程(id 与 name 为位置参数,非交互;默认带 WASM 后端,--ts-only 仅前端)
|
|
28
|
+
wasmnest-plugin create com.example.my-app "My App" --author "you"
|
|
29
|
+
|
|
30
|
+
cd my-app
|
|
31
|
+
pnpm install
|
|
32
|
+
ppnpm run dev # 浏览器开发环境(Dev Shell:空壳宿主 + 移动端骨架,HMR)
|
|
33
|
+
ppnpm run build # 构建产物 dist/
|
|
34
|
+
ppnpm run package # 打包 dist/{id}.zip 插件包
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
更多命令(直接在应用工程里跑 CLI,非 npm script):
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
wasmnest-plugin manifest [--check] # 按源码自动填充 plugin.json 的 contributes / permissions
|
|
41
|
+
wasmnest-plugin validate [--dir] # 校验 plugin.json 合法性
|
|
42
|
+
wasmnest-plugin doctor # 环境自检
|
|
43
|
+
wasmnest-plugin build --watch # 监听重建
|
|
44
|
+
wasmnest-plugin dev --host # 监听局域网,手机浏览器访问 http://<电脑IP>:5173
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
> [!NOTE]
|
|
48
|
+
> `ppnpm run dev` 首次运行自动安装 dev-shell 依赖,浏览器打开 http://localhost:5173;WASM 后端与 SAF / 系统返回键等真机专属能力仍需真机验证。
|
|
49
|
+
|
|
50
|
+
**安装到手机**:将 `dist/{id}.zip` 传到手机 → WasmNest Mobile → 插件管理 → 从文件安装(支持远程下载 + SHA256 校验)。
|
|
51
|
+
|
|
52
|
+
## 手动创建插件
|
|
53
|
+
|
|
54
|
+
一个最小插件只需两个文件:
|
|
55
|
+
|
|
56
|
+
**`plugin.json`** — 插件清单(id / 权限 / 扩展点声明):
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"id": "com.example.my-plugin",
|
|
61
|
+
"name": "My Plugin",
|
|
62
|
+
"version": "0.1.0",
|
|
63
|
+
"platform": "mobile",
|
|
64
|
+
"description": "示例插件",
|
|
65
|
+
"author": "you",
|
|
66
|
+
"icon": "🧩",
|
|
67
|
+
"main": "index.js",
|
|
68
|
+
"pluginType": "frontend",
|
|
69
|
+
"permissions": ["storage", "ui:input"],
|
|
70
|
+
"contributes": {
|
|
71
|
+
"commands": [{ "id": "my-plugin.hello", "title": "Hello" }],
|
|
72
|
+
"terminal": {
|
|
73
|
+
"toolbarItems": [{ "id": "my-plugin.toolbar", "title": "My Plugin", "icon": "🧩" }]
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**`src/index.ts`** — 插件入口(必须导出 `activate`):
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
import type { PluginContext } from '@binblink/wasmnest-plugin-sdk-mobile'
|
|
83
|
+
|
|
84
|
+
export async function activate(context: PluginContext): Promise<void> {
|
|
85
|
+
// 注册终端工具栏按钮
|
|
86
|
+
context.ui.registerTerminalToolbarItem({
|
|
87
|
+
id: 'my-plugin.toolbar',
|
|
88
|
+
label: 'My Plugin',
|
|
89
|
+
icon: '🧩',
|
|
90
|
+
onClick: () => {
|
|
91
|
+
context.dialogs.showToast('Hello WasmNest!', 'success')
|
|
92
|
+
},
|
|
93
|
+
})
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export async function deactivate(): Promise<void> {
|
|
97
|
+
// 清理资源(context 注册的所有 Disposable 宿主会自动回收)
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## PluginContext API
|
|
102
|
+
|
|
103
|
+
`activate(context)` 接收的 `PluginContext` 是插件访问宿主能力的**唯一通道**,各 API 按权限分组:
|
|
104
|
+
|
|
105
|
+
| API | 说明 | 所需权限 |
|
|
106
|
+
|-----|------|----------|
|
|
107
|
+
| `context.commands` | 注册 / 执行命令(`register` / `execute`)——含本应用的自持业务命令(如 `file-transfer.list-remote`) | 默认授予 |
|
|
108
|
+
| `context.session` | 会话列表、单会话查询、状态变更订阅 | `session:read` / `session:write` |
|
|
109
|
+
| `context.ui` | 宿主壳运行面 / 首页卡片 / 胶囊菜单 / 平台设置入口 / 动态路由(`registerSurface` / `registerSlot` / `registerCapsuleItem` / `registerSettingsEntry` / `registerRoute`)、跳转与返回(`openPage` / `goBack`)、系统返回键接管(`onBackPressed`)、入口意图(`onSurfaceIntent`)、全局弹窗(`showDialog`) | `ui:route` / `ui:back` / `ui:dialog` / `ui:settings` |
|
|
110
|
+
| `context.events` | 宿主事件订阅与发布(`on` / `emit`) | 默认授予 |
|
|
111
|
+
| `context.storage` | 键值存储(`get` / `set` / `delete`) | `storage`(**移动端恒授予**,见下方说明) |
|
|
112
|
+
| `context.lifecycle` | 应用生命周期钩子(`onAppStartup` / `onAppShutdown` / `onAuthSuccess` / `onDisconnect` / `onSessionCreated` / `onSessionStopped`) | 默认授予 |
|
|
113
|
+
| `context.dialogs` | 对话框(`showDialog` / `showConfirm` / `showPrompt` / `showToast`) | 默认授予 |
|
|
114
|
+
| `context.notifications` | 系统通知(`notify(title, body?)`) | 默认授予 |
|
|
115
|
+
| `context.status` | 生命周期状态上报(`reportReady` / `reportError`) | 默认授予 |
|
|
116
|
+
| `context.logger` | 分级日志(`info` / `debug` / `warn` / `error`) | 默认授予 |
|
|
117
|
+
| `context.i18n` | 注册应用翻译、`t()` 快捷翻译 | 默认授予 |
|
|
118
|
+
| `context.appUpdate` | 应用更新检查(宿主统一 GitHub Release 判定;失败归一化为 `status: 'error'`) | 默认授予 |
|
|
119
|
+
| `context.system` | 系统级操作(`openFile` / `revealInDir` / `revealReceivedFileLocation` / `requestAllFilesAccess` / `openDownloadDir`) | `system:open` |
|
|
120
|
+
| `context._disposables` | 宿主在注销时统一回收的 Disposable 列表(内部使用) | — |
|
|
121
|
+
|
|
122
|
+
> 注:移动端**无** `context.terminal` / `context.fileService` / `context.http`(那三个仅桌面端有)。
|
|
123
|
+
> 移动端终端输出经宿主壳运行面订阅(业务应用自持协议),文件访问经 `system` 域 API
|
|
124
|
+
> (受 `system:open` 与 SAF 授权约束),跨设备传输经 `context.commands` 自持命令
|
|
125
|
+
> (底层对等网络原语在业务核 crate)。
|
|
126
|
+
|
|
127
|
+
> 权限**按风险域按需声明**,除 `storage` 外无默认位:写入 manifest `permissions` 后由宿主按生效权限授予,未声明即该能力被拒。
|
|
128
|
+
> 例外是 `storage`——移动端把它设为**恒授予**(插件自身配置空间的读写,关掉会让应用无法工作),因此不提供开关:
|
|
129
|
+
> 宿主 `src-tauri/src/plugin/approval.rs::effective_permissions` 无条件 `insert("storage")`,
|
|
130
|
+
> 壳内 `src/shell/permissions.ts::SHELL_LOCKED_PERMISSIONS` 把它标为锁定项。
|
|
131
|
+
|
|
132
|
+
所有 `register*` / `on*` 调用返回 `Disposable`;插件注销时宿主自动回收,无需手动 `dispose()`。
|
|
133
|
+
|
|
134
|
+
## 移动端专属能力
|
|
135
|
+
|
|
136
|
+
### 动态路由
|
|
137
|
+
|
|
138
|
+
插件可注册任意深度的页面路由,宿主挂载到 `/mobile/plugins/{pluginId}/{id}`:
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
context.ui.registerRoute({
|
|
142
|
+
id: 'settings', // 可含 '/' 支持深路径
|
|
143
|
+
title: '插件设置', // 宿主页头标题(header: false 时省略)
|
|
144
|
+
component: SettingsPage, // 任意 Vue 组件
|
|
145
|
+
})
|
|
146
|
+
|
|
147
|
+
context.ui.openPage('settings') // 整体跳转
|
|
148
|
+
context.ui.goBack() // 返回上一页
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
> [!NOTE]
|
|
152
|
+
> `context.ui.onBackPressed()` 可接管 Android 系统返回键(仅 Android 真机触发;只在该应用运行面位于前台时回调,切走后不消费返回);iOS / dev-shell 静默降级为永不触发。
|
|
153
|
+
|
|
154
|
+
### 对话框与通知
|
|
155
|
+
|
|
156
|
+
```ts
|
|
157
|
+
const ok = await context.dialogs.showConfirm({ title: '确认', message: '确定删除?', variant: 'danger' })
|
|
158
|
+
const name = await context.dialogs.showPrompt({ title: '命名', inputPlaceholder: '输入名称' })
|
|
159
|
+
context.dialogs.showToast('已保存', 'success')
|
|
160
|
+
|
|
161
|
+
await context.notifications.notify('任务完成', '会话 #3 已结束')
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### 生命周期钩子
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
context.lifecycle.onAppStartup(() => { /* 应用启动(仅前台启动时触发) */ })
|
|
168
|
+
context.lifecycle.onAuthSuccess(() => { /* 配对成功后刷新对端数据 */ })
|
|
169
|
+
context.lifecycle.onDisconnect((reason) => { /* 与桌面端断开 */ })
|
|
170
|
+
context.lifecycle.onSessionCreated((sessionId) => { /* 新会话建立 */ })
|
|
171
|
+
context.lifecycle.onSessionStopped((sessionId) => { /* 会话结束 */ })
|
|
172
|
+
context.lifecycle.onAppShutdown(() => { /* 应用退出前清理 */ })
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
> `onTerminalInput` / `onTerminalOutput` 已随票 15 阶段 B 退役——终端输入输出不再经
|
|
176
|
+
> 生命周期钩子,改由业务应用自持订阅通道(宿主壳运行面)。
|
|
177
|
+
|
|
178
|
+
### 对端桌面端 HTTP 能力(MobileHostApi)
|
|
179
|
+
|
|
180
|
+
经 `getMobileApi()` 获取响应式连接状态与对端 REST 客户端(任务队列、会话自动模式、
|
|
181
|
+
任务历史、定时任务等均在业务应用自持的 HTTP 路径中调):
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
import { getMobileApi } from '@binblink/wasmnest-plugin-sdk-mobile'
|
|
185
|
+
|
|
186
|
+
const api = getMobileApi()
|
|
187
|
+
console.log(api.isConnected.value, api.activeSessionId.value, api.isPaired.value)
|
|
188
|
+
|
|
189
|
+
// 通用 REST 客户端(路径与载荷形状由业务应用自持)
|
|
190
|
+
const res = await api.httpRequest<{ tasks: unknown[]; queue_count: number }>(
|
|
191
|
+
`/task-queue/${api.activeSessionId}`, { method: 'GET' },
|
|
192
|
+
)
|
|
193
|
+
|
|
194
|
+
await api.loadActiveSessions() // 刷新活动会话
|
|
195
|
+
api.onSessionEvent((evt) => { /* 会话事件推送 */ })
|
|
196
|
+
const settings = await api.readAllSettings() // 读全部设置(扁平键值表)
|
|
197
|
+
await api.writeSetting('my-key', 'my-value') // 写单个设置键
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### 文件与系统访问
|
|
201
|
+
|
|
202
|
+
移动端**无** `context.fileService`。文件相关能力分两路:
|
|
203
|
+
|
|
204
|
+
- **`context.system`**(`system:open` 权限):`openFile(path, displayName?)` 用系统查看器打开、
|
|
205
|
+
`revealInDir(path)` / `revealReceivedFileLocation(fileName)` 在文件管理器中定位、
|
|
206
|
+
`openDownloadDir()` 打开公共下载目录、`requestAllFilesAccess()` 引导授予
|
|
207
|
+
MANAGE_EXTERNAL_STORAGE(未授权时访问公共下载目录会收到以 `needs_all_files_access` 开头的 reject,
|
|
208
|
+
应捕获后弹引导弹窗而非静默失败)。
|
|
209
|
+
- **跨设备文件传输**:经 `context.commands` 调业务应用自持命令(如 `file-transfer.list-remote`),
|
|
210
|
+
底层对等网络 / 断点续传在业务核 crate(`应用仓 apps/file-transfer/rust/core`),
|
|
211
|
+
不暴露为共享 SDK API。
|
|
212
|
+
|
|
213
|
+
### dev-shell 演示数据(devMock)
|
|
214
|
+
|
|
215
|
+
插件入口可导出 `devMock` 字段,为浏览器开发环境提供业务演示数据(任务队列种子、SAF 目录树等);真实宿主忽略该字段,无需条件编译:
|
|
216
|
+
|
|
217
|
+
```ts
|
|
218
|
+
export const devMock: PluginDevMock = {
|
|
219
|
+
queueSeed: [{ id: '1', prompt: '示例任务', position: 0, status: 'pending', created_at: '' }],
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
> `PluginDevMock` 的类型是 `Record<string, unknown>`——键名由应用与 dev-shell 约定,
|
|
224
|
+
> 无编译期校验。
|
|
225
|
+
|
|
226
|
+
## 共享模块(避免重复打包 vue 等)
|
|
227
|
+
|
|
228
|
+
插件构建时 `vue` / `vue-i18n` / `pinia` 会被外部化,运行时从宿主全局 `window.__WASMNEST_SHARED__` 读取。**请通过 SDK 代理函数访问,不要直接操作全局变量**:
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
import { getVue, getPinia, getRouter, getPresetTasks, getMobileApi, getPluginContext } from '@binblink/wasmnest-plugin-sdk-mobile'
|
|
232
|
+
|
|
233
|
+
const { ref, computed } = getVue() // 宿主 Vue 实例(组件内直接 import 即可,构建期已外部化)
|
|
234
|
+
const presetTasks = getPresetTasks() // 宿主预设任务 composable
|
|
235
|
+
const context = getPluginContext() // 组件 setup 内从 inject 获取 PluginContext
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
### 应用运行期与 store(Pinia)
|
|
239
|
+
|
|
240
|
+
宿主按「一次运行期」隔离插件 store:**启动(activate)到停止(deactivate,含多任务上滑 / × /
|
|
241
|
+
详情「停用」/ 卸载)之间的 store 属于该次运行期,停止即整体作废**——再次启动是全新 store
|
|
242
|
+
(回到 setup 初始 state),不会读到上一次运行期残留。
|
|
243
|
+
|
|
244
|
+
由此有两条契约:
|
|
245
|
+
|
|
246
|
+
1. **store 定义写在模块顶层**(`const useX = defineStore(...)`)。宿主在装载模块时记录归属,
|
|
247
|
+
模块被 ESM 缓存、只求值一次也不影响下次运行期拿到新作用域;写在异步 chunk 里会回退宿主
|
|
248
|
+
Pinia 并打 warn(不保证随应用停止作废)。
|
|
249
|
+
2. **模块级可变单例状态必须在 `deactivate` 里清空**(或挂到 `context` 的 disposable)。宿主
|
|
250
|
+
不会重新求值插件模块,跨 activate 保留的模块级状态属插件缺陷;需要跨运行期保留的数据
|
|
251
|
+
请走 storage / plugin-database。
|
|
252
|
+
|
|
253
|
+
## Vite 构建集成
|
|
254
|
+
|
|
255
|
+
在插件 `vite.config.ts` 中引入 `wasmnestPlugin()`,负责将共享模块标记为 external 并改写为全局变量读取:
|
|
256
|
+
|
|
257
|
+
```ts
|
|
258
|
+
import { defineConfig } from 'vite'
|
|
259
|
+
import vue from '@vitejs/plugin-vue'
|
|
260
|
+
import { wasmnestPlugin } from '@binblink/wasmnest-plugin-sdk-mobile/vite'
|
|
261
|
+
|
|
262
|
+
export default defineConfig({
|
|
263
|
+
plugins: [vue(), wasmnestPlugin()],
|
|
264
|
+
build: {
|
|
265
|
+
lib: {
|
|
266
|
+
entry: 'src/index.ts',
|
|
267
|
+
formats: ['es'],
|
|
268
|
+
fileName: () => 'index.js',
|
|
269
|
+
},
|
|
270
|
+
outDir: 'dist',
|
|
271
|
+
},
|
|
272
|
+
})
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
产物文件名必须为 `index.js`(与 `plugin.json` 的 `main` 对应)。
|
|
276
|
+
|
|
277
|
+
## Rust WASM 后端(`--rust` 插件)
|
|
278
|
+
|
|
279
|
+
`--rust` 脚手架附带 Rust 侧 SDK crate **`wasmnest-plugin-api-mobile`**(本包 `rust/` 目录,MIT),用于编写编译为 WASM 组件、在宿主 wasmtime 沙箱内运行的后端逻辑。
|
|
280
|
+
|
|
281
|
+
### 启用
|
|
282
|
+
|
|
283
|
+
```toml
|
|
284
|
+
[dependencies]
|
|
285
|
+
wasmnest-plugin-api-mobile = { path = "<宿主>/packages/plugin-sdk-mobile/rust", features = ["wasm"] }
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
`wasm` feature 提供:
|
|
289
|
+
|
|
290
|
+
- `WasmPlugin` trait + `wasm_entry!` 宏 — 生成 WIT 契约(`rust/wit/wasmnest.wit`,单一事实来源)定义的全部组件导出
|
|
291
|
+
- `WasmHost` — 宿主 API 绑定(import 后端),经 bindgen 调用宿主能力
|
|
292
|
+
|
|
293
|
+
### 最小示例
|
|
294
|
+
|
|
295
|
+
```rust
|
|
296
|
+
use wasmnest_plugin_api_mobile::{CommandArgs, WasmHost, WasmPlugin};
|
|
297
|
+
|
|
298
|
+
struct MyPlugin;
|
|
299
|
+
|
|
300
|
+
impl WasmPlugin for MyPlugin {
|
|
301
|
+
fn activate() -> anyhow::Result<()> {
|
|
302
|
+
// 经 WasmHost 访问宿主能力(事件订阅、存储、文件服务等)
|
|
303
|
+
Ok(())
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
wasmnest_plugin_api_mobile::wasm_entry!(MyPlugin);
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
### 构建
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
cargo build --target wasm32-unknown-unknown --no-default-features --features wasm --release
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
产物为 WASM 组件(Component Model),宿主以 wasmtime 沙箱加载运行;插件崩溃不影响宿主。SAF / 系统返回键等真机专属能力需在 Android 真机验证。
|
|
317
|
+
|
|
318
|
+
## 共享 UI 组件
|
|
319
|
+
|
|
320
|
+
`./ui` 子路径导出的组件遵循宿主设计 token,插件 UI 与宿主观感一致(**禁止使用原生 `<select>` 等系统控件外观**):
|
|
321
|
+
|
|
322
|
+
```vue
|
|
323
|
+
<script setup lang="ts">
|
|
324
|
+
import { ref } from 'vue'
|
|
325
|
+
import Select from '@binblink/wasmnest-plugin-sdk-mobile/ui'
|
|
326
|
+
|
|
327
|
+
const value = ref('a')
|
|
328
|
+
const options = [
|
|
329
|
+
{ value: 'a', label: '选项 A' },
|
|
330
|
+
{ value: 'b', label: '选项 B' },
|
|
331
|
+
]
|
|
332
|
+
</script>
|
|
333
|
+
|
|
334
|
+
<template>
|
|
335
|
+
<Select v-model="value" :options="options" size="sm" />
|
|
336
|
+
</template>
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
### 应用更新检查(AppUpdateSection)
|
|
340
|
+
|
|
341
|
+
manifest 声明 `update`(缺省 = 不参与检查)后,应用设置页直接嵌入 SDK 默认卡片:
|
|
342
|
+
|
|
343
|
+
```vue
|
|
344
|
+
<script setup lang="ts">
|
|
345
|
+
import AppUpdateSection from '@binblink/wasmnest-plugin-sdk-mobile/ui/app-update'
|
|
346
|
+
</script>
|
|
347
|
+
|
|
348
|
+
<template>
|
|
349
|
+
<AppUpdateSection />
|
|
350
|
+
</template>
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
- 数据面 = `context.appUpdate.check`(宿主注入;令牌只能查自己);应用可给 `check` 传自实现,或只用 `useAppUpdate()` 自己画 UI。
|
|
354
|
+
- 更新安装统一在宿主应用管理页执行(需先停用、替换目录并重新审批)。
|
|
355
|
+
|
|
356
|
+
### 首页快捷卡片(QuickCard)
|
|
357
|
+
|
|
358
|
+
宿主壳首页的快捷卡片 = **SDK 公共外观 + 应用内容 + 宿主跳转**:应用只实现卡片内容,
|
|
359
|
+
activate 期用 `context.ui.registerSlot` 注册;宿主壳负责展示、自动轮播(最多 5 张)与
|
|
360
|
+
点击打开本应用,应用不需要也不应该在卡片里处理导航。
|
|
361
|
+
|
|
362
|
+
卡片可以**直达应用内某个位置**(如「活跃会话」卡点进最近一个会话):`registerSlot`
|
|
363
|
+
的可选 `onPress()` 在点击时刻现算一个入口意图(`{ key, payload }`,内容全归应用),
|
|
364
|
+
宿主启动并打开应用后原样投递给运行面——运行面在 `onMounted` 里用
|
|
365
|
+
`context.ui.onSurfaceIntent(handler)` 订阅即可。订阅前到达的意图由宿主排队补投,
|
|
366
|
+
运行面晚于点击创建也不会丢;应用停用 / 卸载后队列清空。
|
|
367
|
+
|
|
368
|
+
```vue
|
|
369
|
+
<script setup lang="ts">
|
|
370
|
+
import QuickCard from '@binblink/wasmnest-plugin-sdk-mobile/ui/quick-card'
|
|
371
|
+
|
|
372
|
+
defineProps<{ activeCount: number }>()
|
|
373
|
+
</script>
|
|
374
|
+
|
|
375
|
+
<template>
|
|
376
|
+
<QuickCard
|
|
377
|
+
label="活跃会话"
|
|
378
|
+
:value="activeCount"
|
|
379
|
+
hint="正在运行"
|
|
380
|
+
tone="success"
|
|
381
|
+
:icon-path="['M4 5h16v14H4z', 'M8 10l3 2.5-3 2.5']"
|
|
382
|
+
/>
|
|
383
|
+
</template>
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
```ts
|
|
387
|
+
context.ui.registerSlot({
|
|
388
|
+
id: 'sessions',
|
|
389
|
+
component: SessionCard,
|
|
390
|
+
order: 10,
|
|
391
|
+
// 点击直达应用内位置;省略 = 只打开应用(旧行为)
|
|
392
|
+
onPress: () => ({ key: 'open-session', payload: { sessionId: latestLiveSessionId() } }),
|
|
393
|
+
})
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
```ts
|
|
397
|
+
// 运行面(应用根组件):宿主投递入口意图
|
|
398
|
+
const sub = context.ui.onSurfaceIntent((intent) => {
|
|
399
|
+
if (intent.key !== 'open-session') return
|
|
400
|
+
openSession((intent.payload as { sessionId: string }).sessionId)
|
|
401
|
+
})
|
|
402
|
+
// 卸载时 sub.dispose()
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
- 宿主把整张卡渲染成按钮(点击 = 启动并打开贡献方应用,再投递 `onPress()` 的返回值),
|
|
406
|
+
卡片内不得再放按钮 / 链接;
|
|
407
|
+
- 宿主按注册顺序截断展示(当前 5 张),多张时自动轮播——触摸 / 键盘聚焦 / 切后台 /
|
|
408
|
+
系统「减少动效」时停走,标题行提供暂停 / 播放控件;
|
|
409
|
+
- `label` / `value` / `hint` / `tone` / `iconPath` 覆盖常见读数卡,复杂内容用默认插槽。
|
|
410
|
+
|
|
411
|
+
当前提供(每个子路径 = 一个独立导出):
|
|
412
|
+
|
|
413
|
+
| 子路径 | 内容 | 用途 |
|
|
414
|
+
|--------|------|------|
|
|
415
|
+
| `./ui` | `Select` 组件 | 下拉选择(`update:modelValue` / `open` 事件,`md` / `sm` 尺寸) |
|
|
416
|
+
| `./ui/quick-card` | `QuickCard` 组件 | 宿主壳首页快捷卡片公共外观(宿主 token / 明暗 / 字号自适应;点击归宿主) |
|
|
417
|
+
| `./ui/plugin-global-dialog` | `PluginGlobalDialog` 组件 | 移动端宿主全局弹窗(应用根挂载一次;渲染由全局弹窗控制器驱动,与桌面端同构) |
|
|
418
|
+
| `./ui/swipe-tabs` | `useSwipeTabs` composable | 弹窗/页签内容区横向滑动切换(内容区水平主导滑动超阈值触发 `onSwitch`;垂直主导不记录位移;`shouldSkip` 排除输入控件等不应作切页手势的起点) |
|
|
419
|
+
| `./global-dialog` | 全局弹窗控制器 | 发布-订阅式弹窗队列(FIFO,同时至多一个;`update()` 生成新条目对象再广播),宿主与 dev-shell 共用 |
|
|
420
|
+
|
|
421
|
+
## 子路径导出总览
|
|
422
|
+
|
|
423
|
+
| 子路径 | 内容 |
|
|
424
|
+
|--------|------|
|
|
425
|
+
| `@binblink/wasmnest-plugin-sdk-mobile` | 主 API:类型 + 运行时代理 |
|
|
426
|
+
| `@binblink/wasmnest-plugin-sdk-mobile/vite` | `wasmnestPlugin()` Vite 构建插件 |
|
|
427
|
+
| `@binblink/wasmnest-plugin-sdk-mobile/types` | 纯类型导出(仅类型,无运行时) |
|
|
428
|
+
| `@binblink/wasmnest-plugin-sdk-mobile/ui` | 共享 Vue 组件:`Select` |
|
|
429
|
+
| `@binblink/wasmnest-plugin-sdk-mobile/ui/quick-card` | `QuickCard` 首页快捷卡片 |
|
|
430
|
+
| `@binblink/wasmnest-plugin-sdk-mobile/ui/app-update` | `AppUpdateSection`(应用更新检查) |
|
|
431
|
+
| `@binblink/wasmnest-plugin-sdk-mobile/ui/plugin-global-dialog` | `PluginGlobalDialog` |
|
|
432
|
+
| `@binblink/wasmnest-plugin-sdk-mobile/ui/swipe-tabs` | `useSwipeTabs` |
|
|
433
|
+
| `@binblink/wasmnest-plugin-sdk-mobile/global-dialog` | 全局弹窗控制器 |
|
|
434
|
+
|
|
435
|
+
## 本地开发本 SDK
|
|
436
|
+
|
|
437
|
+
```bash
|
|
438
|
+
pnpm run build # tsup 构建 dist(ESM + d.ts)
|
|
439
|
+
pnpm run test:run # vitest run
|
|
440
|
+
```
|