在WebView2中高效传递C#数组至JavaScript：JSON序列化实践

本文旨在解决在C# VSTO与WebView2环境中，将C#数组传递给JavaScript时遇到的数据类型不兼容问题。核心解决方案是利用JSON序列化技术，将C#数组转换为JSON字符串，然后在JavaScript端进行解析，从而实现C#复杂数据类型与JavaScript原生数据结构的无缝互操作。

背景与挑战

在基于C# VSTO和WebView2构建的Office插件中，C#作为后端逻辑层，JavaScript作为前端UI层，两者之间的数据交互至关重要。WebView2的window.chrome.webview.hostObjects机制为C#对象提供了一种便捷的暴露方式，使得JavaScript可以直接调用C#方法。然而，当尝试直接传递复杂的C#数据类型，尤其是数组（如int[,]）时，JavaScript端可能会遇到数据无法正确识别的问题，表现为接收到空数组或不完整的数据。

例如，以下C#代码尝试返回一个二维整数数组：

public object test()
{
    int[,] xx = { { 1, 2, 3 }, { 3, 4, 5 } };
    return xx;
}

而在JavaScript中，通过window.chrome.webview.hostObjects.control.test()调用并打印结果时，可能会观察到Array(0)或[]，表明数组内容未能正确传递：

立即学习“Java免费学习笔记（深入）”；

test () {
    return new Promise(async (resolve, reject) => {
        try {
            let result = await window.chrome.webview.hostObjects.control.test();
            console.log(result); // 可能会显示 Array(0) 或 []
            console.log(JSON.stringify(result)); // 可能会显示 []
            resolve(result);
        } catch (error) {
            reject(error);
        }
    });
}

这种现象是由于WebView2在C#和JavaScript之间进行数据类型转换时，对于某些复杂的C#类型（如多维数组）没有提供直接的、开箱即用的JavaScript等效结构。为了确保数据的完整性和正确性，我们需要一种标准化的数据交换格式。

解决方案：JSON序列化与反序列化

解决此问题的核心策略是利用JSON（JavaScript Object Notation）作为C#和JavaScript之间的数据传输媒介。C#端将数组序列化为JSON字符串，然后将该字符串传递给JavaScript。JavaScript端接收到JSON字符串后，再将其反序列化为原生的JavaScript数组或对象。

C#端实现：序列化数组为JSON字符串

在C#中，我们可以使用内置的System.Text.Json命名空间（或第三方库如Newtonsoft.Json）来执行JSON序列化。以下是修改后的C# test()方法：

using System.Text.Json; // 引入System.Text.Json命名空间

public class HostObject
{
    public string test()
    {
        int[,] xx = { { 1, 2, 3 }, { 3, 4, 5 } };
        // 将二维数组序列化为JSON字符串
        string jsonString = JsonSerializer.Serialize(xx);
        return jsonString;
    }

    // 示例：传递一个字符串数组
    public string GetStringArray()
    {
        string[] names = { "Alice", "Bob", "Charlie" };
        return JsonSerializer.Serialize(names);
    }
}

代码说明：

沁言学术

你的论文写作AI助理，永久免费文献管理工具，认准沁言学术

下载

1. 我们引入了System.Text.Json命名空间，这是.NET Core 3.0及更高版本中推荐的内置JSON处理库。
2. test()方法的返回类型从object更改为string，因为我们将返回一个JSON字符串。
3. JsonSerializer.Serialize(xx)会将C#的int[,]二维数组转换为一个标准的JSON数组字符串，例如[[1,2,3],[3,4,5]]。
4. 同样，对于一维字符串数组，JsonSerializer.Serialize(names)会生成["Alice","Bob","Charlie"]。

JavaScript端实现：反序列化JSON字符串

在JavaScript端，接收到C#传递的JSON字符串后，我们需要使用JSON.parse()方法将其转换回JavaScript的原生数组或对象。

