NanUI
窗体功能
概述
本文主要介绍如何使用 WinFormium 的窗体 Formium 类及其与窗体相关内容。Formium 类中与浏览器相关的内容将在《浏览器功能》中介绍。
创建窗体
您可以继承 Formium 类来创建和设置窗体属性。
using WinFormium;
class MyWindow : Formium
{
public MyWindow()
{
Url = "https://www.bing.com/"
}
}
使用以上代码，您可以创建一个简单的窗体。指定 Formium 类的 Url 属性值可以指定窗体默认加载的页面，该属性接受一个 string 类型的参数，您可以在这里指定一个网页地址。正如上面示例代码，它将会在窗体显示后加载 https://www.bing.com/ 网页。
设置窗体样式
Formium 窗体内置了多种窗体样式，您可以重载 Formium 类的 ConfigureWindowStyle 方法来设置窗体样式。 ConfigureWindowStyle 方法接受一个参数 WindowStyleBuilder，使用该参数您可以设置窗体的样式。
protected override FormStyle ConfigureWindowStyle(WindowStyleBuilder builder)
{
var style = builder.UseSystemForm();
return style
}
上面代码示例使用系统窗体样式，这也是默认的 Formium 窗体样式。如果您的应用程序对窗体样式没有特别需求，那么就不必重载 ConfigureWindowStyle 方法。
WindowStyleBuilder 对象提供了多个 UseXXX 方法来设置不同的窗体样式，这些方法返回一个 FormStyle 的子类，除了基类 FormStyle 中提供的样式设置外，不同的窗体样式还提供了该样式特有的属性。您可以设置 FormStyle 类的属性来设置窗体的基础样式，并使用其子类设置特有的样式属性。
在 FormStyle 对象中提供了以下属性：
| 属性 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| AllowFullScreen | 是否允许全屏 | bool | true |
| AllowSystemMenu | 是否允许系统菜单 | bool | true |
| ColorMode | 窗体颜色模式，属性值：SystemPreference - 跟随系统（Windows 11）Light - 亮色模式Dark - 暗色模式 |
FormiumColorMode | FormiumColorMode.SystemPreference |
| DefaultAppTitle | 默认窗体标题 | string | WinFormium |
| Icon | 窗体图标 | Icon | DefaultIcon |
| Location | 窗体位置 | Point | Point.Empty |
| Maximizable | 是否允许最大化 | bool | true |
| MaximiumSize | 窗体最大的尺寸 | Size | Size.Empty |
| Minimizable | 是否允许最小化 | bool | true |
| MinimiumSize | 窗体最小的尺寸 | Size | Size.Empty |
| ShowInTaskbar | 是否在任务栏显示 | bool | true |
| Sizable | 是否允许调整窗体大小 | bool | true |
| Size | 窗体尺寸 | Size | Size.Empty |
| StartCentered | 窗体是否居中显示且居中显示的方式，属性值：None - 不居中CenterScreen - 位于屏幕居中CenterParent - 位于父窗体居中 |
StartCenteredMode | StartCenteredMode.None |
| TopMost | 窗体是否置顶显示 | bool | false |
| UsePageTitle | 是否使用网页标题作为窗体标题 | bool | false |
| WindowState | 窗体状态，属性值：Normal - 正常Maximized - 最大化Minimized - 最小化FullScreen - 全屏 |
FormWindowState | FormWindowState.Normal |
目前 WinFormium 窗体内置了以下几种窗体样式，如果需要了解这些窗体样式，请参考以下文章：
使用 FormStyle 对象设置的窗体样式是只读的，这些设置会在窗体创建时生效，窗体创建工作完成后您将无法再次通过 FormStyle 修改窗体样式。Formium 类自身提供了一些属性，您可以在窗体创建后使用这些属性来修改窗体样式。
显示窗体
当您完成了 Formium 窗体的设置后，您可以使用 Formium 类的 Show 方法来显示窗体，或者使用 ShowDialog 方法以模态方式显示窗体。
如果您需要把当前 Formium 窗体作为项目的主窗体，请参考《使用启动配置文件 - 配置应用程序的主窗体》。
隐藏窗体
您可以使用 Hide() 方法来隐藏当前窗体，隐藏窗体后，您可以使用 Show() 方法来重新显示窗体。但是为了确保窗体能够正常隐藏和显示，强烈建议您设置 Formium 的 Visible 属性的属性值来实现窗体的隐藏和显示。
关闭窗体
您可以使用 Close() 方法来关闭当前窗体，关闭窗体后将销毁窗体对象，您将无法再次显示该窗体。如果需要在此显示该窗体，您需要重新创建一个新的窗体对象。
激活窗体
您可以使用 Activate() 方法来激活当前窗体，激活窗体后，窗体将会被置于最前端，并且窗体标题栏会显示为激活状态。
设置窗体焦点
您可以使用 Focus() 方法来设置当前窗体的焦点，设置焦点后，窗体将会成为焦点窗体，如果窗体是一个子窗体，那么它的父窗体将会失去焦点。
窗体居中
您可以使用 CenterToScreen() 方法来将窗体居中显示，该方法将会把窗体居中显示在屏幕上。如果您的窗体是一个子窗体，您可以使用 CenterToParent() 方法将窗体居中显示在父窗体上。
在 UI 线程中更新界面元素
在使用 WinFormium 窗体的过程中，您会发现大量的异步方法。这些异步方法运行在于 UI 线程不同的线程里，如果您要在这些非 UI 线程中操作窗体，那么您需要使用 InvokeOnUIThread 方法在 UI 线程中更新界面元素。此方法有多个重载：
| 方法 | 描述 |
|---|---|
| void InvokeOnUIThread(System.Action action) | 在 UI 线程中执行一个委托 |
| object InvokeOnUIThread(System.Delegate method, params object[] args) | 在 UI 线程中执行一个带有参数表和返回值的委托 |
| T InvokeOnUIThread<T>(System.Delegate method, params object[] args) | 在 UI 线程中执行一个带有参数表和泛型返回值的委托 |
| T InvokeOnUIThread<T>(System.Func<T> method) | 在 UI 线程中执行一个带有泛型返回值的委托 |
例如，在 UI 线程中创建并显示一个子窗体，您可以使用以下代码：
InvokeOnUIThread(() =>
{
// 在 UI 线程中执行一个委托
var form = new Form();
form.Show(this);
});
使用 InvokeOnUIThread 方法创建的窗体将会在 UI 线程中显示，这样可以避免在非 UI 线程中显示窗体导致的异常。同样的，如果您需要在运行时修改窗体的属性，您也需要使用 InvokeOnUIThread 方法来更新窗体属性。
父窗体
您可以使用 Owner 属性来获取当前窗体的父窗体，如果当前窗体没有父窗体，那么该属性的值为 null。这个属性并不返回一个实际的 Form 对象，而是返回一个 IWin32Window 接口。您可以通过该接口的 Handle 属性来获取父窗体的句柄，或者直接使用此接口来对接 WinForm 的某些 API，例如：MessageBox.Show 方法。
窗体尺寸和位置
您可以使用 Location 属性来设置当前窗体的位置，该属性接受一个 Point 类型的参数，您可以在这里指定窗体的位置。如果您需要获取窗体的位置，您可以使用 Location 属性获取窗体的位置。您还可以使用 Top 和 Left 属性来设置或获取窗体在当前桌面的位置，另外，您还可以使用 Right 和 Bottom 属性来获取窗体的右边界和下边界的位置。
您可以使用 Size 属性来设置当前窗体的尺寸，该属性接受一个 Size 类型的参数，您可以在这里指定窗体的尺寸。如果您需要获取窗体的尺寸，您可以使用 Size 属性获取窗体的尺寸。您还可以使用 Width 和 Height 属性来设置或获取窗体的宽度和高度。
此外，您可以使用 Bounds 属性获取到一个 Rectangle 类型的对象，您可以通过该对象的属性来获取窗体的位置和尺寸。
您还可以使用 MaximiumSize 和 MinimiumSize 属性来设置窗体的最大尺寸和最小尺寸，这两个属性接受一个 Size 类型的参数，您可以在这里指定窗体的最大尺寸和最小尺寸。
窗体标题
您可以使用 AppTitle 属性来设置当前窗体的标题，该属性接受一个 string 类型的参数，您可以在这里指定窗体的标题。如果您需要获取窗体的标题，您可以通过 Title 属性获取窗体的标题。
另外，如果 UsePageTitle 属性的属性值为 true，那么窗体的标题将会使用当前网页的标题和 AppTitle 属性的值拼接而成。默认拼接的方式是 PageTitle - AppTitle，您可以更改 TitlePattern 属性来设置标题字符串的拼接格式，该属性接受一个 string 类型的参数，您可以在这里指定拼接的格式。
窗体图标
您可以使用 Icon 属性来设置当前窗体的图标，该属性接受一个 Icon 类型的参数，您可以在这里指定窗体的图标。如果您需要获取窗体的图标，您可以通过 Icon 属性获取窗体的图标。
窗体状态
您可以使用 WindowState 属性来设置当前窗体的状态，该属性接受一个 FormWindowState 类型的参数，您可以在这里指定窗体的状态。如果您需要获取窗体的状态，您可以通过 WindowState 属性获取窗体的状态。FormWindowState 类型的属性值有以下几种：
| 属性值 | 描述 |
|---|---|
| Normal | 正常 |
| Maximized | 最大化 |
| Minimized | 最小化 |
| FullScreen | 全屏 |
另外，您可以指定 AllowFullScreen 属性来设置是否允许窗体全屏。使用 Minimizable 和 Maximizable 属性来设置是否允许窗体最小化和最大化。指定 Sizable 属性来设置是否允许调整窗体大小。
窗体状态除了上述属性和方法以外，还涉及到了很多前端的内容，因此关于 WinFormium 窗体状态的详细内容，请参考窗体 JavaScript 指南。
启动画面
您可以使用 EnableSplashScreen 属性来设置是否启用窗体的启动画面。如果您需要在窗体显示之前显示一个启动画面，您可以在窗体构造函数中设置 EnableSplashScreen 属性的属性值为 true。启动画面将会在窗体页面加载完成之前显示，当窗体显示完成后，启动画面将会自动关闭。
通过重载 Formium 类的 PaintSplashScreen 方法，您可以自定义窗体的启动画面。该方法接受一个 Graphics 类型的参数，您可以在这里绘制您的启动画面。
启动画面只适用于未开启 CEF 离屏渲染的窗体，开启了 CEF 离屏渲染的窗体将不会显示启动画面。
默认情况下，将显示如下的启动画面：
重载 PaintSplashScreen 方法，删除 base.PaintSplashScreen(e); 代码即可删除默认启动画面。然后使用 GDI+ 代码自定义启动画面：
protected override void PaintSplashScreen(PaintEventArgs e)
{
e.Graphics.Clear(Color.Yellow);
e.Graphics.DrawString("Loading...", SystemFonts.DefaultFont, Brushes.Black, 10, 10);
}
API 参考
属性
| 属性名 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| AllowDrop | 获取或设置一个值，该值指示控件是否可以接受用户拖放到它上面的数据。 | bool | false |
| AllowFullScreen | 获取或设置一个值，该值指示窗体是否允许全屏。 | bool | true |
| AllowSystemMenu | 获取或设置一个值，该值指示窗体是否允许系统菜单。 | bool | true |
| ApplicationContext | 获取或设置应用程序上下文。 | ApplicationContext | WinFormiumApp |
| AppTitle | 获取或设置窗体的标题。 | string | WinFormium |
| Bottom | 获取窗体的下边界的位置。 | int | 0 |
| Bounds | 获取窗体的位置和尺寸。 | Rectangle | Rectangle.Empty |
| ColorMode | 获取或设置窗体的颜色模式。 | FormiumColorMode | FormiumColorMode.SystemPreference |
| DisableAboutMenu | 获取或设置一个值，该值指示是否禁用窗体的关于菜单。 | bool | false |
| Enabled | 获取或设置一个值，该值指示控件是否可以对用户交互作出响应。 | bool | true |
| EnableSplashScreen | 获取或设置一个值，该值指示是否启用窗体的启动画面。 | bool | true |
| Handle | 获取窗体的句柄。 | IntPtr | IntPtr.Zero |
| Height | 获取或设置窗体的高度。 | int | 0 |
| Icon | 获取或设置窗体的图标。 | Icon | DefaultIcon |
| IsDisposed | 获取一个值，该值指示窗体是否已释放。 | bool | false |
| IsFullscreen | 获取一个值，该值指示窗体是否处于全屏状态。 | bool | false |
| Left | 获取或设置窗体的左边界的位置。 | int | 0 |
| Location | 获取或设置窗体的位置。 | Point | Point.Empty |
| Maximizable | 获取或设置一个值，该值指示窗体是否允许最大化。 | bool | true |
| MaximiumSize | 获取或设置窗体的最大尺寸。 | Size | Size.Empty |
| Minimizable | 获取或设置一个值，该值指示窗体是否允许最小化。 | bool | true |
| MinimiumSize | 获取或设置窗体的最小尺寸。 | Size | Size.Empty |
| Modal | 获取一个值，该值指示窗体是否以模态方式显示。 | bool | false |
| Owner | 获取当前窗体父窗体的句柄。 | IWin32Window | null |
| Right | 获取窗体的右边界的位置。 | int | 0 |
| Services | 获取窗体的服务容器。 | IServiceProvider | null |
| Sizable | 获取或设置一个值，该值指示窗体是否允许调整大小。 | bool | true |
| Size | 获取或设置窗体的尺寸。 | Size | Size.Empty |
| TitlePattern | 获取或设置窗体标题的拼接格式。 | string | {0} - {1} |
| Top | 获取或设置窗体的上边界的位置。 | int | 0 |
| TopMost | 获取或设置一个值，该值指示窗体是否置顶显示。 | bool | false |
| UsePageTitle | 获取或设置一个值，该值指示窗体是否使用网页标题作为窗体标题。 | bool | false |
| Visible | 获取或设置一个值，该值指示窗体是否可见。 | bool | true |
| Width | 获取或设置窗体的宽度。 | int | 0 |
| WindowState | 获取或设置窗体的状态。 | FormWindowState | FormWindowState.Normal |
方法
| 方法名 | 描述 | 返回值 |
|---|---|---|
| Activate() | 激活窗体。 | void |
| CenterToParent() | 将窗体居中显示在父窗体上。 | void |
| CenterToScreen() | 将窗体居中显示在屏幕上。 | void |
| Close() | 关闭窗体。 | void |
| ConfigureWindowStyle(WindowStyleBuilder builder) | 配置窗体样式。 | FormStyle |
| Dispose() | 释放窗体。 | void |
| Focus() | 设置窗体焦点。 | void |
| Hide() | 隐藏窗体。 | void |
| InvokeOnUIThread(System.Action action) | 在 UI 线程中执行一个委托。 | void |
| InvokeOnUIThread(System.Delegate method, params object[] args) | 在 UI 线程中执行一个带有参数表和返回值的委托。 | object |
| InvokeOnUIThread<T>(System.Delegate method, params object[] args) | 在 UI 线程中执行一个带有参数表和泛型返回值的委托。 | T |
| InvokeOnUIThread<T>(System.Func<T> method) | 在 UI 线程中执行一个带有泛型返回值的委托。 | T |
| Show() | 显示窗体。 | void |
| Show(System.IntPtr) | 显示窗体，并以指定句柄为父窗体。 | void |
| Show(System.Windows.Forms.IWin32Window) | 显示窗体，并以指定句柄为父窗体。 | void |
| Show(WinFormium.Formium) | 显示窗体，并以指定句柄为父窗体。 | void |
| ShowAboutDialog() | 显示窗体的关于对话框。 | void |
| ShowDialog() | 以模态方式显示窗体，并返回 DialogResult | DialogResult |
| ShowDialog(System.IntPtr) | 以模态方式显示窗体，并以指定句柄为父窗体。 | DialogResult |
| ShowDialog(System.Windows.Forms.IWin32Window) | 以模态方式显示窗体，并以指定句柄为父窗体。 | DialogResult |
| ShowDialog(WinFormium.Formium) | 以模态方式显示窗体，并以指定句柄为父窗体。 | DialogResult |
事件
| 事件名 | 描述 | 参数 |
|---|---|---|
| Activated | 当窗体被激活时发生。 | System.EventArgs |
| Closing | 当窗体关闭时发生。 | System.ComponentModel.CancelEventArgs |
| Closed | 当窗体关闭后发生。 | System.EventArgs |
| Deactive | 当窗体失去焦点时发生。 | System.EventArgs |
| GotFocus | 当窗体获得焦点时发生。 | System.EventArgs |
| Loaded | 当窗体加载完成后发生。 | System.EventArgs |
| Move | 当窗体移动时发生。 | System.EventArgs |
| Resize | 当窗体尺寸改变时发生。 | System.EventArgs |
| ResizeBegin | 当窗体开始调整大小时发生。 | System.EventArgs |
| ResizeEnd | 当窗体结束调整大小时发生。 | System.EventArgs |
| Shown | 当窗体显示后发生。 | System.EventArgs |
| VisibleChanged | 当窗体可见性改变时发生。 | System.EventArgs |
| WindowStateChanged | 当窗体状态改变时发生。 | System.EventArgs |