WinFormedge 项目

✨ 关于

WinFormedge 是一个基于 Microsoft WebView2 的开源 .NET 库，帮助开发者使用 HTML、CSS 和 JavaScript 构建现代且美观的 WinForms 应用。借助 WinFormedge，你可以将 Web 技术无缝集成到 WinForm 项目中，从而实现丰富且交互性强的用户界面。

🖥️ 环境要求

开发环境：

• Visual Studio 2022
• .NET 8.0 或更高版本

部署环境：

• Windows 10 1903 或更高版本

这是一个仅支持 Windows 的库，不兼容其他操作系统。

最低支持的操作系统为 Windows 10 版本 1903（2019 年 5 月更新）。并且诸如 SystemBackdrop 和 SystemColorMode 等功能仅在 Windows 11 上可用。

🪄 快速开始

使用默认项目模板创建 WinForm 应用

1. 使用 WinFormedge 的应用初始化流程替换初始化代码。

在 program.cs 文件中，应使用 FormedgeApp 而不是 Application 类来初始化你的 WinForm 应用。FormedgeApp 是用于创建 WinFormedge 应用的构建器，它提供用于配置和运行应用的方法。

using WinFormedge;

namespace MinimalExampleApp;

internal static class Program
{
    [STAThread]
    static void Main()
    {
        ApplicationConfiguration.Initialize();

        var app = FormedgeApp.CreateBuilder()
            .UseDevTools()
            .UseWinFormedgeApp<MyFormedgeApp>()
            .Build();

        app.Run();
    }
}

当创建 FormedgeApp 时，它会自动初始化 WebView2 环境并运行消息循环。

2. 创建一个 AppStartup 类。

AppStartup 类是 WinFormedge 应用的入口，提供配置应用的方法。你可以重写 OnApplicationLaunched 方法以在应用启动前执行初始化任务。

并且你必须重写 OnApplicationStartup 方法来创建应用的主窗口。如果 OnApplicationStartup 方法返回由 StartupSettings 类创建的值，FormedgeApp 将创建你的应用主窗口。否则如果 OnApplicationStartup 返回 null，应用将被关闭。

using WinFormedge;

namespace MinimalExampleApp;

internal class MyFormedgeApp : AppStartup
{
    protected override AppCreationAction? OnApplicationStartup(StartupSettings options)
    {
        return options.UseMainWindow(new MyWindow());
    }
}

你可以在 OnApplicationStartup 方法中进行诸如用户登录、用户设置等操作，以决定使用哪个窗口启动应用。此外，如果条件不满足，也可以返回 null 结束应用。

3. 创建一个 MainWindow 类。

MainWindow 是应用的主窗口。它继承自 Formedge 类。你可以使用 Formedge 创建一个包含 WebView2 控件的窗口。

using WinFormedge;
using Microsoft.Web.WebView2.Core;

namespace MinimalExampleApp;
internal class MyWindow : Formedge
{
    public MyWindow()
    {
        Url = "https://embedded.appresource.local/";
        Size = new Size(1440, 900);
        AllowFullscreen = true;
        BackColor = Color.Transparent;

        // If you have embedded resources, you can set the virtual host name to access them.
        SetVirtualHostNameToEmbeddedResourcesMapping(new EmbeddedFileResourceOptions { 
            Scheme="https", 
            HostName="embedded.appresource.local", 
            ResourceAssembly=Assembly.GetExecutingAssembly(),
            DefaultFolderName="Resources\\wwwroot"
        });

        Load += MyWindow_Load;
        DOMContentLoaded += MyWindow_DOMContentLoaded;
    }

    // Configure the window settings for the Formedge window.
    protected override WindowSettings ConfigureWindowSettings(HostWindowBuilder opts)
    {
        var win = opts.UseDefaultWindow();

        // Extends the content of the WebView into the non-client area of the window.
        win.ExtendsContentIntoTitleBar = true;
        // Sets the backdrop type of the window to blur behind or something else.
        win.SystemBackdropType = SystemBackdropType.BlurBehind;

        return win;
    }

    private void MyWindow_Load(object? sender, EventArgs e)
    {
        // Window and WebView2 are ready to use here.
    }

    private void MyWindow_DOMContentLoaded(object? sender, CoreWebView2DOMContentLoadedEventArgs e)
    {
        // The DOM content is loaded and ready to use here.
        ExecuteScriptAsync(""""
        (()=>{
            alert("Hello from WinFormedge!");
        })();
        """");
    }
}

上述代码创建了一个 Formedge 窗口。通过 Url 属性可以设置窗口的初始 URL。将 ExtendsContentIntoTitleBar 属性设置为 true 可将 WebView 扩展到窗口的非客户区，以实现无边框窗口。你也可以设置 Size 属性来指定窗口的初始大小。

当窗口和 WebView2 准备就绪时会触发 Load 事件。你可以在该事件中执行任何需要 WebView2 就绪才能进行的初始化任务。

当 DOM 内容加载完成时会触发 DOMContentLoaded 事件。你可以在该事件中执行需要 DOM 内容加载完成后才能进行的任务。

4. 运行应用程序。

你可以在 Visual Studio 中按下 F5 运行应用。应用将创建一个带有 WebView2 控件的窗口，并显示必应首页。

你可以通过点击并拖拽页面的页眉元素来拖动窗口，也可以通过拖拽窗口边缘来调整窗口大小。