WezTerm 窗口级 Action 编程深入解析 window:perform_action 及其事件驱动用法【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwindow:perform_action(key_assignment, pane)是 WezTerm 为 Lua 脚本提供的一个核心能力它允许你在事件回调中以编程方式触发本应通过键盘或鼠标配置绑定的动作。本文基于 WezTerm 官方文档与仓库源码完整讲解该方法的签名、参数构造、底层调度原理并结合真实事件回调示例给出可直接落地的自定义快捷键与自动化方案。方法签名与语义window:perform_action自版本20201031-154415-9614e117起可用其调用形式为window:perform_action(key_assignment, pane)该方法的作用是针对传入的pane在window的上下文中执行一次键位分配key assignment动作。WezTerm 中有一系列可以通过keys与mouse配置选项绑定到窗口/面板的动作而本方法让 Lua 脚本能够自己触发这些动作相当于把按下一个绑定键这件事程序化。两个参数的职责key_assignment一个键位分配对象通常由wezterm.action构造返回。pane事件回调中传入的pane对象指定动作的作用目标。官方文档给出的经典用法示例位于wezterm.onCustom Events 一节即把perform_action与自定义事件、EmitEvent键位绑定组合使用。第一个参数如何构造 key_assignment使用 wezterm.action 构造器推荐从版本20220624-141144-bd1b7c5d起wezterm.action被实现为一种特殊的枚举构造器让动作表达比早期版本更符合直觉。索引一个合法的KeyAssignment名称即可作为该类型的构造函数local wezterm require wezterm local act wezterm.action -- 单元变体无参数直接引用即可求值为对应动作 -- 例如 act.Copy、act.ClearSelection -- 带默认参数的类型也可直接引用如 act.QuickSelectArgs -- 元组变体带位置参数通过调用构造器传入参数 act.ActivatePaneByIndex(0) act.ActivateTabRelative(-1)完整示例local wezterm require wezterm local act wezterm.action return { keys { { key , mods CTRL|SHIFT, action act.QuickSelectArgs }, { key , mods CTRL|SHIFT, action act.QuickSelectArgs { alphabet abc } }, { key F1, mods ALT, action act.ActivatePaneByIndex(0) }, { key F2, mods ALT, action act.ActivatePaneByIndex(1) }, { key {, mods CTRL, action act.ActivateTabRelative(-1) }, { key }, mods CTRL, action act.ActivateTabRelative(1) }, }, }早期版本的语法仍受支持在20220624-141144-bd1b7c5d之前的版本中语法为使用wezterm.action { ... }并传入一个以变体名为键的 Lua 表local wezterm require wezterm return { keys { { key {, mods CTRL, action wezterm.action { ActivateTabRelative -1 } }, { key }, mods CTRL, action wezterm.action { ActivateTabRelative 1 } }, }, }旧语法至今仍受支持无需急于迁移配置文件。KeyAssignment 的本质从底层看KeyAssignment是 Rust 代码中一个枚举类型每个变体对应 WezTerm 已知的一种动作。在 Lua 中该枚举表示为仅含一个键、键名为变体名的表格wezterm.action本质上只是底层 Lua→Rust 反序列化映射的语法糖作用是让配置文件中可能存在的语法错误更容易定位。完整的可用动作列表参见 KeyAssignment 枚举参考。第二个参数pane 对象从哪来pane参数通常是事件回调的第一个或第二个参数。wezterm.on注册的回调会收到两个参数一个window对象代表当前活动的 GUI 窗口一个pane对象代表当前活动面板。因此典型的写法是wezterm.on(some-event, function(window, pane) ... window:perform_action(act.xxx, pane) ... end)。实战perform_action 在自定义事件中的完整用法wezterm.on采用类似 HTML/JavaScript 的命名约定来定义事件处理器。同一个事件可以注册多个回调内部按注册顺序维护一个有序回调列表事件触发时依次调用若某回调返回false将阻止后续回调以及事件定义的默认动作执行。事件处理器无法单独注销但由于 Lua 状态在配置重载时会整体重建重载配置即可清空既有处理器。以下官方示例演示了核心组合拳绑定一个按键 →EmitEvent触发自定义事件 → 回调中使用pane读取内容 → 使用window:perform_action执行SpawnCommandInNewWindowlocal wezterm require wezterm local io require io local os require os local act wezterm.action wezterm.on(trigger-vim-with-scrollback, function(window, pane) -- 从 pane 读取文本取滚动回退区全部行 local text pane:get_lines_as_text(pane:get_dimensions().scrollback_rows) -- 写入临时文件交给 vim local name os.tmpname() local f io.open(name, w) f:write(text) f:flush() f:close() -- 用 perform_action 在新窗口中启动 vim 打开该文件 window:perform_action( act.SpawnCommandInNewWindow { args { vim, name }, }, pane ) -- 等待 vim 读文件后再删除临时文件。 -- 窗口创建与进程 spawn 相对脚本是异步且不可 await 的故取一个足够大的时间。 wezterm.sleep_ms(1000) os.remove(name) end) return { keys { { key E, mods CTRL, action act.EmitEvent trigger-vim-with-scrollback, }, }, }使用要点自定义事件名应尽量避免与 WezTerm 未来可能启用的内置事件名冲突以免产生意外行为window:perform_action完全复用配置中keys/mouse绑定的同一套动作机制因此任何可在配置中绑定的动作都能在此触发回调中pane的方法如get_lines_as_text、get_dimensions详见 pane API 文档。底层实现perform_action 是如何被执行的Lua 绑定层window:perform_action的绑定定义在 wezterm-gui/src/scripting/guiwin.rs。源码显示它是一个async 方法签名对应(assignment: KeyAssignment, pane: UserDataRefMuxPane)创建一个有界 channel(tx, rx)向窗口线程发送TermWindowNotif::PerformAssignment通知携带pane_id、assignment和应答 channeltx异步等待执行结果并返回。若执行出错错误会以mlua::Error::external的形式抛回 Lua 脚本。因此perform_action是异步执行的——这解释了官方示例中为何要用wezterm.sleep_ms(1000)等待新窗口与进程真正完成启动。窗口线程的调度TermWindowNotif::PerformAssignment在 wezterm-gui/src/termwindow/mod.rs 中被处理关键逻辑包括通过get_active_pane_or_overlay()解析当前活动面板由于 CopyMode 等 overlay 并不存在于 mux 中而是以被覆盖面板的pane_id自居因此这里会优先匹配 overlay、否则回退到 mux 中的面板对应 issue 3209 的处理随后调用perform_key_assignment真正执行动作完成后通过tx把结果回传给 Lua 侧并触发窗口重绘window.invalidate()。perform_key_assignment 的分发perform_key_assignmentwezterm-gui/src/termwindow/mod.rs的执行顺序是若存在 modal 层如复制模式、快速选择等 overlay先让 modal 尝试处理该动作再把动作交给pane.perform_assignment(assignment)pane 层默认实现见 mux/src/pane.rs若 pane 已处理则返回剩余动作由窗口层逐个匹配处理覆盖ActivateKeyTable、PopKeyTable、ClearKeyTableStack、Multiple可嵌套多个子动作顺序执行、SpawnTab、SpawnWindow、SpawnCommandInNewTab/NewWindow、SplitHorizontal/SplitVertical、ToggleFullScreen等一大批变体。这也意味着通过perform_action触发动作与真实按键绑定走的是同一条执行路径因此其行为包括 modal 拦截、面板层优先处理等与手动按键完全一致。适用范围与注意事项触发主体perform_action是window对象的方法只能在拿到 window 对象的事件回调如wezterm.on、window 事件中使用不能脱离窗口上下文调用动作目标pane参数决定了动作作用在哪个面板上传回回调收到的pane即可作用于触发事件的当前面板异步语义方法本身异步返回窗口创建/进程派生等动作无法被 await需要时须自行补偿等待动作覆盖面所有KeyAssignment变体都可用完整清单见 KeyAssignment 枚举参考对于尚未被文档覆盖的新增动作可以按wezterm.action的构造约定直接拼装 Lua 表来触发事件机制配合wezterm.on支持多回调与false短路返回值配合wezterm.emit或EmitEvent键位即可构建复杂的自定义命令体系。总结window:perform_action是 WezTerm Lua 编程中把键盘绑定程序化的关键桥梁wezterm.action负责构造动作对象wezterm.on提供事件入口perform_action负责把动作投递到与按键相同的执行管线窗口层 → pane 层 → modal/窗口动作分发。理解这条链路后你就可以把任意内置动作编织进自定义事件流实现诸如一键用 vim 打开整个回滚区这类超越默认快捷键配置的自动化能力。【免费下载链接】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 窗口级 Action 编程：深入解析 window:perform_action 及其事件驱动用法
WezTerm 窗口级 Action 编程深入解析 window:perform_action 及其事件驱动用法【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwindow:perform_action(key_assignment, pane)是 WezTerm 为 Lua 脚本提供的一个核心能力它允许你在事件回调中以编程方式触发本应通过键盘或鼠标配置绑定的动作。本文基于 WezTerm 官方文档与仓库源码完整讲解该方法的签名、参数构造、底层调度原理并结合真实事件回调示例给出可直接落地的自定义快捷键与自动化方案。方法签名与语义window:perform_action自版本20201031-154415-9614e117起可用其调用形式为window:perform_action(key_assignment, pane)该方法的作用是针对传入的pane在window的上下文中执行一次键位分配key assignment动作。WezTerm 中有一系列可以通过keys与mouse配置选项绑定到窗口/面板的动作而本方法让 Lua 脚本能够自己触发这些动作相当于把按下一个绑定键这件事程序化。两个参数的职责key_assignment一个键位分配对象通常由wezterm.action构造返回。pane事件回调中传入的pane对象指定动作的作用目标。官方文档给出的经典用法示例位于wezterm.onCustom Events 一节即把perform_action与自定义事件、EmitEvent键位绑定组合使用。第一个参数如何构造 key_assignment使用 wezterm.action 构造器推荐从版本20220624-141144-bd1b7c5d起wezterm.action被实现为一种特殊的枚举构造器让动作表达比早期版本更符合直觉。索引一个合法的KeyAssignment名称即可作为该类型的构造函数local wezterm require wezterm local act wezterm.action -- 单元变体无参数直接引用即可求值为对应动作 -- 例如 act.Copy、act.ClearSelection -- 带默认参数的类型也可直接引用如 act.QuickSelectArgs -- 元组变体带位置参数通过调用构造器传入参数 act.ActivatePaneByIndex(0) act.ActivateTabRelative(-1)完整示例local wezterm require wezterm local act wezterm.action return { keys { { key , mods CTRL|SHIFT, action act.QuickSelectArgs }, { key , mods CTRL|SHIFT, action act.QuickSelectArgs { alphabet abc } }, { key F1, mods ALT, action act.ActivatePaneByIndex(0) }, { key F2, mods ALT, action act.ActivatePaneByIndex(1) }, { key {, mods CTRL, action act.ActivateTabRelative(-1) }, { key }, mods CTRL, action act.ActivateTabRelative(1) }, }, }早期版本的语法仍受支持在20220624-141144-bd1b7c5d之前的版本中语法为使用wezterm.action { ... }并传入一个以变体名为键的 Lua 表local wezterm require wezterm return { keys { { key {, mods CTRL, action wezterm.action { ActivateTabRelative -1 } }, { key }, mods CTRL, action wezterm.action { ActivateTabRelative 1 } }, }, }旧语法至今仍受支持无需急于迁移配置文件。KeyAssignment 的本质从底层看KeyAssignment是 Rust 代码中一个枚举类型每个变体对应 WezTerm 已知的一种动作。在 Lua 中该枚举表示为仅含一个键、键名为变体名的表格wezterm.action本质上只是底层 Lua→Rust 反序列化映射的语法糖作用是让配置文件中可能存在的语法错误更容易定位。完整的可用动作列表参见 KeyAssignment 枚举参考。第二个参数pane 对象从哪来pane参数通常是事件回调的第一个或第二个参数。wezterm.on注册的回调会收到两个参数一个window对象代表当前活动的 GUI 窗口一个pane对象代表当前活动面板。因此典型的写法是wezterm.on(some-event, function(window, pane) ... window:perform_action(act.xxx, pane) ... end)。实战perform_action 在自定义事件中的完整用法wezterm.on采用类似 HTML/JavaScript 的命名约定来定义事件处理器。同一个事件可以注册多个回调内部按注册顺序维护一个有序回调列表事件触发时依次调用若某回调返回false将阻止后续回调以及事件定义的默认动作执行。事件处理器无法单独注销但由于 Lua 状态在配置重载时会整体重建重载配置即可清空既有处理器。以下官方示例演示了核心组合拳绑定一个按键 →EmitEvent触发自定义事件 → 回调中使用pane读取内容 → 使用window:perform_action执行SpawnCommandInNewWindowlocal wezterm require wezterm local io require io local os require os local act wezterm.action wezterm.on(trigger-vim-with-scrollback, function(window, pane) -- 从 pane 读取文本取滚动回退区全部行 local text pane:get_lines_as_text(pane:get_dimensions().scrollback_rows) -- 写入临时文件交给 vim local name os.tmpname() local f io.open(name, w) f:write(text) f:flush() f:close() -- 用 perform_action 在新窗口中启动 vim 打开该文件 window:perform_action( act.SpawnCommandInNewWindow { args { vim, name }, }, pane ) -- 等待 vim 读文件后再删除临时文件。 -- 窗口创建与进程 spawn 相对脚本是异步且不可 await 的故取一个足够大的时间。 wezterm.sleep_ms(1000) os.remove(name) end) return { keys { { key E, mods CTRL, action act.EmitEvent trigger-vim-with-scrollback, }, }, }使用要点自定义事件名应尽量避免与 WezTerm 未来可能启用的内置事件名冲突以免产生意外行为window:perform_action完全复用配置中keys/mouse绑定的同一套动作机制因此任何可在配置中绑定的动作都能在此触发回调中pane的方法如get_lines_as_text、get_dimensions详见 pane API 文档。底层实现perform_action 是如何被执行的Lua 绑定层window:perform_action的绑定定义在 wezterm-gui/src/scripting/guiwin.rs。源码显示它是一个async 方法签名对应(assignment: KeyAssignment, pane: UserDataRefMuxPane)创建一个有界 channel(tx, rx)向窗口线程发送TermWindowNotif::PerformAssignment通知携带pane_id、assignment和应答 channeltx异步等待执行结果并返回。若执行出错错误会以mlua::Error::external的形式抛回 Lua 脚本。因此perform_action是异步执行的——这解释了官方示例中为何要用wezterm.sleep_ms(1000)等待新窗口与进程真正完成启动。窗口线程的调度TermWindowNotif::PerformAssignment在 wezterm-gui/src/termwindow/mod.rs 中被处理关键逻辑包括通过get_active_pane_or_overlay()解析当前活动面板由于 CopyMode 等 overlay 并不存在于 mux 中而是以被覆盖面板的pane_id自居因此这里会优先匹配 overlay、否则回退到 mux 中的面板对应 issue 3209 的处理随后调用perform_key_assignment真正执行动作完成后通过tx把结果回传给 Lua 侧并触发窗口重绘window.invalidate()。perform_key_assignment 的分发perform_key_assignmentwezterm-gui/src/termwindow/mod.rs的执行顺序是若存在 modal 层如复制模式、快速选择等 overlay先让 modal 尝试处理该动作再把动作交给pane.perform_assignment(assignment)pane 层默认实现见 mux/src/pane.rs若 pane 已处理则返回剩余动作由窗口层逐个匹配处理覆盖ActivateKeyTable、PopKeyTable、ClearKeyTableStack、Multiple可嵌套多个子动作顺序执行、SpawnTab、SpawnWindow、SpawnCommandInNewTab/NewWindow、SplitHorizontal/SplitVertical、ToggleFullScreen等一大批变体。这也意味着通过perform_action触发动作与真实按键绑定走的是同一条执行路径因此其行为包括 modal 拦截、面板层优先处理等与手动按键完全一致。适用范围与注意事项触发主体perform_action是window对象的方法只能在拿到 window 对象的事件回调如wezterm.on、window 事件中使用不能脱离窗口上下文调用动作目标pane参数决定了动作作用在哪个面板上传回回调收到的pane即可作用于触发事件的当前面板异步语义方法本身异步返回窗口创建/进程派生等动作无法被 await需要时须自行补偿等待动作覆盖面所有KeyAssignment变体都可用完整清单见 KeyAssignment 枚举参考对于尚未被文档覆盖的新增动作可以按wezterm.action的构造约定直接拼装 Lua 表来触发事件机制配合wezterm.on支持多回调与false短路返回值配合wezterm.emit或EmitEvent键位即可构建复杂的自定义命令体系。总结window:perform_action是 WezTerm Lua 编程中把键盘绑定程序化的关键桥梁wezterm.action负责构造动作对象wezterm.on提供事件入口perform_action负责把动作投递到与按键相同的执行管线窗口层 → pane 层 → modal/窗口动作分发。理解这条链路后你就可以把任意内置动作编织进自定义事件流实现诸如一键用 vim 打开整个回滚区这类超越默认快捷键配置的自动化能力。【免费下载链接】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），仅供参考
