快速开始
环境要求
- 火山软件开发平台(火山视窗,PC 版)
- Windows 10 / 11 + WebView2 Runtime(Win11 自带;Win10 用微软 Evergreen Bootstrapper 安装)
模块为静态库源码直连——JadeView.wsv 引用 C++ 桥接层与 JadeView.lib,编译时直接联入你的工程,产物是单个 exe,无需随程序分发 DLL。
安装
- 下载模块安装包,安装到火山模块目录
- 在火山项目中引用 JadeView 模块(
火山.JadeView) - 声明 JadeView 基类变量:
变量 Jade <类型 = JadeView>- 点击变量旁的闪电图标快速声明事件回调方法(
JadeView_应用就绪、JadeView_全部窗口已关闭等,方法名与参数签名自动匹配)
编译目标为 win32 / x64 时,模块内静态库自动按平台选择,产物为单个 exe。
最小示例
<火山程序 类型 = "通常" 版本 = 1 />
包 火山.样例
类 启动类 <公开 基础类 = 程序类>
{
变量 Jade <类型 = JadeView>
方法 启动方法 <公开 类型 = 整数>
{
// 1. 可拦截 / 特殊事件需在 初始化 前手动订阅(普通事件会自动订阅)
Jade.订阅事件 (订阅_视图事件.请求新窗口)
// 2. 初始化应用
// 初始化 (调试模式, 日志路径, 数据目录, 应用名, 应用标识, 单实例)
// 应用标识建议 ≥6 字符、反域名格式——JAPK 模式下它就是 JADE:// URL 的主机名
如果 (Jade.初始化 (真, "", "", "我的第一个应用", "com.example.myapp", 真) == 假)
{
返回 (0)
}
// 3. 启动消息循环(阻塞,直到退出)
Jade.运行消息循环 ()
返回 (1)
}
方法 JadeView_应用就绪 <接收事件 类型 = 整数 注释 = "初始化完成后的第一入口,在这里创建主窗口。">
参数 来源对象 <类型 = JadeView>
参数 标记值 <类型 = 整数>
参数 窗口ID <类型 = 整数>
参数 数据 <类型 = 文本型>
{
如果 (来源对象 == Jade)
{
变量 窗口选项 <类型 = JadeWindowOptions>
变量 视图选项 <类型 = JadeViewOptions>
窗口选项.标题 = "我的第一个 JadeView 应用"
窗口选项.宽度 = 1024
窗口选项.高度 = 768
窗口选项.左边 = -1 // 左边/顶边同为 -1 表示居中
窗口选项.顶边 = -1
窗口选项.可调整大小 = 真
窗口选项.主题 = 窗口主题.跟随系统
变量 主窗口ID <类型 = 整数>
主窗口ID = Jade.创建窗口 ("https://example.com", 0, 窗口选项, 视图选项)
调试输出 ("窗口已创建:", 主窗口ID)
}
返回 (0)
}
方法 JadeView_全部窗口已关闭 <接收事件 类型 = 整数>
参数 来源对象 <类型 = JadeView>
参数 标记值 <类型 = 整数>
参数 窗口ID <类型 = 整数>
{
如果 (来源对象 == Jade)
{
Jade.退出程序 () // 所有窗口关闭后退出
}
返回 (0)
}
}应用生命周期
- 订阅特殊事件 — 可拦截事件(
请求新窗口、窗口即将关闭、即将导航、下载开始)与文件拖放不会自动订阅,需在初始化前调用订阅事件(...) - 初始化 — 调用
Jade.初始化(...),失败直接返回结束 - 创建窗口 — 在
JadeView_应用就绪接收事件中调用创建窗口(...) - 消息循环 — 调用
Jade.运行消息循环()进入阻塞消息循环 - 退出 — 在
JadeView_全部窗口已关闭中调用Jade.退出程序()
接收事件是火山的挂接方式
JadeView 的事件全部以「定义事件」暴露。在你的类里声明 变量 Jade <类型 = JadeView> 后,点击变量旁的闪电图标即可快速生成 JadeView_应用就绪 等接收事件方法——方法名、参数签名自动匹配,无需手写。回调里记得判断 来源对象 == Jade。
加载本地 HTML
使用协议服务把本地目录映射为可访问的 URL,比 file:// 更安全、与库同源(IPC 无跨域问题):
方法 JadeView_应用就绪 <接收事件 类型 = 整数>
参数 来源对象 <类型 = JadeView>
参数 标记值 <类型 = 整数>
参数 窗口ID <类型 = 整数>
参数 数据 <类型 = 文本型>
{
如果 (来源对象 == Jade)
{
// 热载模式=真:改动站点文件页面即时刷新(开发期好用)
变量 本地资源地址 <类型 = 文本型>
本地资源地址 = Jade.置协议服务目录 (取运行目录 () + "web", 真)
Jade.创建窗口 (本地资源地址, 0, , )
}
返回 (0)
}前端目录用包属性 @视窗.附属文件 随编译自动复制到输出目录:
包 火山.样例 <@视窗.附属文件 = "web > web">WARNING
协议服务的站点目录不要与 初始化 的数据目录相同或嵌套——库持续写数据会触发「写 → 热载刷新」死循环。
IPC:前端 ⇄ 火山
前端 jade.invoke(通道, payload) 发请求,火山用对象方法回调统一应答;火山用 发送IPC消息 主动推送,前端 jade.on(事件名, ...) 接收。
// 初始化成功后设置一次回调,再注册通道
Jade.置IPC频道回调 (本对象, "ipcChannelMessageCallback")
Jade.注册IPC通道 ("greet")
Jade.注册IPC通道 ("set-theme")方法 IPC频道消息 <公开 类型 = 文本型 @强制输出 = 真 @输出名 = "ipcChannelMessageCallback">
参数 通道名 <类型 = 文本型>
参数 窗口ID <类型 = 整数>
参数 数据 <类型 = 文本型>
{
如果 (通道名 == "greet")
{
// 用内置 json_object 解析 payload
变量 数据解构 <类型 = json_object>
数据解构.创建自文本 (数据)
返回 ("你好, " + 数据解构.取文本 ("name", "访客"))
}
如果 (通道名 == "set-theme")
{
Jade.窗口.置主题 (窗口ID, 数据)
返回 ("ok")
}
返回 ("") // 空文本 = 不回传
}前端侧:
const reply = await jade.invoke('greet', { name: '火山' }); // "你好, 火山"
jade.on('push-demo', payload => console.log('宿主推送:', payload));构建与分发
- 火山 IDE 中直接编译(win32 / x64 均可),静态链接产出单个 exe
- 前端资源两种走法:
@视窗.附属文件 = "web > web"把目录随编译复制,运行时置协议服务目录加载- 打成 JAPK 加密包,经
Jade.应用包.加载字节集从内存加载(磁盘零前端文件),见高级用法
- GUI 程序看不到
调试输出?给初始化传日志路径落盘日志
功能分区总览
SDK 以 JadeView 为入口,细分能力挂在成员对象上:
| 分区 | 入口 | 主要方法 |
|---|---|---|
| 生命周期 | Jade. | 初始化 / 运行消息循环 / 退出程序 / 取版本 |
| 窗口创建 | Jade. | 创建窗口 / 创建无边框窗口 / 置协议服务目录 |
| WebView | Jade. | 导航到地址 / 执行脚本 / 置缩放比例 / 取URL |
| 事件与 IPC | Jade. | 订阅事件 / 置IPC频道回调 / 注册IPC通道 / 发送IPC消息 |
| 对话框 / 通知 | Jade. | 打开文件对话框 / 消息框 / 显示通知(含 _异步 版) |
| 全局热键 | Jade. | 注册全局热键 / 注销全局热键 |
| 窗口操作 | Jade.窗口. | 置标题 / 置大小 / 置材质 / 置窗口层级 / 置任务栏进度 … |
| 系统工具 | Jade.系统. | 剪贴板 / 路径 / 显示器 / 打印 / 自启 / NTP / 文件图标 … |
| YAML 存储 | Jade.YAML. | 写 / 读 / 列出键 / 删除 … |
| 系统托盘 | Jade.托盘. | 创建 / 置图标 / 添加菜单项 … |
| 右键菜单 | Jade.菜单. | 创建 / 置显示 / 销毁 |
| JAPK 应用包 | Jade.应用包. | 设置公钥 / 加载字节集 / 是否加载 |
| JSON | json_object / json_array / json_value | 解析与构造 JSON |
| 常量类 | — | 窗口主题 / 窗口边框样式 / 订阅_视图事件 / 热键功能键 … |