windui

简体中文 · English

轻量跨平台桌面 GUI 框架 — 用 Rust 构建内存友好的小工具。

平台原生窗口 · tiny-skia 矢量渲染 · 平台原生文字排版 · 无运行时 · 无 GC。

平台	窗口/呈现	文字
Windows	Win32 + GDI（DIB 拷屏）	DirectWrite
macOS	Cocoa/AppKit + CoreGraphics（CGImage blit）	Core Text

渲染层（tiny-skia）与全部控件/布局/事件逻辑平台无关；每个平台只实现「窗口+事件循环」与「文字引擎」两条缝。

为什么

做小工具时，Electron 动辄上百 MB，Go GUI 因 runtime/GC 也要 15–40MB。windui 没有运行时、没有垃圾回收，Windows 上的实测：

指标	实测值
二进制体积（release，LTO+strip）	最小窗口应用 0.44 MB；综合示例（含 SVG + 全控件）1.07 MB
私有内存（PrivateBytes，520×560 窗口）	3.65 MB
跨平台直接依赖	tiny-skia（渲染）· resvg（SVG，默认开，不用则被 LTO 裁掉）· serde + toml（主题）；平台系统绑定按 target 引入

工作集约 14MB，其中大部分是 gdi32/dwrite 等跨进程共享的系统 DLL 映射；进程真正独占的私有内存仅约 3.6MB。

特性

• 命令式 Builder API — 纯 Rust 链式构建，类型安全、零解析开销。
• Copy 句柄状态 — 状态是 Signal<T>，闭包里 move 直接捕获、不用 clone() 前戏；set() 自动触发重绘。数据变化驱动子树重建（list_signal），动态列表不用手写 diff。
• 运行期换主题 — App::theme_handle() 拿句柄，回调里 set(Theme::dark()) 即整树热切换；用 Role 表达的颜色（fg_role/bg_role）自动跟随。
• 一份代码，两个平台 — 控件树、布局、事件、动画、主题全平台无关；切换平台零改动。
• Retained 模式 + 脏触发 — 空闲不重绘、阻塞在事件循环，零 CPU 占用。
• 高质量文字 — 平台原生排版（DirectWrite / Core Text）+ 灰度抗锯齿，CJK 清晰；Label 自动换行；彩色 emoji（含 ZWJ 组合序列、肤色修饰），文本框可输入 emoji。
• DPI / Retina 感知 — 控件树用逻辑坐标、绘制层统一缩放到物理像素，文字按物理字号渲染（测量与绘制同源），高 DPI（1.5x/2x/Retina）下依然锐利、不偏小。
• 纯净焦点环 — 焦点环仅在键盘 Tab 导航时显示，纯鼠标操作不显示外框。
• 完整控件集 — 布局、文本、按钮、表单输入、容器导航、列表、图片、托盘一应俱全。
• 触摸/触控板 — 平移滚动 + 惯性滑动 + 撞界回弹。
• 可选 GPU 加速（Windows） — 大窗口可 opt-in Direct2D 后端（App::accelerated(true)），几何/渐变/阴影/文字光栅走 GPU；文字仍用 DirectWrite（系统字体缓存、ClearType）。默认软渲染；RDP / 无 GPU / 离屏截图自动回退、绝不 panic。
• 自动截屏 — --screenshot 离屏渲染存 PNG（--scale 1.5 验证高 DPI），适合自动化回归。

界面预览

下列截图全部由离屏渲染自动截取（--screenshot，见 scripts/screenshots.ps1）。

真实场景：侧栏导航 + 分段控件 + 开关 + 钻入行	TOML 主题覆盖：同一套控件一键换肤
图片能力：PNG/SVG、Fit 模式、圆角裁剪、单色着色	列表：单选 / 高亮 / 滚动 / 图标
	模态对话框 + 多标签页导航。 更多控件见下方「控件」表，或运行 cargo run --release --example fullshowcase 亲自体验。

快速开始

use windui::prelude::*;

fn main() {
    // 状态是 Signal<T>：Copy 句柄，闭包直接捕获，写入自动触发重绘
    let on = signal(true);

    let ui = Element::col()
        .fill()
        .padding(20)
        .spacing(12)
        .bg(Color::hex(0xF5F6FA))
        .child(Element::label("Hello, windui!").font_size(22.0).width_match())
        .child(Element::checkbox("启用功能", on))
        .child(Element::button("确定").on_click(move |ctx| {
            println!("checkbox = {}", on.get());
            ctx.request_close();
        }));

    App::new("Demo", 360, 240).content(ui).run();
}

控件

