借助 wv2winrt 工具 (WebView2 WinRT JS 投影工具) ,Web 端 JavaScript 代码可以访问本机 WinRT 方法和属性。 wv2winrt 工具可为 JavaScript 代码生成所需的代码文件,并支持使用任何 WinRT API 的方法和属性,包括:
- WebView2 主机应用的 WinRT API。
- Windows WinRT API。
- 第三方 WinRT API。
有关为何希望 Web 端 JavaScript 代码访问 WinRT 主机应用的方法和属性的详细信息,请参阅 从 Web 端代码调用本机代码的简介。
WinRT 和 .NET 为何使用不同的方法
本文适用于 WinRT WebView2 API,而非 .NET WebView2 API。 本文中的 C# 代码将为 .NET WebView2 API 生成,但不运行。 使用本文的 C# 代码进行 .NET WebView2 API 调用 AddHostObjectToScript 将生成错误消息。
投影 WinRT 对象时需要 WebView2 WinRT JS 投影工具) (wv2winrt 工具,因为 WinRT 不支持 IDispatch 或任何其他机制来动态检查 WinRT 对象并与之交互,而 WebView2 的 Win32 和 .NET 平台支持这些机制。 对于 .NET 的 AddHostObjectToScript使用 ,请参阅 从 Web 端代码调用本机代码, 而不是本文。
WinUI 3 与 WinUI 2 的设置差异
如果你的 WinRT WebView2 应用面向 WinUI 3 (Windows 应用 SDK) 而不是 WinUI 2 (UWP) ,下面概述了下面进一步提供的 WinUI 3 特定步骤:
在非打包应用中,必须执行“使用 Windows 运行时组件增强非打包桌面应用”一文中的其他步骤。
添加到
WinRTAdapterCsWinRTIncludes.对于 WinUI 3 (Windows 应用 SDK) 应用,主应用项目具有对 WinAppSDK 的引用,其中直接包含其自己的 WebView2 SDK 文件副本,因此,如果不生成错误消息,则无法在主应用项目中包含对 WebView2 SDK 的引用。
项目适配器版本不必匹配。
安装 Visual Studio 2022 社区版的“默认”选项后,在 Visual Studio 安装程序中,单击 .NET 卡,然后在右侧选中复选框 Windows 应用 SDK C# 模板。
如果仍未显示正确的项目模板:在 Visual Studio 安装程序中,单击 UWP 卡将其选中,选中右侧的“v143 C++ 工具”复选框,然后单击“修改”按钮。
此示例的策略和最终目标
策略
本文将指导你完成以下主要步骤:
(WebView2 WinRT JS 投影工具) 为 wv2winrt 工具创建 WinRTAdapter 项目。
对于此示例,请指定以下用于投影的主机端 API:
运行 wv2winrt 工具为所选命名空间或类生成 C++/WinRT 源代码。
在主 WinUI 项目中调用 AddHostObjectToScript。
从 Web 端 JavaScript 代码 (或从 DevTools 控制台) 调用主机对象上的方法和属性。
最终目标
首先,我们将挑选一些我们想要从 JavaScript 代码调用的 WinRT API。 在本示例中,我们将命名空间中的 Windows.Globalization WinRT Language 类用于 Windows UWP 应用程序。
Windows.Globalization.Language 类支持从客户端的本机操作系统获取语言信息。
在 WebView2 主机应用中,Web 端 JavaScript 代码可以访问本机代码中对象 Language 的方法和属性。
通过 DevTools 控制台访问投影的 API
在本示例演练的最后,你将使用 Microsoft Edge DevTools 的控制台来测试对类的Language主机displayName属性的读取:
const Windows = chrome.webview.hostObjects.sync.Windows;
(new Windows.Globalization.Language("en-US")).displayName;
然后,DevTools 控制台将输出 English (美国)或其他语言显示名称,表明已从 Web 端 JavaScript 代码调用了本机代码:
您可以同样访问 Windows.System.UserProfile 命名空间 成员。
通过源代码文件访问投影的 API
同样,在源代码文件而不是在 DevTools 控制台中,可以访问投影的主机对象。 首先,运行脚本的设置代码:
// early in setup code:
const Windows = chrome.webview.hostObjects.sync.Windows;
然后,在代码的主体中添加对投影对象的调用,如下所示:
(new Windows.Globalization.Language("en-US")).displayName;
您可以同样访问 Windows.System.UserProfile 命名空间 成员。
让我们开始吧!
步骤 1:创建或获取基本 WebView2 项目
安装 Visual Studio
- 如果尚未安装 Visual Studio 2015 或更高版本,请在单独的窗口或选项卡中,请参阅为 WebView2 设置开发环境中的安装 Visual Studio。 按照该部分中的步骤操作,然后返回到本页面并继续以下步骤。 本文显示了 Visual Studio Community Edition 2022 的屏幕截图。
安装 Microsoft Edge 的预览频道
- 如果尚未安装 Microsoft Edge (Beta、Dev 或 Canary) 的预览频道,请在单独的窗口或选项卡中参阅为 WebView2 设置开发环境中的安装 Microsoft Edge 预览频道。 按照该部分中的步骤操作,然后返回到本页面并继续以下步骤。
创建或打开基本 WebView2 项目
执行以下任一方法获取基线入门项目,该项目包含几行嵌入 WebView2 控件的 WebView2 代码:
使用提供的基线示例解决方案: 如果尚未完成,
WebView2Samples请克隆存储库或将存储库下载到本地驱动器。 在单独的窗口或选项卡中,请参阅为 WebView2 设置开发环境中的下载 WebView2Samples 存储库。 按照该部分中的步骤操作,然后返回到此页面并继续下面的操作。 此方法使用本地副本 https://github.com/MicrosoftEdge/WebView2Samples/tree/main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln。使用 Visual Studio 中的项目模板创建基本 UWP 应用并添加 WebView2 控件:执行 WinUI 2 (UWP) 应用中的 WebView2 入门中的步骤,创建一个基线入门项目,其中包含几行嵌入 WebView2 控件的 WebView2 代码。
使用现有的基本代码: 如果已有自己的应用代码库,则可以在 Visual Studio 中打开该项目。
在本地驱动器上,打开上面获取的文件
.sln,例如 Samples 存储库解决方案:<your-repos-directory>/WebView2Samples-main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln<your-repos-directory>/WebView2Samples/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln
此时将在 Visual Studio 中打开示例解决方案:
在 Visual Studio 中,选择“ 调试>启动调试”。 这将生成项目,然后运行项目的基线版本。 此时将打开基线应用,例如 MyUWPGetStartApp 窗口:
显示了一个 WinUI 2 (UWP) 应用,它添加了 WebView 控件,设置为最初导航到 Bing.com。 这是在 UWP) 应用中执行“WinUI 2 中的 WebView2 入门”中的步骤 (产生的应用。
关闭应用窗口。
步骤 2:为 wv2winrt 工具添加 WinRTAdapter 项目
接下来, (WebView2 WinRT JS 投影工具) 为 wv2winrt 工具创建 WinRTAdapter 项目。 此项目基于运行该工具生成的代码库。 此生成的代码允许在 WebView2 控件中公开 WinRT API。
为 wv2winrt 工具添加一个项目,如下所示:
在 Visual Studio 中,打开上一步中的 WinUI 项目。
在 解决方案资源管理器 中,右键单击解决方案 (而不是项目) ,然后选择“添加>新项目”。 “ 添加新项目 ”对话框将打开。
在“搜索”文本框中,输入 Windows 运行时 组件 (C++/WinRT) 。
备选方法:如果未按照下面的编号步骤所述使用 Windows 运行时 组件 (C++/WinRT) 的项目模板添加项目,则需要按照 UWP 应用程序 > C++/WinRT 简介中的步骤安装 通用 Windows 平台 开发工作负载。
选择 Windows 运行时 组件 (C++/WinRT) 卡,然后单击“下一步”按钮:
注意: 确保模板在其名称中包含“C++/WinRT”。 如果未列出此模板,请从 Visual Studio 安装程序中安装通用 Windows 平台开发工作负载。 如果您使用的是 Visual Studio 2019,但仍然找不到模板,请从 Visual Studio > 扩展>管理扩展中安装适用于 VS2019 扩展的 C++/WinRT 模板和可视化工具。
此时将打开 “配置新项目” 窗口。
配置和创建项目
在 “项目名称 ”文本框中,将项目命名为“ WinRTAdapter”。 注意: 现在,必须使用此特定的项目名称。
上面屏幕截图中的路径反映了克隆示例存储库的方法。
单击“创建”按钮。
此时将打开“ 新建 Windows 项目 ”对话框:
单击“ 确定” 按钮。
WinRTAdapter 项目已创建并添加到主项目旁边的解决方案资源管理器中:
选择 “文件>” (Ctrl+Shift+S) 保存全部。
WebView2 WinRT JS 投影工具 (wv2winrt 工具) 将在此 WinRTAdapter 项目中运行。 在下面的步骤中,您将为此项目中的选定类生成代码。
步骤 3:为 WinRTAdapter 项目安装 Windows 实现库
在 WinRTAdapter 项目中,安装 WIL) (Windows 实现库,如下所示:
在解决方案资源管理器中,右键单击 WinRTAdapter 项目,然后选择“管理 NuGet 包”。 NuGet 包管理器 窗口将在 Visual Studio 中打开。
在 “NuGet 包管理器 ”窗口中,单击“ 浏览 ”选项卡。
在“NuGet 程序包管理器”窗口的“搜索”框中,输入“Windows 实现库”,然后选择“Windows 实现库”卡:
点按“ 安装 ”按钮。 “ 预览更改 ”对话框将打开:
单击“ 确定” 按钮。
选择 “文件>” (Ctrl+Shift+S) 保存全部。
现在已为 WinRTAdapter 项目安装 WIL。 WIL) (Windows 实现库是一个仅包含头文件的 C++ 库,可更轻松地使用适用于 Windows 的 COM 编码。 它为 Windows COM 编码模式提供可读的类型安全 C++ 接口。
步骤 4:为 WinRTAdapter 项目安装 WebView2 预发行 SDK
在 WinRTAdapter 项目中,还安装 WebView2 SDK 的预发行版本,如下所示:
在解决方案资源管理器中,右键单击 WinRTAdapter 项目,然后选择“管理 NuGet 包”。 此时将会打开“NuGet 包管理器”窗口。
在 “NuGet 包管理器 ”窗口中,单击“ 浏览 ”选项卡。
选中“ 包括预发行版 ”复选框。
在 搜索 框中,输入 WebView2。
单击 Microsoft.Web.WebView2 卡。 详细信息显示在窗口的中间区域。
在 “版本” 下拉列表中,选择 WebView2 SDK 的 预发行 版本,或确保选择了 “最新预发行版” 。 版本必须为 1.0.1243.0 或更高版本。 请注意您选择的版本号。
点按“ 安装 ”按钮。 “ 预览更改 ”对话框将打开:
单击“ 确定” 按钮。
选择 “文件>” (Ctrl+Shift+S) 保存全部。
现在已为 WinRTAdapter 项目安装 WebView2 预发行 SDK。
步骤 5:仅) 安装 WebView2 预发行版 SDK (WinUI 2
在主项目(如 MyUWPGetStartApp)中,安装与为 WinRTAdapter 项目安装的相同的预发行版 WebView2 SDK,如下所示:
在解决方案资源管理器中,右键单击主项目(如 MyUWPGetStartApp),然后选择“管理 NuGet 包”。 此时将会打开“NuGet 包管理器”窗口。
选中“ 包括预发行版 ”复选框。
选择“ 浏览 ”选项卡。
在 搜索 框中,输入 WebView2。
单击 Microsoft.Web.WebView2 卡。 详细信息显示在窗口的中间区域。
在 “版本” 下拉列表中,选择 WebView2 SDK 的 预发行 版本,或确保选择了 “最新预发行版” 。 请确保使用与 WinRTAdapter 项目使用的相同版本;对于面向 WinUI 2 (UWP) 的 WinRT WebView2 应用,这需要与 WinRTAdapter 项目的版本相同。 版本必须为 1.0.1243.0 或更高版本。
点按“ 安装 ”按钮。 此时将打开“预览更改”对话框,将 WebView2 添加到主项目。
单击“ 确定” 按钮。
Visual Studio 应类似于上述步骤部分,只不过现在为主项目而不是 WinRTAdapter 项目打开 NuGet 包管理器。
选择 “文件>” (Ctrl+Shift+S) 保存全部。
现在已为主项目安装 WebView2 预发行 SDK。
步骤 6:为所选主机 API 生成源代码
接下来,将 wv2winrt 工具配置 (WebView2 WinRT JS 投影工具) ,以合并要使用的 WinRT 类。 这将生成随后将进行编译的源文件。 通过为这些 API 生成代码,Web 端 JavaScript 代码可以调用这些 API。
在下面的示例步骤中,我们将指定两个 Windows 命名空间, wv2winrt 工具将仅为这些命名空间下的 API 生成源代码:
稍后,当示例应用运行时,你将从 DevTools 控制台调用这些 API,以演示可以从 Web 端代码调用这些指定的主机端 API。
按如下所示指定命名空间和类:
在解决方案资源管理器中,右键单击 WinRTAdapter 项目,然后选择“属性”。 “ WinRTAdapter 属性页 ”对话框随即打开。
在左侧,展开并选择“常用属性”WebView2>。
将 使用 WebView2 WinRT API 设置为 “否”。 这样,WebView2 SDK 就不会将 WebView2 WinRT 组件复制到项目的输出。 此 WinRTAdapter 项目不会调用任何 WebView2 WinRT API,因此不需要 WinRT 组件。
将 “使用 wv2winrt 工具” 设置为 “是”。
将 “使用 JavaScript 大小写” 设置为 “是”。
在 “包含筛选器 ”行中,单击右侧的列,单击该单元格中的下拉菜单,然后单击 “编辑”。 此时将打开 “包括筛选器” 对话框。
在最顶部的文本框中,将下列字符串粘贴在单独的行上,不要前导或尾随空格:
Windows.System.UserProfile Windows.Globalization.Language
需要指定命名空间或类的全名,如上所示。
单击“ 确定” 按钮关闭“ 包括筛选器 ”对话框。
确保本演练的 “WinRTAdapter 属性页 ”对话框如下所示:
单击“ 确定” 按钮关闭“ 属性页 ”对话框。
选择 “文件>” (Ctrl+Shift+S) 保存全部。
添加指向适配器项目的引用
接下来,在主项目中添加指向适配器项目的引用。
在主项目(如 MyUWPGetStartApp)中,添加指向 WinRTAdapter 项目的引用,如下所示:
在解决方案资源管理器中,展开主项目(如 MyUWPGetStartApp),右键单击“引用”,然后选择“添加引用”。 “ 参考管理器”(Reference Manager ) 对话框随即打开。
在左侧树中,选择 “项目”。 选择 WinRTAdapter 复选框:
单击“ 确定” 按钮关闭“ 参考管理器 ”对话框。
选择 “文件>” (Ctrl+Shift+S) 保存全部。
生成 API 代码
接下来,生成 API 代码:
右键单击 WinRTAdapter 项目,然后选择 “生成”。
源代码是在 WebView2 WinRT JS 投影工具 (wv2winrt 工具的“包含筛选器”对话框中指定的命名空间或类生成的) :
-
Windows.System.UserProfile命名空间 -
Windows.Globalization.Language类
-
生成完成后,选择“ 文件>”“全部保存” (Ctrl+Shift+S) 。
重要
如果安装了 WebView2 SDK 的发行版,并且生成失败, error MIDL2011: [msg]unresolved type declaration [context]: Microsoft.Web.WebView2.Core.ICoreWebView2DispatchAdapter [ RuntimeClass 'WinRTAdapter.DispatchAdapter' ]则这是 WebView2 SDK 的发布版本中的问题,需要在上述步骤中将使用 WebView2 WinRT API 更改 为 是 。
或者,在项目文件WinRTAdapter.vcxproj的最后一个</ItemGroup>之后添加以下内容:
<ItemGroup Condition="'$(WebView2UseDispatchAdapter)' == 'true'">
<Reference Include="$(WebView2SDKPath)lib\Microsoft.Web.WebView2.Core.winmd">
<!-- wv2winrt needs Dispatch Adapter metadata to generate code -->
</Reference>
</ItemGroup>
将替换为安装 WebView2 SDK 的目录,并在$(WebView2SDKPath)末尾加上 。\ 例如:..\<sample-directory>\packages\Microsoft.Web.WebView2.1.0.1264.42\。
步骤 7:仅) WinUI 3 (更新目标框架
如果你的应用适用于 WinUI 2 (UWP) ,请跳过此步骤。
步骤 8:在主项目中添加主对象
接下来,将 WinRT 对象从主机应用的本机端传递到主机应用的 Web 端。 为此,请添加一个 InitializeWebView2Async 调用 AddHostObjectToScript的方法,如下所示:
在 解决方案资源管理器 中,展开主项目(如 MyUWPGetStartApp),展开 MainPage.xaml,然后选择MainPage.xaml.cs。
在构造函数下方
MainPage,添加以下InitializeWebView2Async方法:private async void InitializeWebView2Async() { await WebView2.EnsureCoreWebView2Async(); var dispatchAdapter = new WinRTAdapter.DispatchAdapter(); WebView2.CoreWebView2.AddHostObjectToScript("Windows", dispatchAdapter.WrapNamedObject("Windows", dispatchAdapter)); }此方法调用
AddHostObjectToScript.在行
AddHostObjectToScript("Windows", ...中 ,Windows是顶级命名空间。 如果您有其他顶级命名空间,则可以添加对AddHostObjectToScriptへの其他调用,例如以下示例:WebView2.CoreWebView2.AddHostObjectToScript("RuntimeComponent1", dispatchAdapter.WrapNamedObject("RuntimeComponent1", dispatchAdapter));该调用为
WrapNamedObject命名空间创建包装器对象RuntimeComponent1。 调用使用AddHostObjectToScript名称RuntimeComponent1将该包装的对象添加到脚本中。有关如何使用自定义 WinRT 组件的完整指南,请参阅下面的 自定义 (第三方) WinRT 组件。
在构造函数下面的
MainPagethis.InitializeComponent();,添加以下代码:InitializeWebView2Async();右键单击主项目(如 MyUWPGetStartApp),然后选择“ 设置为启动项目”。 粗体表示启动项目。
选择 “文件>” (Ctrl+Shift+S) 保存全部。
按 F5 运行示例应用。 启用了 WebView2 的 WinUI 2 (UWP) 应用程序将打开:
主机应用的 Web 端代码 (和 DevTools 控制台) 现在可以调用主机对象的指定命名空间或类的方法和属性。
步骤 9:从 Web 端 JavaScript 调用主机对象上的方法和属性
通过 DevTools 控制台访问投影的 API
接下来,使用 DevTools 控制台演示 Web 端代码可以调用 WebView2 WinRT JS 投影工具 (wv2winrt 工具中指定的主机端 API,) :
如果应用未运行,请在 Visual Studio 中按 F5 运行示例应用。
单击 WebView2 示例应用窗口的主要部分以提供焦点,然后按 Ctrl+Shift+I 打开 Microsoft Edge DevTools。 或者,右键单击页面,然后选择“ 检查”。
此时将打开 Microsoft Edge DevTools 窗口。
如果未显示 Microsoft Edge DevTools 窗口,请按 Alt+Tab 显示该窗口。
在 “DevTools ”窗口中,选择“ 控制台 ”选项卡。
单击“ 清除控制台” (“
) ”按钮,或右键单击 控制台 ,然后选择“ 清除控制台”。 控制台中可能会定期显示消息。在 DevTools 控制台中,粘贴以下 Windows.Globalization.Language 类 代码,然后按 Enter:
const Windows = chrome.webview.hostObjects.sync.Windows; (new Windows.Globalization.Language("en-US")).displayName;控制台会输出一个语言名称字符串,例如
English (美国),说明可以从 Web 端 JavaScript 代码调用应用的主机端 (本机端) 代码:
请尝试省略括号。 在 DevTools 控制台中,输入以下语句:
new Windows.Globalization.Language("en-US").displayName;控制台会输出语言名称字符串,如
English (美国)。您可以同样访问 Windows.System.UserProfile 命名空间 成员。
关闭 DevTools 窗口。
关闭应用。
恭喜! 您已经完成了从 JavaScript 代码调用 WinRT 代码的示例演示。
通过源代码文件访问投影的 API
上面,我们使用 DevTools 控制台运行访问投影的主机对象的 JavaScript 语句。 同样,您可以从源代码文件中访问投影的主机对象。 为此,请首先运行脚本的安装代码:
// early in setup code:
const Windows = chrome.webview.hostObjects.sync.Windows;
然后,在代码的主体中添加对投影对象的调用,如下所示:
(new Windows.Globalization.Language("en-US")).displayName;
同样可以访问 Windows.System.UserProfile API 成员。
本教程步骤到此结束。 以下部分是有关 WebView2 WinRT 应用的一般信息。
自定义 (第三方) WinRT 组件
除了第一方操作系统 WinRT API 外,WebView2 WinRT JS 投影工具 (wv2winrt 工具) 支持自定义第三方 WinRT 组件。
若要将自定义 (第三方) WinRT 组件与 wv2winrt 工具配合使用,除上述步骤外,还可以执行下列步骤:
将主应用和 WinRTAdapter 项目) 以外的第三个项目 (添加到实现 WinRT 类的 Visual Studio 解决方案中。
让 WinRTAdapter 项目“添加引用”到包含 WinRT 类的新第三个项目。
更新属性中 WinRTAdapter 项目的 Include 筛选器,以同时包含新类。
添加另一行
InitializeWebView2Async以添加 winrt 类的命名空间:WebView2.CoreWebView2.AddHostObjectToScript("MyCustomNamespace", dispatchAdapter.WrapNamedObject("MyCustomNamespace", dispatchAdapter));为了方便从 Web 调用方法,可以选择在脚本中将命名空间同步代理添加为全局对象。 例如:
window.MyCustomNamespace = chrome.webview.hostObjects.sync.MyCustomNamespace;
有关此示例,请参阅以下 WebView2 示例:
- uwp-wv2winrt-custom-csharp-winrt - 作为分支的示例。
异步 WinRT 方法
按照上述指南中的步骤,您应该能够使用同步代理。 对于异步方法调用,需要使用 chrome.webview.hostObjects.options.forceAsyncMethodMatches。
该 forceAsyncMethodMatches 属性是一个正则表达式数组,其中如果任何正则表达式与同步代理上的方法名称匹配,则该方法将异步运行。 设置为 将它 [/Async$/] 与以后缀 Async结尾的任何方法匹配。 然后,匹配的方法调用就像异步代理上的方法一样工作,并返回您可以等待的承诺。
示例:
const Windows = chrome.webview.hostObjects.sync.Windows;
chrome.webview.hostObjects.options.forceAsyncMethodMatches = [/Async$/];
let result = await Windows.System.Launcher.launchUriAsync(new Windows.Foundation.Uri('https://contoso.com/'));
有关详细信息,请参阅 forceAsyncMethodMatchesCoreWebView2.AddHostObjectToScript 方法中的行。
订阅 WinRT 事件
WinRT 事件也通过脚本代理公开。 你可以使用 and addEventListener(string eventName, function handler)removeEventListener(string eventName, function handler) 方法添加和删除实例 WinRT 事件和静态 WinRT 事件的事件处理程序。
这些方法的工作原理类似于同名的 DOM 方法。 使用要订阅的 WinRT 事件的字符串名称作为第一个参数,并在引发事件时调用函数回调进行调用 addEventListener 。 使用相同参数调用 removeEventListener 将取消订阅该事件。 例如:
const Windows = chrome.webview.hostObjects.sync.Windows;
const coreApplication = Windows.ApplicationModel.Core.CoreApplication;
const coreApplicationView = coreApplication.getCurrentView();
const titleBar = coreApplicationView.titleBar;
titleBar.addEventListener('IsVisibleChanged', () => {
console.log('titlebar visibility changed to: ' + titleBar.isVisible);
});
对于提供事件参数的 WinRT 事件,这些参数作为事件处理程序函数的第一个参数提供。 例如, Windows.Foundation.Collections.PropertySet.MapChanged 事件具有 IMapChangedEventArgs<string, object> 事件参数对象,并且该对象作为回调的参数提供。
const Windows = chrome.webview.hostObjects.sync.Windows;
const propertySet = new Windows.Foundation.Collections.PropertySet();
propertySet.addEventListener('MapChanged', eventArgs => {
const key = eventArgs.key;
const collectionChange = eventArgs.collectionChange;
// ...
});
事件参数对象还将具有以下属性:
| 属性名 | 说明 |
|---|---|
target |
引发此事件的对象 |
type |
事件的字符串名称 |
detail |
提供给 WinRT 委托的所有参数的数组 |
使 AddHostObjectToScript JavaScript 代理的作用更类似于其他 JavaScript API
AddHostObjectToScript 默认使用异步和详细代理,但你可以使 AddHostObjectToScript JavaScript 代理的行为更像其他 JavaScript API。 若要详细了解 AddHostObjectToScript 及其默认行为,请参阅 AddHostObjectToScript。 此外,如果要从 JavaScript UWP 应用中的 JavaScript WinRT 投影或基于 EdgeHTML 的 WebView 迁移主机应用,则可能需要使用以下方法以更好地匹配之前的行为。
若要使 AddHostObjectToScript JavaScript 代理的行为更像其他 JavaScript API,请设置以下属性:
chrome.webview.hostObjects.option.defaultSyncProxy- 代理可以是异步的,也可以是同步的。 通常我们知道,当在同步代理上调用方法时,结果也应该是同步代理。 但在某些情况下,我们会丢失该上下文,例如当向本机代码提供对函数的引用时,然后本机代码稍后调用该函数。 在这些情况下,除非设置了此属性,否则代理将是异步的。chrome.webview.hostObjects.options.forceAsyncMethodMatches- 这是一个正则表达式数组。 如果在同步代理上调用方法,则如果方法名称与此数组中的字符串或正则表达式匹配,则实际上将异步执行方法调用。 将此值设置为 [/Async$/] 将使任何以 结Async尾的方法都是异步方法调用。 如果异步方法在此处不匹配并且未强制异步,则将同步调用该方法,阻止执行调用 JavaScript,然后返回承诺的解析,而不是返回承诺。chrome.webview.hostObjects.options.ignoreMemberNotFoundError- 如果您尝试获取代理的属性值,而该属性在相应的本机类上不存在,则会收到异常 - 除非您将此属性设置为true,在这种情况下,该行为将与 Chakra WinRT 投影行为 (和常规 JavaScript 行为匹配) 并无错误地返回undefined。
Chakra WinRT 投影将 WinRT 命名空间直接置于根对象上。 相比之下:
-
AddHostObjectToScript将异步根代理放置在 上。chrome.webview.hostObjects -
AddHostObjectToScript将同步根代理chrome.webview.hostObjects.sync放置在 上。
若要访问 Chakra WinRT 投影代码所需的根代理,可以将根代理 WinRT 命名空间位置分配给根对象。 例如:
window.Windows = chrome.webview.hostObjects.sync.Windows;
若要确保在进行其他操作之前运行设置所有这些内容的 JavaScript,可以将上述语句添加到 JavaScript,也可以使用该 CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync 方法告知 WebView2 在运行任何其他脚本之前为你注入上述语句。
以下示例演示了上述技术:
webview.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync(
"(() => {" +
"if (chrome && chrome.webview) {" +
"console.log('Setting up WinRT projection options');" +
"chrome.webview.hostObjects.options.defaultSyncProxy = true;" +
"chrome.webview.hostObjects.options.forceAsyncMethodMatches = [/Async$/,/AsyncWithSpeller$/];" +
"chrome.webview.hostObjects.options.ignoreMemberNotFoundError = true;" +
"window.Windows = chrome.webview.hostObjects.sync.Windows;" +
"}" +
"})();");
获取有关 WebView2 属性的信息
有关 WebView2 属性的信息可在两个地方获得:
- WinRTAdapter 项目的属性页。
-
wv2winrt.exe命令行帮助。 这是 WebView2 WinRT JS 投影工具) (wv2winrt 工具。
WinRTAdapter 项目的属性页
在 WinRTAdapter 项目的属性页中,要获取有关属性的帮助,请单击属性行。 帮助显示在对话框底部:
wv2winrt.exe 属性的命令行帮助
命令行帮助 (WebView2 wv2winrt.exe WinRT JS 投影工具) 提供有关 wv2winrt 工具参数的信息。 例如:
| 参数 | 说明 |
|---|---|
verbose |
列出一些要标准化的内容,包括已创建的文件以及有关包含和排除规则的信息。 |
include |
如上所示,默认情况下将排除除列出的命名空间和 runtimeclasses 之外。 include 声明可以是包含该命名空间中的所有内容的命名空间,也可以是仅包含该 runtimeclass 的 runtimeclass 名称。 |
use-javascript-case |
更改生成的代码以生成方法名称、属性名称等,它们使用与 Chakra JavaScript WinRT 投影相同的大小写样式。 默认值是生成与 winrt 匹配的名称。 |
output-path |
设置生成的文件将写入的路径。 |
output-namespace |
设置要用于生成的 WinRT 类的命名空间。 |
winmd-paths |
一个以空格分隔的列表,其中列出了用于代码生成应检查的所有 winmd 文件。 |
另请参阅
教程和示例:
- UWP) 应用 (WinUI 2 入门 - 教程:使用项目模板通过 WebView2 创建应用的步骤。
- WinUI 2 (UWP) 示例应用 - 示例:下载、生成、运行和更新示例的步骤。
API 参考:
- WinRT: CoreWebView2.AddHostObjectToScript 方法
- Win32: ICoreWebView2::AddHostObjectToScript 方法
- .NET: CoreWebView2.AddHostObjectToScript 方法
.NET 等效文章:
- 从 Web 端代码调用本机代码 - 涵盖 Win32/C++,还涵盖帧内 .NET/C# 的某些方面。