快速开始

环境要求

  • 火山软件开发平台(火山视窗,PC 版)
  • Windows 10 / 11 + WebView2 Runtime(Win11 自带;Win10 用微软 Evergreen Bootstrapper 安装)

模块为静态库源码直连——JadeView.wsv 引用 C++ 桥接层与 JadeView.lib,编译时直接联入你的工程,产物是单个 exe,无需随程序分发 DLL

安装

  1. 下载模块安装包,安装到火山模块目录
  2. 在火山项目中引用 JadeView 模块火山.JadeView
  3. 声明 JadeView 基类变量:
Plaintext
变量 Jade <类型 = JadeView>
  1. 点击变量旁的闪电图标快速声明事件回调方法(JadeView_应用就绪JadeView_全部窗口已关闭 等,方法名与参数签名自动匹配)

编译目标为 win32 / x64 时,模块内静态库自动按平台选择,产物为单个 exe。

最小示例

Plaintext
<火山程序 类型 = "通常" 版本 = 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)
    }
}

应用生命周期

  1. 订阅特殊事件 — 可拦截事件(请求新窗口窗口即将关闭即将导航下载开始)与 文件拖放 不会自动订阅,需在 初始化 前调用 订阅事件(...)
  2. 初始化 — 调用 Jade.初始化(...),失败直接返回结束
  3. 创建窗口 — 在 JadeView_应用就绪 接收事件中调用 创建窗口(...)
  4. 消息循环 — 调用 Jade.运行消息循环() 进入阻塞消息循环
  5. 退出 — 在 JadeView_全部窗口已关闭 中调用 Jade.退出程序()

加载本地 HTML

使用协议服务把本地目录映射为可访问的 URL,比 file:// 更安全、与库同源(IPC 无跨域问题):

Plaintext
方法 JadeView_应用就绪 <接收事件 类型 = 整数>
参数 来源对象 <类型 = JadeView>
参数 标记值 <类型 = 整数>
参数 窗口ID <类型 = 整数>
参数 数据 <类型 = 文本型>
{
    如果 (来源对象 == Jade)
    {
        // 热载模式=真:改动站点文件页面即时刷新(开发期好用)
        变量 本地资源地址 <类型 = 文本型>
        本地资源地址 = Jade.置协议服务目录 (取运行目录 () + "web", 真)

        Jade.创建窗口 (本地资源地址, 0, , )
    }
    返回 (0)
}

前端目录用包属性 @视窗.附属文件 随编译自动复制到输出目录:

Plaintext
包 火山.样例 <@视窗.附属文件 = "web > web">

IPC:前端 ⇄ 火山

前端 jade.invoke(通道, payload) 发请求,火山用对象方法回调统一应答;火山用 发送IPC消息 主动推送,前端 jade.on(事件名, ...) 接收。

Plaintext
// 初始化成功后设置一次回调,再注册通道
Jade.置IPC频道回调 (本对象, "ipcChannelMessageCallback")
Jade.注册IPC通道 ("greet")
Jade.注册IPC通道 ("set-theme")
Plaintext
方法 IPC频道消息 <公开 类型 = 文本型 @强制输出 = 真 @输出名 = "ipcChannelMessageCallback">
参数 通道名 <类型 = 文本型>
参数 窗口ID <类型 = 整数>
参数 数据 <类型 = 文本型>
{
    如果 (通道名 == "greet")
    {
        // 用内置 json_object 解析 payload
        变量 数据解构 <类型 = json_object>
        数据解构.创建自文本 (数据)
        返回 ("你好, " + 数据解构.取文本 ("name", "访客"))
    }
    如果 (通道名 == "set-theme")
    {
        Jade.窗口.置主题 (窗口ID, 数据)
        返回 ("ok")
    }
    返回 ("")   // 空文本 = 不回传
}

前端侧:

JavaScript
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.创建窗口 / 创建无边框窗口 / 置协议服务目录
WebViewJade.导航到地址 / 执行脚本 / 置缩放比例 / 取URL
事件与 IPCJade.订阅事件 / 置IPC频道回调 / 注册IPC通道 / 发送IPC消息
对话框 / 通知Jade.打开文件对话框 / 消息框 / 显示通知(含 _异步 版)
全局热键Jade.注册全局热键 / 注销全局热键
窗口操作Jade.窗口.置标题 / 置大小 / 置材质 / 置窗口层级 / 置任务栏进度
系统工具Jade.系统.剪贴板 / 路径 / 显示器 / 打印 / 自启 / NTP / 文件图标 …
YAML 存储Jade.YAML. / / 列出键 / 删除
系统托盘Jade.托盘.创建 / 置图标 / 添加菜单项
右键菜单Jade.菜单.创建 / 置显示 / 销毁
JAPK 应用包Jade.应用包.设置公钥 / 加载字节集 / 是否加载
JSONjson_object / json_array / json_value解析与构造 JSON
常量类窗口主题 / 窗口边框样式 / 订阅_视图事件 / 热键功能键

完整签名见 API 参考,可拷贝的完整片段见示例代码