web.view 快速入门指南

1. 简介

web.view 是 aardio 中用于创建基于 WebView2 (Edge/Chromium 内核) 的浏览器控件的库。WebView2 接口简洁、性能强悍、稳定可靠。

更重要的是 WebView2 是 Win10、Win11 等主流桌面操作系统的自带组件，可生成体积较小的独立 EXE 程序。

2. 创建 web.view 控件

首先，我们需要导入必要的库并创建一个窗体:

import win.ui;
import web.view;

// 创建主窗口
var winform = win.form(text="web.view 示例");

// 创建 web.view 控件
var wb = web.view(winform);

winform.show();
win.loopMessage();

要点: - 使用 import web.view 导入 web.view 库 - 使用 web.view(winform) 创建 web.view 控件，参数为宿主窗口（可指定主窗体或窗口上的 custom 控件）。

3. 加载网页内容

web.view 控件提供了多种方式加载网页内容:

// 加载 URL
wb.go("https://example.com");

// 加载 HTML 字符串
wb.html = "<html><body><h1>Hello World</h1></body></html>";

// 加载本地 HTML 文件
wb.go("/web/index.html");

如果 wb.go 的第一个参数指定了应用程序根目录下的相对路径（以单个斜杠或反斜杠开始），并且该路径位于发布后会嵌入 EXE 文件的内嵌资源目录，则我们必须事先引入 aardio 提供的嵌入式 HTTP 服务端，例如：

import wsock.tcp.simpleHttpServer 引入多线程 HTTP 服务端
import wsock.tcp.asynHttpServer 引入单线程异步 HTTP 服务端

aardio 将会将资源路径自动转换为通过嵌入 HTTP 服务端访问的网址，如果 wb.go 指定的是 index.html 的路径，则 index.html 的父目录自动被设置为文档根目录（ documentBase，在网页中通过 / 表示该目录），并且自动支持 SPA 应用。

4. 在 aardio 中如何调用 JavaScript 。

首先在网页中添加下面的 JavaScript 全局函数：

<script> 
//定义全局函数
window.add = function(a,b){
    return a+ b;  
} 
</script>

在 aardio 中就可以如下调用上面的 JS 函数：

//调用 JS 函数
var result = wb.xcall("add",12,3);

//显示返回值
winform.msgbox(result);

wb.xcall 使用 JSON 在 aardio 与 JS 之间转换函数的调用参数与返回值。第一个参数可指定可获取 JS 函数的 JS 表达式。

wb.xcall 会阻塞等待 JS 函数的返回值，如果不需要返回值可改用异步调用的 wb.invoke 调用 JS 函数。wb.xcall 与 wb.invoke 除了是否等待 JS 返回值的区别，其他用法完全一样。

通过 wb.eval 函数可以直接执行 JS 表达式并获取返回值。wb.eval 使用 JSON 将 JS 返回值转换为 aardio 对象。注意 wb.eval 也是阻塞调用函数。

我们也可以通过 wb.doScript 函数执行 JS 代码，并可选指定一个异步非阻塞的回调函数以获取 JS 返回值，示例：

wb.doScript("window.location.href",function(result){
    winform.msgbox(result,"result 为 JS 返回的值")
})

注意：所有阻塞调用 JS 的函数都不会卡界面，等待的同时会继续处理窗口消息。

5. 使用 wb.external 导出 aardio 对象或函数到 JavaScript 。

web.view 可以通过 external 导出网页可以直接访问的 aardio 对象，示例:

// 导出 aardio 对象到 JavaScript
wb.external = {
    sayHello = function(name){
        winform.msgbox("Hello, " + name);
    }
}

// 网页中调用 aardio 函数
wb.html = /**
<!doctype html>
<html>
<body>
    <button onclick="aardio.sayHello('World')">Click Me</button>
</body>
</html>
**/

要点:

只有在打开网页或设置网页 HTML 前通过 wb.external导出的 aardio 对象才能在网页中生效。
在 JavaScript 中通过全局 aardio 对象访问导出的 wb.external 对象。wb.external 导出的所以对象以及通过调用 aardio 函数返回的对象在 JavaScript 中都是 Promise 对象。
在 JavaScript 回调 aardio 函数时不应在被回调的 aardio 函数内再通过阻塞调用的 wb.eval 、 wb.xcall 回调 JavaScript 函数，应改用非阻塞的 wb.invoke 、wb.doScript 调用 JS 函数。或者通过 winform.setTimeout 异步调用 wb.eval, wb.xcall。

6. 使用 wb.export 导出 JavaScript 全局对象。

在 aardio 中可以用 wb.export 导出 aardio 对象为 JavaScript 全局对象。

示例：

wb.export({
    alert = function(msg){
        winform.msgbox(msg) 

        //要避免重入，例如：不能在 alert 回调中再次调用 alert 函数
        //wb.invoke("alet('test')");
    };
    nativeAdd = function(a,b){ 
        return a + b; 
    }
})

上面的参数是一个表，表中每个元素在等号前面的键名为导出到 JavaScript 的全局变量名称，等号后面的值为导出到 JavaScript 的全局对象。

wb.export 导出的函数使用 JSON 协议在 aardio 与 JavaScript 之间自动转换参数和返回值，JS 函数通常无需特别处理就默认支持 JSON 兼容的参数。

注意：

只有在打开网页或设置网页 HTML 前通过 wb.export导出的 aardio 对象才能在网页中生效。
在 JavaScript 回调 aardio 函数时不应在被回调的 aardio 函数内再通过阻塞调用的 wb.eval 、 wb.xcall 回调 JavaScript 函数，应改用非阻塞的 wb.invoke 、wb.doScript 调用 JS 函数。或者通过 winform.setTimeout 异步调用 wb.eval, wb.xcall。

7. 网页调试

在网页上右键选择"检查"或按 F12 键可以打开开发者工具 (DevTools)，在控制台可以查看 JS 输出的信息与错误信息。

8. 完整示例

//创建 winform 窗口
import win.ui; 
var winform = win.form(text="窗口标题")

//创建 WebView2 浏览器控件
import web.view;
var wb = web.view(winform);

// 导出 aardio 函数
wb.external = {
    add: function(a, b) {
        return a + b;
    }   
} 

// 指定网页 HTML 代码
wb.html = /******
<!DOCTYPE html>
<html><head>
<meta charset="utf-8">
</head><body> 
<div id="result"></div>

<script> 
(async ()=>{

    //调用 aardio 导出的 wb.external.add 函数。
    var num = await aardio.add(1, 2)

    //显示结果
    document.getElementById('result').innerText = num;
})()
</script>
******/;

//显示窗口
winform.show();

//启动界面消息循环
win.loopMessage();

Markdown 格式