Native Windows GUI：轻量级、高性能的 Rust Windows 桌面GUI开发框架

# Native Windows GUI：轻量级、高性能的 Rust Windows 桌面GUI开发框架

## 一、核心概念

Native Windows GUI（简称 NWG）是一个专为 Rust 语言设计的 Windows 桌面图形用户界面开发库。其核心理念是提供一个对 Windows 原始 API（WINAPI）的轻量级、安全且符合 Rust 语言习惯的封装。与许多重量级 GUI 框架不同，NWG 追求极致的简洁与高效，力求在最小化资源占用和编译时间的同时，为开发者提供构建完整 Windows 桌面应用所需的核心功能。

该库的主要定位与设计哲学可以概括为以下几点：

- **轻量级封装**：NWG 并非从零构建的抽象层，而是直接构建在 WINAPI 之上的薄封装。这意味着它避免了大型框架带来的冗余开销和性能损耗，开发者能更直接地掌控底层行为。
- **安全与易用**：通过 Rust 的所有权系统和类型安全特性，NWG 将 WINAPI 中常见的内存泄漏、空指针和句柄管理错误在编译时或运行时以安全的方式暴露出来，大大降低了开发难度和出错概率。
- **开发效率优先**：NWG 的设计目标之一是减少开发者查阅文档的时间。其 API 设计遵循 Rust 的习惯用法，Builder 模式和宏的应用使得代码编写直观、简洁，同时保持了高度的灵活性。
- **最终版本**：NWG 的当前版本（第三版）被其作者标记为“成熟”或“功能完备”。这意味着其 API 已经稳定，不会再有重大架构变更，开发者可以信赖其长期可用性。作者明确表示，未来对 Windows GUI 的扩展功能将以独立库的形式发布，而非修改 NWG 核心。

NWG 并非为跨平台设计，它唯一的目标平台是 Microsoft Windows。这一专注使得它能够深度利用 Windows 平台的特性，提供比通用框架更优的性能和更完整的原生体验。

## 二、项目结构

NWG 项目本身被清晰地划分为多个独立的 crate，各自承担不同的职责。理解这种结构有助于开发者选择合适的组件并理解其依赖关系。

1. **native-windows-gui（核心库）**：这是 NWG 的主体部分，包含了所有 GUI 控件的定义、布局管理器、事件系统、资源加载以及与 WINAPI 交互的核心逻辑。开发者绝大多数的开发工作都将基于此 crate。它还内含一个交互式测试套件和大量示例程序。

2. **native-windows-derive（过程宏库）**：这是一个独立的 crate，提供了一个名为 `NwgUi` 的 derive 宏。该宏能够根据开发者定义的结构体自动生成 GUI 构建、事件绑定和资源管理的样板代码。这极大地简化了大型应用程序的开发，避免了手动编写大量重复的初始化代码。

3. **文档与示例**：项目目录下的 `docs` 文件夹包含了详尽的在线文档，覆盖了从入门到高级用法的各个方面。`showcase` 文件夹则存放了库中各个示例程序的运行截图。

4. **Cargo.toml 与依赖管理**：整个项目采用 Cargo 工作空间管理。`native-windows-gui` 和 `native-windows-derive` 是主要的发布工件，开发者只需在项目的 `Cargo.toml` 中声明依赖即可。

## 三、支持的WinAPI 控件与功能

NWG 几乎完整地覆盖了 WINAPI 标准控件库（common control library），为其提供了 Rust 绑定。它支持以下核心控件和功能：

**标准控件**：
- **窗口与对话框**：主窗口（Window）、模态与非模态对话框。
- **基础输入控件**：按钮（Button）、文本框（TextInput/Edit）、多行文本框（RichEdit）、复选框（CheckBox）、单选按钮（RadioButton）。
- **列表与选择控件**：列表框（ListBox）、组合框（ComboBox）、树形视图（TreeView）、列表视图（ListView/Report模式）。
- **进度与状态指示**：进度条（ProgressBar）、滑块（Slider/Trackbar）、静态文本框（Static/Label）、分组框（GroupBox）。
- **容器控件**：选项卡（TabControl）、面板（Panel）。

**高级控件与功能**：
- **菜单系统**：完全支持菜单栏、弹出式菜单及右键上下文菜单。
- **图像资源**：全面支持位图（BMP）、图标（ICO）、光标（CUR），并通过 Windows 图像处理组件（WIC）扩展支持 PNG、GIF、JPG、TIFF、DDS 等现代格式。
- **系统集成**：系统托盘图标（Tray Icon）通知、光标（Cursor）自定义与捕获。
- **对话框**：文件对话框（打开、保存、选择文件夹）、字体选择对话框、颜色选择对话框。
- **剪贴板**：完整的剪贴板读写封装，支持文本、图像等多种格式。
- **拖放支持**：支持从资源管理器将文件拖放到应用窗口。
- **多线程支持**：允许在非 GUI 线程中与 GUI 主线程安全通信，也支持在不同线程上独立运行多个窗口。

**布局管理**：
- **FlexboxLayout**：弹性布局，支持控件在水平或垂直方向上的灵活排列与自适应大小。
- **GridLayout**：网格布局，允许将控件精确放置于行和列组成的单元格中，支持跨行跨列。

**未支持的特殊控件**：鉴于其极低的用户基数，NWG 有意省略了对“扁平滚动条”（Flat Scroll Bar）、“IP 地址控件”（IP Control）、“Rebar”和“Pager”等特殊控件的支持。这些控件的缺失不会影响绝大多数桌面应用开发。

## 四、性能与资源特性

性能是 NWG 的核心优势之一，其具体数值（由作者在 Intel i7-3770 平台测得）充分体现了“轻量级”的承诺：

