NanUI

JavaScript

概述

WinFormium 使用 Chromium Embedded Framework (CEF) 作为其渲染引擎,因此,您可以使用 JavaScript 来完成各项工作,例如:前后端通信、编写自定义的交互功能等。

《窗体》《窗体 JavaScript 指南》章节中已经介绍了如何在 JavaScript 中使用 WinFormium 提供的对象,本章节将介绍更多 WinFormium 框架与 JavaScript 相关的内容。

JavaScriptValue 对象

在 WinFormium 中负责 JavaScript 交互的对象是 JavaScriptValue,它是 .NET 与 JavaScript 传递数据的重要桥梁。后面将要介绍的 JavaScript 交互功能都是基于 JavaScriptValue 对象的。

您可以单纯的把 JavaScriptValue 类理解为在 .NET 里的 JavaScript 基础数据类型。它可以表示 JavaScript 中的任何数据类型,例如:字符串、数字、布尔值、数组、对象、方法等。其中,数组使用其衍生类 JavaScriptArray、对象使用其衍生类 JavaScriptObject、方法使用其衍生类 JavaScriptFunction 来表示。

执行 JavaScript 代码

WinFormium 提供了 ExecuteJavaScript 方法来执行 JavaScript 代码。您可以使用该方法来执行任何 JavaScript 代码,例如:调用 JavaScript 函数、修改 JavaScript 对象的属性值等。

// 执行 JavaScript 代码
ExecuteJavaScript("alert('Hello World!');");

同时,WinFormium 还提供了另一个方法来执行 JavaScript 代码并返回执行结果,该方法是 EvaluateJavaScriptAsync。这个方法返回可等待的 Task<JavaScriptResult> 对象,您可以使用 await 关键字来等待 JavaScript 代码执行完成并获取执行结果。其中 JavaScriptResult 包含了 JavaScript 代码执行的结果,Success 属性指示了 JavaScript 代码是否执行成功,当代码执行错误时,ExceptionText 属性包含了 JavaScript 代码的错误提示。当代码执行成功时,ReturnValue 属性包含了 JavaScript 代码的返回值。

// 执行带结果的JavaScript表达式,如果不需要返回结果,可以使用ExecuteJavaScript方法。
var retval = await EvaluateJavaScriptAsync("3+4");

// 获取返回结果,类型为JavaScriptValue,可以使用JavaScriptValue的各种方法来获取返回结果的值。
// 这个版本为JavaScriptValuew提供了各类显式、隐式转换操作符,可以直接将JavaScriptValue转换为各种基本类型。
// 例如下面的代码将JavaScriptValue转换为int类型。
int value1 = retval.ReturnValue;

// 获取页面标题
var retval2 = await EvaluateJavaScriptAsync("document.title");

// 显式转换为可空string类型
string? value2 = retval2.ReturnValue;

// 返回一个函数对象
var retval3 = await EvaluateJavaScriptAsync("(a)=>{ const v = a.apply(); console.log(`value:${v}`); }");

// 获取函数对象的Invoker,可以通过该Invoker类型的ExecuteAsync调用这个函数对象。这里使用了JavaScriptSynchronousFunction,表示这个函数对象是同步执行的,如果是异步执行的,可以使用JavaScriptAsynchronousFunction,根据函数对象的参数类型来选择。
var retval4 = await ((JavaScriptFunctionInvoker)retval3.ReturnValue).ExecuteAsync(new JavaScriptSynchronousFunction((a) => "Callback function for retval3."));

// 函数对象的返回结果,这里是string类型
string? value3 = retval4.ReturnValue;

// 返回一个函数对象,这个函数对象是异步执行的,所以使用JavaScriptAsynchronousFunction
var retval5 = await EvaluateJavaScriptAsync("(callback)=>{ callback().then(x=>console.log(`success:${x}`)).catch(err=>console.log(`success:${err}`)); }");

// 在JavaScriptAsynchronousFunction中提供了一个Promise参数,可以使用这个参数的Resolve方法来返回结果,也可以使用Reject方法来返回错误。因为是异步的,所以这里使用了await关键字来等待这个异步函数的执行结果。

// promise resovle
var retval6 = await ((JavaScriptFunctionInvoker)retval5.ReturnValue).ExecuteAsync(new JavaScriptAsynchronousFunction(async (args, promise) =>
{
    await Task.Delay(5000);
    promise.Resolve("Resolved for retval5.");
}));

// promise reject
var retval7 = await ((JavaScriptFunctionInvoker)retval5.ReturnValue).ExecuteAsync(new JavaScriptAsynchronousFunction(async (args, promise) =>
{
    await Task.Delay(1000);
    promise.Reject("Rejected for retval5.");
}));

在上面的示例代码中,已经展示了 EvaluateJavaScriptAsync 执行 JavaScript 代码的各种情况,并且还展示了作为 JavaScriptValue 类型的 ReturnValue 属性在不同情况下的类型转换,以及它作为回调 JavaScript 前端方法的 JavaScriptFunctionInvoker 类型时的使用方法。

至于数组和对象的使用方法,将在后面的章节的具体示例中介绍。

在 JavaScript 中注册 .NET 映射对象

WinFormium 提供给了在前端 JavaScript 环境中注册 .NET 对象的功能。您可以使用 RegisterJavaScriptObject 方法来注册一个 .NET 对象的映射,然后在 JavaScript 的 window.external 对象中找到并使用您注册的对象。

有关 .NET 映射对象的更多信息,请参考《在 JavaScript 中注册 .NET 映射对象》

注册 JavaScript 窗体绑定对象

窗体绑定对象 (Window Binding Object) 是 CEF 的一个概念,它是一个 JavaScript 对象,用于在 JavaScript 环境中访问窗体的一些属性和方法。有关窗体绑定对象的更多信息,请参考 CEF 的《窗体绑定对象》一文,虽然该文档使用 C++ 编码,但是这对理解窗体绑定的原理是非常有帮助的。

有关在 WinFormium 中创建和注册窗体绑定对象的更多信息,请参考《注册 JavaScript 窗体绑定对象》

另请参阅