类别	控件
布局	col / row（LinearLayout，支持 weight）、stack（FrameLayout）、grid（等宽网格）、flex_spacer
文本	label（自动换行）、label_signal（绑信号）、link（可点击链接）、rich（富文本：多样式 span / 折叠段）
按钮	button（hover/press/focus 三态 + 点击/回车/空格激活）、icon_button（纯图标）
表单	checkbox / switch / radio（互斥组）/ slider（拖动+键盘）/ text_input（CJK 编辑+密码+多行）/ dropdown / check_menu / stepper / chip / tag_field
反馈	progress（确定/不确定）/ tooltip（悬停提示）/ toast（居中轻提示）/ badge（胶囊徽章）
容器	scroll（滚轮/触摸+裁剪+滚动条）/ tabs / tabs_pill / divider / dialog（模态）/ dialog_panel（带标题栏）/ visible_when（条件可见）
导航	segmented（连体多段单选）/ nav_row（钻入行）/ collapsible / accordion·accordion_multi（手风琴）
列表	list / list_pill（侧栏样式）/ list_icons（单选/滚动/高亮/图标/禁用态）/ list_signal（数据驱动动态列表）/ reorder_list（拖拽排序）
表格	table（只读）/ table_custom / table_editable / table_sortable / table_sortable_server（服务端排序分页）/ table_selectable（多选）
图片	image / image_svg / image_view（PNG/SVG，状态调制/着色/圆角）
系统	系统托盘（图标 + 左键/双击 + 原生右键菜单）、全局热键、多窗口（ctx.open_window，含单例窗口）、启动即隐藏、关闭转隐藏、无边框窗口（自定义标题栏）、文件拖放、剪贴板

控件状态统一绑定 Signal<T>（signal(初值) 创建的 Copy 句柄）：checkbox/switch 绑 Signal<bool>、dropdown/list/tabs 绑 Signal<usize>、text_input 绑 Signal<String>。 set() 写入即自动触发重绘，无需手动标脏。用法见 docs/API_GUIDE.md §3.2。

构建与运行

cargo run --release --example fullshowcase                  # 运行综合示例窗口
cargo run --release --example ime -- --accelerated          # 启用 Direct2D GPU 后端（Windows）
cargo run --example fullshowcase -- --screenshot out.png    # 离屏渲染存 PNG
cargo test                                                  # 运行单元测试
cargo clippy --all-targets                                  # 静态检查

示例一览：fullshowcase（综合）、settings（设置窗：侧栏 + 表格 + 对话框）、dyn_list（数据驱动动态列表）、about（卡片 + Toast）、background_task（跨线程更新）、animation、theming（TOML 主题 + 运行期切换）、image、list、dropdown、tabs_pill、toast、progress、multiline、emoji（彩色 emoji 渲染）、frameless、light_titlebar、tray、hotkey（全局热键 + 启动即隐藏）、multi_window（子窗 + 跨窗共享状态）、file_drop、ime、ime_settings，以及 phase0–phase5 分阶段演示。

架构

详见 docs/DESIGN.md（架构设计）与 docs/ROADMAP.md（实施路线）。

应用层  App / UiHost（交互宿主，实现 AppHandler）
控件层  Element Builder · Widget trait · 布局算法
核心层  Arena + Node 树 · Measure/Arrange/Paint 三阶段 · 事件分发
渲染层  Canvas trait → tiny-skia 后端（纯 Rust，跨平台）
文字层  TextEngine trait → DirectWrite（Windows）/ Core Text（macOS）
平台层  AppHandler trait → win32（窗口/WndProc/DIB 呈现）/ macos（NSWindow/NSView/CGImage 呈现）

关键设计：节点存于 generational arena（非 Rc<RefCell>），Widget trait 退化为纯内容、布局递归由 Tree 独占 &mut self 驱动 —— 从根上规避 Rust 借用冲突。文字用平台原生引擎在 tiny-skia 预乘缓冲上抗锯齿合成。平台缝合层映射见 docs/MACOS_PORTING.md。

状态

Windows 与 macOS 均已支持。MVP 控件集完成，持续完善中。

文档

文档	面向
docs/API_GUIDE.md	用本库写应用（API 风格、控件、扩展）
docs/DEVELOPMENT.md	在仓库内开发（构建、布局、加控件、平台缝）
CONTRIBUTING.md	贡献流程与 DCO 签署
docs/DESIGN.md	架构设计与取舍
docs/ROADMAP.md	实施路线与验收
docs/MACOS_PORTING.md	macOS 后端缝合层映射
AGENTS.md	仓库开发约定（流程、陷阱速查）

许可证

双许可，任选其一：

• Apache License, Version 2.0（LICENSE-APACHE）
• MIT License（LICENSE-MIT）

除非另有声明，你有意提交到本仓库的贡献，将按上述双许可授权，无附加条款（见 CONTRIBUTING.md）。