- **二进制文件尺寸**：在 Release 模式下，一个包含窗口、输入框、按钮的“basic”示例程序，其生成的 `.exe` 文件仅约 **163KB**。即使包含所有功能模块的交互式测试套件，其大小也仅为 **931KB**。
- **内存占用**：上述“basic”示例程序运行时，内存占用约为 **900KB**。包含数百个测试用例的完整测试套件运行时也仅消耗 **8MB** 内存。
- **启动速度**：应用程序启动为“瞬时”级别，几乎没有可感知的延迟。
- **编译速度**：由于底层依赖 `winapi-rs`，首次编译一个简单应用大约需要 **22秒**。但后续的增量编译则快的多，通常只需 **0.7秒**。

这些数据表明，NWG 极其适合对资源敏感或需要快速启动的应用场景，例如系统工具、桌面小部件或嵌入式计算环境。

## 五、开发模式与代码示例

NWG 提供了三种灵活的开发模式，以适应从简单原型到复杂项目的不同需求。

### 5.1 使用 `native-windows-derive` 宏（推荐方式）

这是最高效、最现代化的开发方式。开发者只需定义一个结构体并用 `#[derive(NwgUi)]` 标注，然后在字段上使用 `#[nwg_control]`、`#[nwg_events]` 和 `#[nwg_layout_item]` 等属性宏声明控件属性、事件处理逻辑和布局信息。宏会自动生成所有必要的事件循环和资源管理代码。

以下代码演示了如何创建一个简单的“Say My Name”应用：

```rust
#[windows_subsystem = "windows"]
extern crate native_windows_gui as nwg;
extern crate native_windows_derive as nwd;

use nwd::NwgUi;
use nwg::NativeUi;

#[derive(Default, NwgUi)]
pub struct BasicApp {
    #[nwg_control(size: (300, 115), position: (300, 300), title: "Basic example", flags: "WINDOW|VISIBLE")]
    #[nwg_events(OnWindowClose: [BasicApp::say_goodbye])]
    window: nwg::Window,

    #[nwg_layout(parent: window, spacing: 1)]
    grid: nwg::GridLayout,

    #[nwg_control(text: "Heisenberg", focus: true)]
    #[nwg_layout_item(layout: grid, row: 0, col: 0)]
    name_edit: nwg::TextInput,

    #[nwg_control(text: "Say my name")]
    #[nwg_layout_item(layout: grid, col: 0, row: 1, row_span: 2)]
    #[nwg_events(OnButtonClick: [BasicApp::say_hello])]
    hello_button: nwg::Button,
}

impl BasicApp {
    fn say_hello(&self) {
        nwg::modal_info_message(&self.window, "Hello", &format!("Hello {}", self.name_edit.text()));
    }

    fn say_goodbye(&self) {
        nwg::modal_info_message(&self.window, "Goodbye", &format!("Goodbye {}", self.name_edit.text()));
        nwg::stop_thread_dispatch();
    }
}

fn main() {
    nwg::init().expect("Failed to init Native Windows GUI");
    nwg::Font::set_global_family("Segoe UI").expect("Failed to set default font");
    let _app = BasicApp::build_ui(Default::default()).expect("Failed to build UI");
    nwg::dispatch_thread_events();
}
```

### 5.2 使用 `NativeUi` trait（手动构建）

如果不使用过程宏，开发者需要手动实现 `NativeUi` trait。这种方式提供了最大的控制权，适合理解底层运作机制或处理宏无法覆盖的特殊场景。代码结构清晰，但略显冗长。

### 5.3 纯“裸”API调用

对于极其简单的静态界面或对性能有极致要求的场景，NWG 允许完全不使用 `NativeUi`，直接通过 `Builder` 模式创建控件，并使用 `full_bind_event_handler` 来绑定事件。这种方式最为底层、灵活，但需要开发者自行管理事件处理器的生命周期。

## 六、跨平台编译

NWG 虽然是 Windows 原生库，但开发者可以在 Linux 环境（如 Ubuntu）上通过 MinGW 工具链进行交叉编译并测试。

**必要条件**：
- MinGW 编译器：`sudo apt install gcc-mingw-w64-x86-64`
- Rust 目标支持：`rustup target add x86_64-pc-windows-gnu`

**编译与运行示例**：
```bash
cargo build --release --target=x86_64-pc-windows-gnu
cargo build --release --target=x86_64-pc-windows-gnu --example basic
wine target/x86_64-pc-windows-gnu/release/examples/basic.exe
```

需要说明的是，虽然大部分功能可以正常工作，但 Wine 并非完美模拟所有 Windows API，因此并非所有特性都能在 Linux 下完美运行。开发者应优先在 Windows 环境下进行最终测试。

## 七、展望与合法性

NWG 目前被作者标记为“功能完成”（feature-complete）。这意味着其现有 API 将保持稳定，不会因新增功能破坏现有代码。该库已准备好用于生产环境，并已被其他多个 Rust 项目所采用。

- **未来演进**：作者表示，未来的开发将侧重于构建基于 NWG 之上的更高级库（例如处理更复杂的渲染、动画或自定义控件），而非直接改动 NWG 核心。这保证了 NWG 作为一个稳定基础的长期价值。
- **许可协议**：NWG 使用宽松的 MIT 许可证。这意味着开发者可以自由地将 NWG 用于任何商业或非商业项目，只需保留原版权声明即可。

**总结**：Native Windows GUI 是 Rust 生态系统在 Windows 桌面开发领域的一颗明珠。它以微型库的尺寸提供了近乎完整的原生功能，通过极致的性能优化和友好的 Rust 接口，为构建高性能、低资源的 Windows 桌面应用提供了卓越的选择。对于所有希望在 Windows 平台上拥抱 Rust 的开发者而言，NWG 是一个值得深入了解和信赖的框架。