test () {
    return new Promise(async (resolve, reject) => {
        try {
            // 从C#获取JSON字符串
            let jsonResult = await window.chrome.webview.hostObjects.control.test();

            // 将JSON字符串解析为JavaScript数组
            let result = JSON.parse(jsonResult);

            console.log(result); // 现在会正确显示 [[1,2,3],[3,4,5]]
            console.log(result[0][1]); // 访问数组元素，例如 2
            console.log(JSON.stringify(result)); // 正确的JSON字符串

            resolve(result);
        } catch (error) {
            console.error("Error parsing JSON from C#:", error);
            reject(error);
        }
    });
}

// 调用示例：
(async () => {
    try {
        const data = await test();
        console.log("Received data from C#:", data);
    } catch (e) {
        console.error("Failed to get data:", e);
    }
})();

代码说明：

1. await window.chrome.webview.hostObjects.control.test()现在会返回一个JSON字符串。
2. JSON.parse(jsonResult)是JavaScript内置的函数，用于将符合JSON格式的字符串解析成JavaScript值或对象。
3. 解析后的result变量将是一个标准的JavaScript二维数组，可以像操作任何JavaScript数组一样访问其元素。

关键注意事项与最佳实践

1. 错误处理：

   • C#端： 在序列化过程中，如果对象结构复杂或包含循环引用，JsonSerializer可能会抛出异常。应在C#方法中加入try-catch块来捕获并处理这些异常。
   • JavaScript端： JSON.parse()在接收到非法的JSON字符串时会抛出SyntaxError。务必在JavaScript的try-catch块中处理此异常，以防止应用崩溃。

2. 数据类型映射：

   • System.Text.Json会自动将C#的原始类型（如int, string, bool, double）映射到JSON的相应类型。
   • C#的数组（T[]或T[,]）会映射到JSON数组。
   • C#的List也会映射到JSON数组。
   • C#的自定义类（public属性）会映射到JSON对象。

3. 性能考量：

   • 对于非常大的数据集，JSON序列化和反序列化会带来一定的性能开销。在性能敏感的场景下，需要评估这种开销是否可接受。
   • 如果数据量极大且结构复杂，可以考虑更高效的二进制序列化协议，但这会增加C#和JavaScript两端的实现复杂性。

4. 序列化选项：

   • System.Text.Json提供了JsonSerializerOptions类，允许自定义序列化行为，例如：
     • WriteIndented = true：生成带缩进的JSON，便于阅读。
     • PropertyNamingPolicy = JsonNamingPolicy.CamelCase：将C#属性名转换为camelCase（JavaScript常用命名风格）。
     • DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull：忽略值为null的属性。

   // 示例：使用自定义序列化选项
   var options = new JsonSerializerOptions
   {
       WriteIndented = true, // 格式化输出
       PropertyNamingPolicy = JsonNamingPolicy.CamelCase // 属性名转为小驼峰
   };
   string jsonString = JsonSerializer.Serialize(xx, options);

5. 替代方案（Newtonsoft.Json）： 如果项目已经依赖Newtonsoft.Json（Json.NET），也可以使用它进行序列化，其API与System.Text.Json类似：

   // 需要安装 NuGet 包 Newtonsoft.Json
   using Newtonsoft.Json;
   
   public string testNewtonsoft()
   {
       int[,] xx = { { 1, 2, 3 }, { 3, 4, 5 } };
       return JsonConvert.SerializeObject(xx);
   }

   对于大多数现代.NET应用，System.Text.Json是首选，因为它性能更优且是内置库。

总结

在C# VSTO和WebView2的集成环境中，通过window.chrome.webview.hostObjects机制传递C#数组等复杂数据类型到JavaScript的最佳实践是利用JSON进行序列化和反序列化。C#端负责将数据序列化为JSON字符串，JavaScript端负责解析该字符串。这种方法不仅解决了数据类型不兼容的问题，还提供了一种标准化、灵活且易于理解的数据交换方式，极大地增强了C#与JavaScript之间的互操作性。务必在两端都实现健壮的错误处理机制，以确保应用的稳定性和可靠性。