 遍历与管理多路复用窗口)
WezTerm Lua API 实战wezterm.mux.all_windows() 遍历与管理多路复用窗口【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读wezterm.mux.all_windows()是 WezTerm 多路复用层mux暴露给 Lua 配置的核心 API 之一用于一次性获取当前会话中所有已知的 MuxWindow 对象。它常被用于启动脚本gui-startup/gui-attached事件或键盘快捷键处理器中实现批量操作窗口——例如启动时最大化所有窗口、统一设置窗口标题、按工作区workspace筛选窗口并施加布局。读完本文你将掌握该 API 的返回值结构、底层实现原理以及结合MuxWindow方法、workspace 机制编写实战配置的能力。一、函数签名与基本语义wezterm.mux.all_windows()于版本20220807-113146-c2fee766引入其签名与用途如下wezterm.mux.all_windows()返回值一个数组表array table其中每个元素都是一个MuxWindow对象代表多路复用器当前已知的每一个窗口。窗口的列举不区分所在 workspace——无论窗口属于默认工作区还是自定义工作区都会出现在返回表中。文档原文定义见 all_windows.md对象类型定义见 MuxWindow 对象。在使用前需要在配置文件中取得mux模块的引用惯用写法与 wezterm.mux 模块说明 中给出的一致local wezterm require wezterm local mux wezterm.mux随后即可在事件回调、快捷键处理函数等任何合适的作用域中调用local windows mux.all_windows() for _, window in ipairs(windows) do print(found window: .. window:window_id()) end二、源码级解析从 Lua 调用到 Mux 核心all_windows的 Lua 绑定实现在 lua-api-crates/mux/src/lib.rs这段 Rust 代码完整展示了Lua 表 ← Rust 向量 ← 全局 Mux 注册表的数据流mux_mod.set( all_windows, lua.create_function(|_, _: ()| { let mux get_mux()?; Ok(mux .iter_windows() .into_iter() .map(MuxWindow) .collect::VecMuxWindow()) })?, )?;其执行步骤可以拆解为通过Mux::try_get()即get_mux()拿到全局唯一的多路复用器句柄若当前进程没有可用的 Mux 实例则直接返回 Lua 错误cannot get Mux!?——这提示我们该 API 只在 WezTerm 运行时环境中可用脱离终端进程的纯脚本环境无法调用。调用mux.iter_windows()获取全部窗口 ID 列表。将每个WindowId包装为MuxWindow(window_id)结构体收集成VecMuxWindow最后由 mlua 自动转换为 Lua 数组表返回。底层的iter_windows()定义在 mux/src/lib.rs它是对 Mux 内部windows哈希表键集合的一次只读快照pub fn iter_windows(self) - VecWindowId { self.windows.read().keys().cloned().collect() }值得注意的是MuxWindow是#[derive(Clone, Copy, Debug)]的轻量包装类型见 lua-api-crates/mux/src/window.rs本身只携带WindowId真正的Window数据仍保存在 Mux 中。因此all_windows()返回的对象在 Lua 侧是句柄而非快照副本——你拿到的是指向多路复用器内实际窗口的引用后续调用其方法时仍会实时解析到最新的窗口状态例如活跃标签页的变化。三、理解返回对象MuxWindow 的核心方法all_windows()的价值体现在返回的MuxWindow对象上。在 lua-api-crates/mux/src/window.rs 中该对象通过UserDatatrait 注册了以下方法实战中常用方法类型说明window:window_id()同步返回窗口的数字 ID即WindowIdwindow:get_workspace()同步返回该窗口所属 workspace 的名称window:set_workspace(name)同步将窗口移动到指定 workspacewindow:get_title()/window:set_title(title)同步读取 / 设置窗口标题window:tabs()同步返回该窗口内的MuxTab对象数组window:tabs_with_info()同步返回带index、is_active等信息的标签页表window:active_tab()同步返回当前活跃标签页的MuxTab无则返回 nilwindow:active_pane()同步返回当前活跃窗格的MuxPane无则返回 nilwindow:spawn_tab(...)异步在该窗口中创建新标签页window:gui_window()异步获取对应的 GUI 窗口对象GuiWindow进而可调用maximize()、set_position()等图形层方法其中gui_window()的实现采用运行时模块解析——mux crate 不直接依赖 wezterm-gui而是通过 Lua 模块wezterm.gui.gui_window_for_mux_window间接调用见 lua-api-crates/mux/src/window.rs这也是window:gui_window()被标记为 async 方法、在纯 headless 的 mux-server 进程中不可用的原因。如果要在无 GUI 的复用器上下文中获取窗口信息应优先使用get_title()、tabs()等方法。四、实战示例4.1 启动时最大化所有窗口all_windows()最典型的应用是配合gui-attached事件在 GUI 启动后批量调整窗口。完整可运行的配置示例见 gui-attached 事件文档local wezterm require wezterm local mux wezterm.mux wezterm.on(gui-attached, function(domain) -- 启动时将当前 workspace 的所有窗口最大化 local workspace mux.get_active_workspace() for _, window in ipairs(mux.all_windows()) do if window:get_workspace() workspace then window:gui_window():maximize() end end end) local config wezterm.config_builder() return config这个例子展示了all_windows()与 workspace 过滤的经典组合mux.get_active_workspace()拿到当前工作区名称遍历全部窗口后用window:get_workspace()比对筛选只对属于当前工作区的窗口调用gui_window():maximize()。4.2 在 gui-startup 中批量设置窗口标题gui-startup事件是另一个适合使用all_windows()的入口参见 gui-startup 事件文档。例如遍历所有窗口并统一设置标题local wezterm require wezterm local mux wezterm.mux wezterm.on(gui-startup, function(cmd) local windows mux.all_windows() for _, window in ipairs(windows) do if window:get_title() then window:set_title(wezterm) end end end)4.3 按工作区统计与操作窗口结合 workspace 相关 APImux.get_workspace_names()、mux.get_active_workspace()、mux.set_active_workspace()分别见 get_workspace_names.md、get_active_workspace.md可以实现跨工作区的批量管理例如将某个工作区下的所有窗口移动合并local function merge_workspace_into(target) for _, window in ipairs(mux.all_windows()) do if window:get_workspace() ~ target then window:set_workspace(target) end end end4.4 与其他 mux 查询 API 配合all_windows()与mux.get_window(window_id)是互补的两种取窗口方式前者做全量遍历后者按 ID 精确取用见 get_window.md。例如来自wezterm cli list或其他外部来源的窗口 ID可以直接用get_window解析为对象再调用相同的方法集local win mux.get_window(win_id_from_cli) if win then print(title: .. win:get_title()) end五、重要注意事项不要在配置文件顶层作用域调用会创建新 split / tab / window 的 mux 函数。配置文件可能在多种上下文中被多次求值顶层副作用会导致重复创建。如需在启动时生成窗口务必把逻辑放进gui-startupGUI 启动后触发或mux-startup无 GUI 复用器启动后触发事件回调中。all_windows()本身是只读查询在顶层调用虽不产生副作用但最佳实践仍是在事件回调或快捷键处理函数中使用。GUI 相关方法有运行环境限制。window:gui_window()依赖运行时解析 GUI 模块在 headless 的 mux-server 或纯 CLI 上下文中不可用此时应改用get_title()、get_workspace()、tabs()等不依赖图形栈的方法。这从侧面印证了 wezterm.mux 模块说明 中复用器可能未连接 GUI某些需要窗口管理系统才能执行的操作不会出现在该模块接口中的约束。返回表是运行时快照。all_windows()在调用瞬间对 Mux 的窗口注册表做一次收集之后新建或关闭窗口不会自动反映到已有的 Lua 表变量中如需最新状态应在事件发生时重新调用。与quit_when_all_windows_are_closed的联动WezTerm 提供quit_when_all_windows_are_closed true配置见 quit_when_all_windows_are_closed.md控制所有窗口关闭后是否退出进程。结合all_windows()可以在窗口层面自主决定程序的存续逻辑实现更精细的窗口生命周期管理。六、相关 API 速查wezterm.mux.all_domains()返回所有 mux domainwezterm.mux.get_window(WINDOW_ID)按 ID 获取单个窗口wezterm.mux.get_tab(TAB_ID) / wezterm.mux.get_pane(PANE_ID)按 ID 获取标签页 / 窗格MuxWindow 对象完整方法列表gui-attached 事件 / gui-startup 事件all_windows()的主要挂载点【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
WezTerm Lua API 实战：wezterm.mux.all_windows() 遍历与管理多路复用窗口
WezTerm Lua API 实战wezterm.mux.all_windows() 遍历与管理多路复用窗口【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读wezterm.mux.all_windows()是 WezTerm 多路复用层mux暴露给 Lua 配置的核心 API 之一用于一次性获取当前会话中所有已知的 MuxWindow 对象。它常被用于启动脚本gui-startup/gui-attached事件或键盘快捷键处理器中实现批量操作窗口——例如启动时最大化所有窗口、统一设置窗口标题、按工作区workspace筛选窗口并施加布局。读完本文你将掌握该 API 的返回值结构、底层实现原理以及结合MuxWindow方法、workspace 机制编写实战配置的能力。一、函数签名与基本语义wezterm.mux.all_windows()于版本20220807-113146-c2fee766引入其签名与用途如下wezterm.mux.all_windows()返回值一个数组表array table其中每个元素都是一个MuxWindow对象代表多路复用器当前已知的每一个窗口。窗口的列举不区分所在 workspace——无论窗口属于默认工作区还是自定义工作区都会出现在返回表中。文档原文定义见 all_windows.md对象类型定义见 MuxWindow 对象。在使用前需要在配置文件中取得mux模块的引用惯用写法与 wezterm.mux 模块说明 中给出的一致local wezterm require wezterm local mux wezterm.mux随后即可在事件回调、快捷键处理函数等任何合适的作用域中调用local windows mux.all_windows() for _, window in ipairs(windows) do print(found window: .. window:window_id()) end二、源码级解析从 Lua 调用到 Mux 核心all_windows的 Lua 绑定实现在 lua-api-crates/mux/src/lib.rs这段 Rust 代码完整展示了Lua 表 ← Rust 向量 ← 全局 Mux 注册表的数据流mux_mod.set( all_windows, lua.create_function(|_, _: ()| { let mux get_mux()?; Ok(mux .iter_windows() .into_iter() .map(MuxWindow) .collect::VecMuxWindow()) })?, )?;其执行步骤可以拆解为通过Mux::try_get()即get_mux()拿到全局唯一的多路复用器句柄若当前进程没有可用的 Mux 实例则直接返回 Lua 错误cannot get Mux!?——这提示我们该 API 只在 WezTerm 运行时环境中可用脱离终端进程的纯脚本环境无法调用。调用mux.iter_windows()获取全部窗口 ID 列表。将每个WindowId包装为MuxWindow(window_id)结构体收集成VecMuxWindow最后由 mlua 自动转换为 Lua 数组表返回。底层的iter_windows()定义在 mux/src/lib.rs它是对 Mux 内部windows哈希表键集合的一次只读快照pub fn iter_windows(self) - VecWindowId { self.windows.read().keys().cloned().collect() }值得注意的是MuxWindow是#[derive(Clone, Copy, Debug)]的轻量包装类型见 lua-api-crates/mux/src/window.rs本身只携带WindowId真正的Window数据仍保存在 Mux 中。因此all_windows()返回的对象在 Lua 侧是句柄而非快照副本——你拿到的是指向多路复用器内实际窗口的引用后续调用其方法时仍会实时解析到最新的窗口状态例如活跃标签页的变化。三、理解返回对象MuxWindow 的核心方法all_windows()的价值体现在返回的MuxWindow对象上。在 lua-api-crates/mux/src/window.rs 中该对象通过UserDatatrait 注册了以下方法实战中常用方法类型说明window:window_id()同步返回窗口的数字 ID即WindowIdwindow:get_workspace()同步返回该窗口所属 workspace 的名称window:set_workspace(name)同步将窗口移动到指定 workspacewindow:get_title()/window:set_title(title)同步读取 / 设置窗口标题window:tabs()同步返回该窗口内的MuxTab对象数组window:tabs_with_info()同步返回带index、is_active等信息的标签页表window:active_tab()同步返回当前活跃标签页的MuxTab无则返回 nilwindow:active_pane()同步返回当前活跃窗格的MuxPane无则返回 nilwindow:spawn_tab(...)异步在该窗口中创建新标签页window:gui_window()异步获取对应的 GUI 窗口对象GuiWindow进而可调用maximize()、set_position()等图形层方法其中gui_window()的实现采用运行时模块解析——mux crate 不直接依赖 wezterm-gui而是通过 Lua 模块wezterm.gui.gui_window_for_mux_window间接调用见 lua-api-crates/mux/src/window.rs这也是window:gui_window()被标记为 async 方法、在纯 headless 的 mux-server 进程中不可用的原因。如果要在无 GUI 的复用器上下文中获取窗口信息应优先使用get_title()、tabs()等方法。四、实战示例4.1 启动时最大化所有窗口all_windows()最典型的应用是配合gui-attached事件在 GUI 启动后批量调整窗口。完整可运行的配置示例见 gui-attached 事件文档local wezterm require wezterm local mux wezterm.mux wezterm.on(gui-attached, function(domain) -- 启动时将当前 workspace 的所有窗口最大化 local workspace mux.get_active_workspace() for _, window in ipairs(mux.all_windows()) do if window:get_workspace() workspace then window:gui_window():maximize() end end end) local config wezterm.config_builder() return config这个例子展示了all_windows()与 workspace 过滤的经典组合mux.get_active_workspace()拿到当前工作区名称遍历全部窗口后用window:get_workspace()比对筛选只对属于当前工作区的窗口调用gui_window():maximize()。4.2 在 gui-startup 中批量设置窗口标题gui-startup事件是另一个适合使用all_windows()的入口参见 gui-startup 事件文档。例如遍历所有窗口并统一设置标题local wezterm require wezterm local mux wezterm.mux wezterm.on(gui-startup, function(cmd) local windows mux.all_windows() for _, window in ipairs(windows) do if window:get_title() then window:set_title(wezterm) end end end)4.3 按工作区统计与操作窗口结合 workspace 相关 APImux.get_workspace_names()、mux.get_active_workspace()、mux.set_active_workspace()分别见 get_workspace_names.md、get_active_workspace.md可以实现跨工作区的批量管理例如将某个工作区下的所有窗口移动合并local function merge_workspace_into(target) for _, window in ipairs(mux.all_windows()) do if window:get_workspace() ~ target then window:set_workspace(target) end end end4.4 与其他 mux 查询 API 配合all_windows()与mux.get_window(window_id)是互补的两种取窗口方式前者做全量遍历后者按 ID 精确取用见 get_window.md。例如来自wezterm cli list或其他外部来源的窗口 ID可以直接用get_window解析为对象再调用相同的方法集local win mux.get_window(win_id_from_cli) if win then print(title: .. win:get_title()) end五、重要注意事项不要在配置文件顶层作用域调用会创建新 split / tab / window 的 mux 函数。配置文件可能在多种上下文中被多次求值顶层副作用会导致重复创建。如需在启动时生成窗口务必把逻辑放进gui-startupGUI 启动后触发或mux-startup无 GUI 复用器启动后触发事件回调中。all_windows()本身是只读查询在顶层调用虽不产生副作用但最佳实践仍是在事件回调或快捷键处理函数中使用。GUI 相关方法有运行环境限制。window:gui_window()依赖运行时解析 GUI 模块在 headless 的 mux-server 或纯 CLI 上下文中不可用此时应改用get_title()、get_workspace()、tabs()等不依赖图形栈的方法。这从侧面印证了 wezterm.mux 模块说明 中复用器可能未连接 GUI某些需要窗口管理系统才能执行的操作不会出现在该模块接口中的约束。返回表是运行时快照。all_windows()在调用瞬间对 Mux 的窗口注册表做一次收集之后新建或关闭窗口不会自动反映到已有的 Lua 表变量中如需最新状态应在事件发生时重新调用。与quit_when_all_windows_are_closed的联动WezTerm 提供quit_when_all_windows_are_closed true配置见 quit_when_all_windows_are_closed.md控制所有窗口关闭后是否退出进程。结合all_windows()可以在窗口层面自主决定程序的存续逻辑实现更精细的窗口生命周期管理。六、相关 API 速查wezterm.mux.all_domains()返回所有 mux domainwezterm.mux.get_window(WINDOW_ID)按 ID 获取单个窗口wezterm.mux.get_tab(TAB_ID) / wezterm.mux.get_pane(PANE_ID)按 ID 获取标签页 / 窗格MuxWindow 对象完整方法列表gui-attached 事件 / gui-startup 事件all_windows()的主要挂载点【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
