egui-winit 集成层完全指南从 winit 事件到 egui 界面的桥梁与跨平台演进【免费下载链接】eguiegui: an easy-to-use immediate mode GUI in Rust that runs on both web and native项目地址: https://gitcode.com/GitHub_Trending/eg/eguiegui-winit是 egui 生态中负责把winit窗口系统的原生事件鼠标、键盘、触摸、IME、窗口生命周期等翻译成 egui 输入、并把 egui 输出剪贴板、光标、链接、窗口命令写回操作系统的集成层。本文以 crates/egui-winit/CHANGELOG.md 为主体骨架结合 crates/egui-winit/src/lib.rs 等源码与 crates/egui-winit/Cargo.toml 特性配置梳理该 crate 的核心职责、功能特性、平台适配演进与完整版本历史帮助你理解 egui 桌面端运行时的工作方式并掌握如何配置它的特性开关。一、egui-winit 在 egui 生态中的定位egui 本身是纯立即模式 GUI 库不直接接触操作系统窗口。在原生桌面端窗口的创建、事件循环和系统交互由winit提供而egui-winit就是连接两者的胶水层。从 crates/egui-winit/src/lib.rs 的 crate 级文档可以看到它的职责将 winit 事件翻译为 egui 事件处理复制/粘贴剪贴板更新光标打开 egui 中被点击的链接。在实际工程中eframe的各个原生后端glow/wgpu都依赖egui-winit。例如 crates/eframe/src/native/glow_integration.rs 与 crates/eframe/src/native/wgpu_integration.rs 中都用egui_winit::State::new(...)为每个窗口viewport创建集成状态。egui-winit于 0.15.0 版本首次独立发布此前是egui_glium的一部分自 0.15.0 至今其变更日志完整记录了该集成层围绕 IME、剪贴板、多窗口多 viewport、无障碍AccessKit以及各桌面与移动平台适配的演进历程。二、核心架构State 与事件双向翻译2.1 State每个窗口一份的集成状态State是egui-winit的核心结构体文档明确要求每个 viewport/window 实例化一个。它内部保存了egui_ctxegui 的共享Contextviewport_id当前窗口对应的视图 IDegui_input累积的egui::RawInputmodifiers当前修饰键状态用于给每个事件打上修饰键快照pointer_pos_in_points与any_pointer_button_down指针状态current_cursor_icon与current_custom_cursor光标缓存按Arc::as_ptr去重避免每帧重复上传位图光标clipboard剪贴板句柄allow_ime、ime_rect_px、old_ime_purposeIME 状态在 Windows 上还有pressed_processed_physical_keys用于过滤被 IME 处理过的按键释放事件。State::new接收egui_ctx、viewport_id、显示句柄、native_pixels_per_point、系统主题与max_texture_side并把这些初始信息写入egui_inputlib.rs。其中max_texture_side会在创建图形上下文后通过set_max_texture_side更新对应变更日志 0.17.0 中需要获知最大纹理边长如GL_MAX_TEXTURE_SIZE的改动。2.2 事件翻译on_window_eventState::on_window_event是事件入口lib.rs它把winit::event::WindowEvent逐一映射为 egui 事件并返回EventResponseconsumedegui 是否独占消费了该事件例如点击了 egui 窗口或正在输入文字。文档特别指出如果你用 egui 做游戏只有当consumed false时才应该把事件继续传给游戏逻辑Tab键永远为true因为 egui 用 Tab 在控件间移动焦点repaint该事件是否触发一次 egui 重绘。映射关系包括MouseInput→PointerButton、MouseWheel→MouseWheel区分LineDelta与PixelDelta两种单位、CursorMoved→PointerMoved、Touch→Touch同时把首个触摸模拟为指针、PinchGesture→Zoom、RotationGesture→Rotate、PanGesture→MouseWheel(Point)以及HoveredFile/DroppedFile拖放事件原生端文件路径通过 dropped_file.rs 的NativeFile延迟读取字节。2.3 平台输出回写handle_platform_output每一帧 egui 运行完后集成层调用handle_platform_output或带事件循环的handle_platform_output_with_event_loop把egui::PlatformOutput写回系统lib.rs包括OutputCommand::CopyText/CopyImage→ 写剪贴板OutputCommand::OpenUrl→ 打开浏览器依赖links特性光标更新cursor_icon与位图cursor_image后者需要ActiveEventLoop注册CustomCursor否则回退到标准图标路径IME 区域与用途同步window.set_ime_allowed、set_ime_purpose、set_ime_cursor_area并处理should_interrupt_composition时通过先禁后启的方式打断组合输入AccessKit 无障碍更新accesskit特性开启时。三、特性开关Feature Flags完全说明Cargo.toml中定义的特性开关如下默认特性为clipboard、links、wayland、winit/default、x11特性作用依赖default剪贴板 打开链接 Wayland/X11 winit 默认特性—accesskit通过 AccessKit 实现平台无障碍 APIaccesskit_winitandroid-game-activity/android-native-activity选择 Android 的android-activity后端经由 winitwinit/android-*bytemuck允许把egui::epaint::Vertex、egui::Vec2等转换为[u8]egui/bytemuck,bytemuckclipboard启用系统剪贴板复制/粘贴关闭时退化为仅应用内可用的模拟剪贴板arboard,bytemuck,smithay-clipboardlinks点击 egui 超链接时在浏览器中打开webbrowserserde允许WindowSettings的序列化窗口位置/大小持久化egui/serde,serdewaylandWayland 支持winit/wayland,bytemuckx11X11 支持winit/x11,bytemuck有几个值得注意的细节剪贴板是分平台实现的。clipboard特性在非 Android/iOS 平台启用arboard在 Linux/BSD 系列平台额外启用smithay-clipboardWayland 需要Android/iOS 上则刻意不启用arboard变更日志 0.33.2 明确记录了这一点。0.34.0 起还允许从 smithay 回退到 arboard 获取剪贴板。如果Clipboard::new初始化失败会退化为仅应用内的字符串剪贴板clipboard.rs。0.22.0 还修过Clipboard::new的不安全 API改为接收EventLoopWindowTargetT。0.20.0 引入wayland特性同时若egui-winit默认特性被关闭则winit的默认特性也不会被启用0.23.0 又允许用户彻底关闭 winit 默认特性。Android 后端选择权交给应用0.22.0 移除了android-activity直接依赖改为通过android-game-activity/android-native-activity两个特性让应用自行决定。四、剪贴板与快捷键从文本到图片egui-winit对剪贴板的封装位于 clipboard.rs提供文本与图片双向读写clipboard_text()/set_clipboard_text()文本读写clipboard_image()/set_image()图片读写依赖arboard的image-data见 Cargo.toml。0.26.0 起clipboard_text与allow_ime状态改为公开可访问。在键盘输入处理中lib.rsegui-winit会拦截剪贴板快捷键并把它们翻译成egui::Event::Cut/Copy/PasteCutmodifiers.command XWindows 下还有ShiftDeleteCopymodifiers.command CWindows 下还有CtrlInsertPastemodifiers.command VWindows 下还有ShiftInsert粘贴时若剪贴板无文本但有图片则发出egui::Event::PasteImage0.26.0不消费剪贴板快捷键的修复保证了这些快捷键能到达 egui 的处理逻辑。同时代码通过逻辑键 OR 物理键的兜底机制让非拉丁键盘布局下剪贴板快捷键仍能按物理键位触发对应 0.28.0 的非拉丁布局下发出物理按键事件与 0.28.0 的忽略合成按键改动。五、IME 输入法支持变更日志中最密集的演进线浏览整个 CHANGELOG.md输入法IME是投入改动最多、持续时间最长的主题从 0.23.0 到 0.36.1 几乎每个版本都有相关条目0.23.0仅在编辑文本时显示屏幕键盘与 IME0.28.0支持中文 IME#44360.29.0修复 IME 输入后退格键失效#49120.29.1 又因 X11 上退格/方向键问题暂时禁用 IME0.31.0 在 Linux 上重新启用 IME#51980.34.0大幅改进 IME#7967修复 macOS 原生与 Safari 上退格在 IME 预测中残留最后一个字符的问题#78100.35.0实现 IME 组合的视觉效果#8083并把 IME 中断处理委托给各集成层以修复 Web 端虚拟键盘闪烁#8078。从源码看 IME 的处理链路WindowEvent::Ime由on_ime翻译为egui::ImeEvent::Preedit与Commitlib.rs其中预编辑文本的激活区间从字节区间换算为字符区间并对 Windows 上韩文 IME 的游标位置 bug 做了规避。而 lib.rs 中 Windows 专属的try_on_ime_processed_keyboard_input记录了完整的 winit 0.30.12 缺陷规避方案通过检测NamedKey::Process对应VK_PROCESSKEY过滤被 IME 处理过的按键事件并用pressed_processed_physical_keys集合跟踪对应的按键释放从而保持与其他平台行为一致。此外handle_platform_output_inner会把 egui 的 IME 输出同步到窗口set_ime_allowed/set_ime_cursor_area/set_ime_purposeViewportCommand::IMERect、IMEAllowed、IMEPurpose也直接映射到 winit 窗口 API。六、多窗口Viewport与窗口管理命令0.24.0 起egui-winit经历了多 viewport 支持所需的破坏性变更此后版本围绕窗口管理持续增强0.24.1不把CloseRequested当作已消费事件修复 Linuxx11特性下的窗口问题0.32.0新增 macOS 专属的has_shadow/with_has_shadowViewportBuilder修复 Wayland 上不可调整大小窗口的尺寸错误应用失焦时标记所有按键为释放Android 支持返回键0.35.0新增ViewportBuilder::with_monitor与ViewportCommand::SetMonitor并用窗口与显示器重叠面积选择恢复窗口所属的显示器Windows 全屏时隐藏无装饰窗口的投影阴影0.36.2全屏时隐藏投影阴影装饰#8449。源码层面lib.rs 的process_viewport_commands把egui::ViewportCommand逐一映射到 winit 窗口 API包括窗口大小/位置、标题、透明度、可见性、最小/最大尺寸、可调整性、窗口按钮关闭/最小化/最大化、全屏SetMonitor使用指定显示器的 Borderless 全屏、窗口层级置顶/置底、图标、IME、焦点、用户注意力请求RequestUserAttention、光标抓取与可见性、鼠标穿透MousePassthrough等。窗口创建的辅助函数lib.rs包括create_window、create_winit_window_attributes、apply_viewport_builder_to_window与apply_monitor_to_window_attributes——后者是 Wayland 下唯一可靠地把窗口直接创建到指定显示器的方法避免 Mutter 在映射前忽略OuterPosition的竞态。glow 与 wgpu 后端均通过它们构建窗口。七、窗口状态持久化WindowSettingsWindowSettings用于保存并恢复原生窗口的位置与尺寸from_window采集窗口的内外位置物理像素、全屏/最大化状态与逻辑像素尺寸initialize_viewport_builder在重建窗口时应用这些设置并考虑 egui 缩放因子与显示器缩放macOS 用 inner position其他平台用 outer positionclamp_size_to_sane_values防止窗口过小下限 64px或大于最大显示器Linux 上过大窗口可能崩溃clamp_position_to_monitors在 Windows 上把窗口位置钳制回有效显示器区域修复 0.21.0 与 0.28.0 中窗口位置在多显示器/缩放显示器间漂移的持久化问题0.19.0 与 0.21.0 也分别修复过位置持久化与 Windows 位置持久化 bug。启用serde特性后WindowSettings可序列化配合 eframe 的持久化机制实现跨会话的窗口布局恢复。窗口恢复时按显示器重叠面积挑选显示器正是 0.35.0 的 #8191 改动。八、平台适配历程与安全区处理变更日志展示了清晰的多平台支持脉络Wayland/X110.20.0 新增wayland特性0.19.0 修复 Wayland 剪贴板0.27.2 修复 Wayland 上 TextEdit 聚焦或 IME 输出时的连续重绘问题0.32.0 修复 Wayland 非可调整窗口尺寸macOS0.17.0 修复enable_drag0.21.0 通过 winit 0.28 支持触控板缩放0.28.0 修复窗口位置在缩放显示器间漂移0.33.0 修复 eframe 窗口启动时未聚焦0.30.0 支持把 UI 放到灵动岛旁边iOSiOS0.33.0 支持安全区#7578。源码中 safe_area.rs 通过 objc2 读取UIWindowScene的safeAreaInsets在Resized、ScaleFactorChanged、Focused(true)、Occluded(false)时更新safe_area_insetslib.rs。该实现是 winit 0.31 原生Window::safe_area落地前的临时方案避免 UI 被灵动岛、刘海屏或摄像头模组遮挡Android0.22.0 移除android-activity直接依赖并引入后端特性0.19.0 支持延迟渲染与 surface 状态初始化0.32.0 修复 Android 文本输入与返回键支持Web (wasm32)0.22.0 支持 Wasm 目标0.17.0 用instant后替换为web_time见 0.23.0保证时间测量跨平台一致。九、无障碍AccessKit与其他辅助能力AccessKit0.20.0 引入可选的 AccessKit 集成实现平台无障碍 API0.30.0 移除了隐式的accesskit_winit特性#5316需要显式启用accesskit0.25.0 修复让 AccessKit 处理窗口事件#3733。源码中State::init_accesskit通过accesskit_winit::Adapter::with_event_loop_proxy建立适配器事件循环里收到的AccessKitActionRequest经on_accesskit_action_request注入 egui。滚动0.17.0 修复 Linux 水平滚动方向并让 Shift滚轮在所有平台水平滚动0.34.0 新增is_scrolling/is_smooth_scrolling工具函数0.28.0 识别小键盘回车/加/减号。触摸与手势simulate_touch_screen支持把鼠标输入模拟为触摸用于调试0.33.0 支持触控板来源的旋转手势。性能与工具0.18.0 引入puffin特性为关键路径打点0.33.0 修复启用 profiling 时的构建错误0.20.0 起仅移动窗口不重绘0.17.0 自动检测系统深色/浅色模式ThemeChanged事件更新system_theme。键盘修饰键0.27.0 起焦点变化时不再清空修饰键状态#4157而 0.32.0 改为失焦时释放所有按键#5743两者针对不同问题最终行为以 lib.rs 为准失焦时重置modifiers并在重新聚焦时由 winit 重新上报。十、版本演进时间线速览从 CHANGELOG.md 汇总关键里程碑版本日期关键变更0.15.02021-10-24首次独立发布此前属egui_glium0.16.02021-12-29新增EpiIntegration助手winit 0.260.17.02022-02-22系统明暗模式检测wasm 时间兼容水平滚动修复0.18.02022-04-30重导出 eguipuffin特性serde特性更名0.19.02022-08-20MSRV 1.61Wayland 剪贴板修复窗口位置持久化0.20.02022-12-08新增wayland特性AccessKit 可选集成0.21.02023-02-08winit 0.28mac 触控板缩放移除screen_reader特性0.22.02023-05-23支持 Wasm移除android-activity依赖剪贴板 API 安全化0.23.02023-09-27仅编辑文本时启用屏幕键盘/IMEweb_time可关闭 winit 默认特性0.24.02023-11-23MSRV 1.72多 viewport 破坏性变更0.25.02024-01-08winit 0.29AccessKit 处理窗口事件0.26.02024-02-05不消费剪贴板快捷键公开clipboard_text/allow_ime0.27.x2024-03依赖更新修饰键状态行为调整0.28.02024-07-03中文 IME物理键支持忽略合成按键0.29.x2024-09/10winit 0.30IME 修复含 X11 临时禁用/重启用0.30.02024-12-16iOS 灵动岛旁 UI移除隐式 accesskit 特性0.31.02025-02-04Linux 重新启用 IMEwinit 0.30.70.32.x2025-07/08失焦释放按键Android 修复macOS 阴影Wayland 尺寸修复winit 0.30.120.33.x2025-10/11iOS 安全区旋转手势MSRV 1.88iOS 不启用 arboard0.34.x2026-03/05IME 大幅改进滚动工具函数剪贴板回退0.35.02026-06-25IME 组合视觉with_monitor/SetMonitor全屏阴影处理0.36.x2026-08/09全屏隐藏无装饰窗口阴影值得注意的是egui-winit的 MSRV 随版本演进为 1.600.18.0→ 1.610.19.0→ 1.720.24.0→ 1.880.33.0当前 rust-version.workspace true 沿用工作区设定。十一、调试与日志辅助egui-winit提供两个便捷的日志/性能辅助函数short_window_event_description与short_device_event_descriptionlib.rs为每个 winit 事件返回静态字符串描述便于在事件循环外层做 profiling 打点或日志过滤。eframe的 run.rs 正是这样使用的。键盘映射相关的log::trace!输出logical → egui, physical → egui则用于排查按键识别问题。仓库根目录的 scripts/generate_changelog.py 是维护者生成各 crate CHANGELOG 的工具读者可用它复现本文件所述条目并对比latest...HEAD区间查看未发布的新改动。总结egui-winit虽然不直接参与 UI 渲染却是 egui 桌面与移动端体验的基石它负责把 winit 的事件流翻译成 egui 的输入语义把 egui 的输出命令执行到操作系统并围绕剪贴板、IME、多窗口、无障碍与各平台差异做了大量精细化工作。阅读 crates/egui-winit/CHANGELOG.md 可以看到一条清晰的主线——从基础窗口绑定到 IME 的中文支持与组合视觉、从单窗口到多 viewport 与多显示器选择、从桌面三平台到 iOS/Android/Web 的全平台覆盖。对于需要直接基于 winit 集成 egui 的开发者State、EventResponse、process_viewport_commands与各 feature 开关就是最核心的接入点。【免费下载链接】eguiegui: an easy-to-use immediate mode GUI in Rust that runs on both web and native项目地址: https://gitcode.com/GitHub_Trending/eg/egui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
egui-winit 集成层完全指南从 winit 事件到 egui 界面的桥梁与跨平台演进【免费下载链接】eguiegui: an easy-to-use immediate mode GUI in Rust that runs on both web and native项目地址: https://gitcode.com/GitHub_Trending/eg/eguiegui-winit是 egui 生态中负责把winit窗口系统的原生事件鼠标、键盘、触摸、IME、窗口生命周期等翻译成 egui 输入、并把 egui 输出剪贴板、光标、链接、窗口命令写回操作系统的集成层。本文以 crates/egui-winit/CHANGELOG.md 为主体骨架结合 crates/egui-winit/src/lib.rs 等源码与 crates/egui-winit/Cargo.toml 特性配置梳理该 crate 的核心职责、功能特性、平台适配演进与完整版本历史帮助你理解 egui 桌面端运行时的工作方式并掌握如何配置它的特性开关。一、egui-winit 在 egui 生态中的定位egui 本身是纯立即模式 GUI 库不直接接触操作系统窗口。在原生桌面端窗口的创建、事件循环和系统交互由winit提供而egui-winit就是连接两者的胶水层。从 crates/egui-winit/src/lib.rs 的 crate 级文档可以看到它的职责将 winit 事件翻译为 egui 事件处理复制/粘贴剪贴板更新光标打开 egui 中被点击的链接。在实际工程中eframe的各个原生后端glow/wgpu都依赖egui-winit。例如 crates/eframe/src/native/glow_integration.rs 与 crates/eframe/src/native/wgpu_integration.rs 中都用egui_winit::State::new(...)为每个窗口viewport创建集成状态。egui-winit于 0.15.0 版本首次独立发布此前是egui_glium的一部分自 0.15.0 至今其变更日志完整记录了该集成层围绕 IME、剪贴板、多窗口多 viewport、无障碍AccessKit以及各桌面与移动平台适配的演进历程。二、核心架构State 与事件双向翻译2.1 State每个窗口一份的集成状态State是egui-winit的核心结构体文档明确要求每个 viewport/window 实例化一个。它内部保存了egui_ctxegui 的共享Contextviewport_id当前窗口对应的视图 IDegui_input累积的egui::RawInputmodifiers当前修饰键状态用于给每个事件打上修饰键快照pointer_pos_in_points与any_pointer_button_down指针状态current_cursor_icon与current_custom_cursor光标缓存按Arc::as_ptr去重避免每帧重复上传位图光标clipboard剪贴板句柄allow_ime、ime_rect_px、old_ime_purposeIME 状态在 Windows 上还有pressed_processed_physical_keys用于过滤被 IME 处理过的按键释放事件。State::new接收egui_ctx、viewport_id、显示句柄、native_pixels_per_point、系统主题与max_texture_side并把这些初始信息写入egui_inputlib.rs。其中max_texture_side会在创建图形上下文后通过set_max_texture_side更新对应变更日志 0.17.0 中需要获知最大纹理边长如GL_MAX_TEXTURE_SIZE的改动。2.2 事件翻译on_window_eventState::on_window_event是事件入口lib.rs它把winit::event::WindowEvent逐一映射为 egui 事件并返回EventResponseconsumedegui 是否独占消费了该事件例如点击了 egui 窗口或正在输入文字。文档特别指出如果你用 egui 做游戏只有当consumed false时才应该把事件继续传给游戏逻辑Tab键永远为true因为 egui 用 Tab 在控件间移动焦点repaint该事件是否触发一次 egui 重绘。映射关系包括MouseInput→PointerButton、MouseWheel→MouseWheel区分LineDelta与PixelDelta两种单位、CursorMoved→PointerMoved、Touch→Touch同时把首个触摸模拟为指针、PinchGesture→Zoom、RotationGesture→Rotate、PanGesture→MouseWheel(Point)以及HoveredFile/DroppedFile拖放事件原生端文件路径通过 dropped_file.rs 的NativeFile延迟读取字节。2.3 平台输出回写handle_platform_output每一帧 egui 运行完后集成层调用handle_platform_output或带事件循环的handle_platform_output_with_event_loop把egui::PlatformOutput写回系统lib.rs包括OutputCommand::CopyText/CopyImage→ 写剪贴板OutputCommand::OpenUrl→ 打开浏览器依赖links特性光标更新cursor_icon与位图cursor_image后者需要ActiveEventLoop注册CustomCursor否则回退到标准图标路径IME 区域与用途同步window.set_ime_allowed、set_ime_purpose、set_ime_cursor_area并处理should_interrupt_composition时通过先禁后启的方式打断组合输入AccessKit 无障碍更新accesskit特性开启时。三、特性开关Feature Flags完全说明Cargo.toml中定义的特性开关如下默认特性为clipboard、links、wayland、winit/default、x11特性作用依赖default剪贴板 打开链接 Wayland/X11 winit 默认特性—accesskit通过 AccessKit 实现平台无障碍 APIaccesskit_winitandroid-game-activity/android-native-activity选择 Android 的android-activity后端经由 winitwinit/android-*bytemuck允许把egui::epaint::Vertex、egui::Vec2等转换为[u8]egui/bytemuck,bytemuckclipboard启用系统剪贴板复制/粘贴关闭时退化为仅应用内可用的模拟剪贴板arboard,bytemuck,smithay-clipboardlinks点击 egui 超链接时在浏览器中打开webbrowserserde允许WindowSettings的序列化窗口位置/大小持久化egui/serde,serdewaylandWayland 支持winit/wayland,bytemuckx11X11 支持winit/x11,bytemuck有几个值得注意的细节剪贴板是分平台实现的。clipboard特性在非 Android/iOS 平台启用arboard在 Linux/BSD 系列平台额外启用smithay-clipboardWayland 需要Android/iOS 上则刻意不启用arboard变更日志 0.33.2 明确记录了这一点。0.34.0 起还允许从 smithay 回退到 arboard 获取剪贴板。如果Clipboard::new初始化失败会退化为仅应用内的字符串剪贴板clipboard.rs。0.22.0 还修过Clipboard::new的不安全 API改为接收EventLoopWindowTargetT。0.20.0 引入wayland特性同时若egui-winit默认特性被关闭则winit的默认特性也不会被启用0.23.0 又允许用户彻底关闭 winit 默认特性。Android 后端选择权交给应用0.22.0 移除了android-activity直接依赖改为通过android-game-activity/android-native-activity两个特性让应用自行决定。四、剪贴板与快捷键从文本到图片egui-winit对剪贴板的封装位于 clipboard.rs提供文本与图片双向读写clipboard_text()/set_clipboard_text()文本读写clipboard_image()/set_image()图片读写依赖arboard的image-data见 Cargo.toml。0.26.0 起clipboard_text与allow_ime状态改为公开可访问。在键盘输入处理中lib.rsegui-winit会拦截剪贴板快捷键并把它们翻译成egui::Event::Cut/Copy/PasteCutmodifiers.command XWindows 下还有ShiftDeleteCopymodifiers.command CWindows 下还有CtrlInsertPastemodifiers.command VWindows 下还有ShiftInsert粘贴时若剪贴板无文本但有图片则发出egui::Event::PasteImage0.26.0不消费剪贴板快捷键的修复保证了这些快捷键能到达 egui 的处理逻辑。同时代码通过逻辑键 OR 物理键的兜底机制让非拉丁键盘布局下剪贴板快捷键仍能按物理键位触发对应 0.28.0 的非拉丁布局下发出物理按键事件与 0.28.0 的忽略合成按键改动。五、IME 输入法支持变更日志中最密集的演进线浏览整个 CHANGELOG.md输入法IME是投入改动最多、持续时间最长的主题从 0.23.0 到 0.36.1 几乎每个版本都有相关条目0.23.0仅在编辑文本时显示屏幕键盘与 IME0.28.0支持中文 IME#44360.29.0修复 IME 输入后退格键失效#49120.29.1 又因 X11 上退格/方向键问题暂时禁用 IME0.31.0 在 Linux 上重新启用 IME#51980.34.0大幅改进 IME#7967修复 macOS 原生与 Safari 上退格在 IME 预测中残留最后一个字符的问题#78100.35.0实现 IME 组合的视觉效果#8083并把 IME 中断处理委托给各集成层以修复 Web 端虚拟键盘闪烁#8078。从源码看 IME 的处理链路WindowEvent::Ime由on_ime翻译为egui::ImeEvent::Preedit与Commitlib.rs其中预编辑文本的激活区间从字节区间换算为字符区间并对 Windows 上韩文 IME 的游标位置 bug 做了规避。而 lib.rs 中 Windows 专属的try_on_ime_processed_keyboard_input记录了完整的 winit 0.30.12 缺陷规避方案通过检测NamedKey::Process对应VK_PROCESSKEY过滤被 IME 处理过的按键事件并用pressed_processed_physical_keys集合跟踪对应的按键释放从而保持与其他平台行为一致。此外handle_platform_output_inner会把 egui 的 IME 输出同步到窗口set_ime_allowed/set_ime_cursor_area/set_ime_purposeViewportCommand::IMERect、IMEAllowed、IMEPurpose也直接映射到 winit 窗口 API。六、多窗口Viewport与窗口管理命令0.24.0 起egui-winit经历了多 viewport 支持所需的破坏性变更此后版本围绕窗口管理持续增强0.24.1不把CloseRequested当作已消费事件修复 Linuxx11特性下的窗口问题0.32.0新增 macOS 专属的has_shadow/with_has_shadowViewportBuilder修复 Wayland 上不可调整大小窗口的尺寸错误应用失焦时标记所有按键为释放Android 支持返回键0.35.0新增ViewportBuilder::with_monitor与ViewportCommand::SetMonitor并用窗口与显示器重叠面积选择恢复窗口所属的显示器Windows 全屏时隐藏无装饰窗口的投影阴影0.36.2全屏时隐藏投影阴影装饰#8449。源码层面lib.rs 的process_viewport_commands把egui::ViewportCommand逐一映射到 winit 窗口 API包括窗口大小/位置、标题、透明度、可见性、最小/最大尺寸、可调整性、窗口按钮关闭/最小化/最大化、全屏SetMonitor使用指定显示器的 Borderless 全屏、窗口层级置顶/置底、图标、IME、焦点、用户注意力请求RequestUserAttention、光标抓取与可见性、鼠标穿透MousePassthrough等。窗口创建的辅助函数lib.rs包括create_window、create_winit_window_attributes、apply_viewport_builder_to_window与apply_monitor_to_window_attributes——后者是 Wayland 下唯一可靠地把窗口直接创建到指定显示器的方法避免 Mutter 在映射前忽略OuterPosition的竞态。glow 与 wgpu 后端均通过它们构建窗口。七、窗口状态持久化WindowSettingsWindowSettings用于保存并恢复原生窗口的位置与尺寸from_window采集窗口的内外位置物理像素、全屏/最大化状态与逻辑像素尺寸initialize_viewport_builder在重建窗口时应用这些设置并考虑 egui 缩放因子与显示器缩放macOS 用 inner position其他平台用 outer positionclamp_size_to_sane_values防止窗口过小下限 64px或大于最大显示器Linux 上过大窗口可能崩溃clamp_position_to_monitors在 Windows 上把窗口位置钳制回有效显示器区域修复 0.21.0 与 0.28.0 中窗口位置在多显示器/缩放显示器间漂移的持久化问题0.19.0 与 0.21.0 也分别修复过位置持久化与 Windows 位置持久化 bug。启用serde特性后WindowSettings可序列化配合 eframe 的持久化机制实现跨会话的窗口布局恢复。窗口恢复时按显示器重叠面积挑选显示器正是 0.35.0 的 #8191 改动。八、平台适配历程与安全区处理变更日志展示了清晰的多平台支持脉络Wayland/X110.20.0 新增wayland特性0.19.0 修复 Wayland 剪贴板0.27.2 修复 Wayland 上 TextEdit 聚焦或 IME 输出时的连续重绘问题0.32.0 修复 Wayland 非可调整窗口尺寸macOS0.17.0 修复enable_drag0.21.0 通过 winit 0.28 支持触控板缩放0.28.0 修复窗口位置在缩放显示器间漂移0.33.0 修复 eframe 窗口启动时未聚焦0.30.0 支持把 UI 放到灵动岛旁边iOSiOS0.33.0 支持安全区#7578。源码中 safe_area.rs 通过 objc2 读取UIWindowScene的safeAreaInsets在Resized、ScaleFactorChanged、Focused(true)、Occluded(false)时更新safe_area_insetslib.rs。该实现是 winit 0.31 原生Window::safe_area落地前的临时方案避免 UI 被灵动岛、刘海屏或摄像头模组遮挡Android0.22.0 移除android-activity直接依赖并引入后端特性0.19.0 支持延迟渲染与 surface 状态初始化0.32.0 修复 Android 文本输入与返回键支持Web (wasm32)0.22.0 支持 Wasm 目标0.17.0 用instant后替换为web_time见 0.23.0保证时间测量跨平台一致。九、无障碍AccessKit与其他辅助能力AccessKit0.20.0 引入可选的 AccessKit 集成实现平台无障碍 API0.30.0 移除了隐式的accesskit_winit特性#5316需要显式启用accesskit0.25.0 修复让 AccessKit 处理窗口事件#3733。源码中State::init_accesskit通过accesskit_winit::Adapter::with_event_loop_proxy建立适配器事件循环里收到的AccessKitActionRequest经on_accesskit_action_request注入 egui。滚动0.17.0 修复 Linux 水平滚动方向并让 Shift滚轮在所有平台水平滚动0.34.0 新增is_scrolling/is_smooth_scrolling工具函数0.28.0 识别小键盘回车/加/减号。触摸与手势simulate_touch_screen支持把鼠标输入模拟为触摸用于调试0.33.0 支持触控板来源的旋转手势。性能与工具0.18.0 引入puffin特性为关键路径打点0.33.0 修复启用 profiling 时的构建错误0.20.0 起仅移动窗口不重绘0.17.0 自动检测系统深色/浅色模式ThemeChanged事件更新system_theme。键盘修饰键0.27.0 起焦点变化时不再清空修饰键状态#4157而 0.32.0 改为失焦时释放所有按键#5743两者针对不同问题最终行为以 lib.rs 为准失焦时重置modifiers并在重新聚焦时由 winit 重新上报。十、版本演进时间线速览从 CHANGELOG.md 汇总关键里程碑版本日期关键变更0.15.02021-10-24首次独立发布此前属egui_glium0.16.02021-12-29新增EpiIntegration助手winit 0.260.17.02022-02-22系统明暗模式检测wasm 时间兼容水平滚动修复0.18.02022-04-30重导出 eguipuffin特性serde特性更名0.19.02022-08-20MSRV 1.61Wayland 剪贴板修复窗口位置持久化0.20.02022-12-08新增wayland特性AccessKit 可选集成0.21.02023-02-08winit 0.28mac 触控板缩放移除screen_reader特性0.22.02023-05-23支持 Wasm移除android-activity依赖剪贴板 API 安全化0.23.02023-09-27仅编辑文本时启用屏幕键盘/IMEweb_time可关闭 winit 默认特性0.24.02023-11-23MSRV 1.72多 viewport 破坏性变更0.25.02024-01-08winit 0.29AccessKit 处理窗口事件0.26.02024-02-05不消费剪贴板快捷键公开clipboard_text/allow_ime0.27.x2024-03依赖更新修饰键状态行为调整0.28.02024-07-03中文 IME物理键支持忽略合成按键0.29.x2024-09/10winit 0.30IME 修复含 X11 临时禁用/重启用0.30.02024-12-16iOS 灵动岛旁 UI移除隐式 accesskit 特性0.31.02025-02-04Linux 重新启用 IMEwinit 0.30.70.32.x2025-07/08失焦释放按键Android 修复macOS 阴影Wayland 尺寸修复winit 0.30.120.33.x2025-10/11iOS 安全区旋转手势MSRV 1.88iOS 不启用 arboard0.34.x2026-03/05IME 大幅改进滚动工具函数剪贴板回退0.35.02026-06-25IME 组合视觉with_monitor/SetMonitor全屏阴影处理0.36.x2026-08/09全屏隐藏无装饰窗口阴影值得注意的是egui-winit的 MSRV 随版本演进为 1.600.18.0→ 1.610.19.0→ 1.720.24.0→ 1.880.33.0当前 rust-version.workspace true 沿用工作区设定。十一、调试与日志辅助egui-winit提供两个便捷的日志/性能辅助函数short_window_event_description与short_device_event_descriptionlib.rs为每个 winit 事件返回静态字符串描述便于在事件循环外层做 profiling 打点或日志过滤。eframe的 run.rs 正是这样使用的。键盘映射相关的log::trace!输出logical → egui, physical → egui则用于排查按键识别问题。仓库根目录的 scripts/generate_changelog.py 是维护者生成各 crate CHANGELOG 的工具读者可用它复现本文件所述条目并对比latest...HEAD区间查看未发布的新改动。总结egui-winit虽然不直接参与 UI 渲染却是 egui 桌面与移动端体验的基石它负责把 winit 的事件流翻译成 egui 的输入语义把 egui 的输出命令执行到操作系统并围绕剪贴板、IME、多窗口、无障碍与各平台差异做了大量精细化工作。阅读 crates/egui-winit/CHANGELOG.md 可以看到一条清晰的主线——从基础窗口绑定到 IME 的中文支持与组合视觉、从单窗口到多 viewport 与多显示器选择、从桌面三平台到 iOS/Android/Web 的全平台覆盖。对于需要直接基于 winit 集成 egui 的开发者State、EventResponse、process_viewport_commands与各 feature 开关就是最核心的接入点。【免费下载链接】eguiegui: an easy-to-use immediate mode GUI in Rust that runs on both web and native项目地址: https://gitcode.com/GitHub_Trending/eg/egui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
