WezTerm SendKey 动作深度指南按键重绑定与跨平台快捷键适配【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读SendKey是 WezTerm 提供的一个键盘动作KeyAssignment它允许将某个按键组合**原样转发re-emit**到当前窗格pane实现“把一个按键的效果改写成另一个按键”的按键重绑定。本文以其官方文档为基础结合仓库源码config/src/keyassignment.rs、config/src/keys.rs、wezterm-gui/src/termwindow/mod.rs讲解其核心语义、配置方式与典型实战场景如 macOS 下复刻 Terminal.app 的光标词级跳转并说明它与 Multiple 的组合用法。一、SendKey是什么核心语义与设计意图SendKey自 WezTerm 20211204-082213-a66c61ee9 版本起引入定义在 config/src/keyassignment.rs 的KeyAssignment枚举中SendKey(KeyNoAction),其官方文档给出的核心语义是将指定的按键按压事件发送给当前窗格pane。这对于重绑定某个按键组合的效果非常有用。这里需要特别澄清一个容易混淆的点重绑定效果只在“将要发送给窗格的输入”这一层生效被改写出的按键不会再次经过 WezTerm 的按键映射表去重新求值。也就是说SendKey是在键映射解析完成之后、向终端程序注入输入之前的“最后一道改写”不存在无限递归的二次映射问题。从实现上看wezterm-gui/src/termwindow/mod.rs 中SendKey的处理分支清晰地印证了这一语义SendKey(key) { use keyevent::Key; let mods key.mods; if let Key::Code(key) self.win_key_code_to_termwiz_key_code( key.key.resolve(self.config.key_map_preference), ) { pane.key_down(key, mods)?; } }可以看到处理流程是取出KeyNoAction中声明的按键码key.key与修饰键key.mods经key_map_preference决定使用物理键位还是映射键位解析最终直接调用窗格的pane.key_down(key, mods)将这一“按键按压”事件注入终端。这本质上等价于“把指定的按键当作你亲手按下”。与之形成对照的是SendStringwezterm-gui/src/termwindow/mod.rs它直接向窗格写入一串文本字节而SendKey注入的是结构化的按键事件交给终端程序自行解析为字符或控制序列。在命令面板Command Palette中SendKey也被登记为一条可搜索命令描述为 Sends {key} to the active pane, as though you typed it见 wezterm-gui/src/commands.rs。二、配置结构KeyNoAction的两个字段SendKey动作携带的数据结构是KeyNoAction定义于 config/src/keys.rs#[derive(Debug, Clone, PartialEq, Eq, FromDynamic, ToDynamic)] pub struct KeyNoAction { pub key: DeferredKeyCode, #[dynamic(default)] pub mods: Modifiers, }字段类型说明keyDeferredKeyCode要发送的按键码必填支持普通键名也支持phys:、mapped:、raw:前缀精确指定物理/映射/原始键码modsModifiers要发送的修饰键组合可省略默认无修饰键2.1key的取值形态DeferredKeyCodeconfig/src/keys.rs支持以下几种写法普通键名如b、f、LeftArrow、UpArrow、Enter等解析时同时匹配 mapped 与 phys 两套键位phys:前缀显式指定物理键码例如phys:US.B不随键盘布局/映射变化mapped:前缀显式指定映射后的键码raw:前缀指定操作系统层面的原始键码数字如raw:56。默认情况下KeyMapPreference::Mapped见 config/src/keys.rs不带前缀的键名按映射键位解析开发者也可以在配置中使用key_map_preference Physical切换为物理键位优先。2.2mods的取值mods支持常见的修饰键名称可组合CTRL、ALTmacOS 上即 Option、SHIFT、SUPERWindows 的 Win / macOS 的 Cmd、CMDmacOS 上SUPER的别名、MEHCTRLALTSHIFT的组合、以及LEADER配合 Leader 键使用。组合多个修饰键时使用|连接例如CTRL|SHIFT。三、实战场景macOS 下复刻 Terminal.app 的 Option 方向键行为SendKey最典型的应用案例来自 macOS 用户在 Terminal.app 中OptionLeftArrow/OptionRightArrow会被映射为ALT-b/ALT-f从而让大多数 Unix shell 和编辑器bash、zsh、readline、vim 等实现按词word前后移动光标。WezTerm 默认不进行这项改写因此文档给出了完整配置local act wezterm.action config.keys { -- Rebind OPT-Left, OPT-Right as ALT-b, ALT-f respectively to match Terminal.app behavior { key LeftArrow, mods OPT, action act.SendKey { key b, mods ALT, }, }, { key RightArrow, mods OPT, action act.SendKey { key f, mods ALT }, }, }这份配置的语义是当用户按下OptionLeftArrow时WezTerm 并不直接把该按键交给终端而是改写成一次Altb的按键事件注入当前窗格readline 类的行编辑库收到ALT-b后即执行“光标后退一个单词”。同理OptionRightArrow被改写为ALT-f触发“光标前进一个单词”。该示例同时展示了SendKey的两个典型应用特征入参组合与出参组合可以不同源按键是OPT修饰的方向键目标按键是ALT修饰的字母键目标按键无需绑定任何动作改写后的ALT-b不要求你在config.keys中预先定义它直接以普通按键的身份进入终端程序的处理逻辑。除了这个经典案例SendKey还可用于统一跨平台快捷键习惯例如在 Windows / Linux 上把SUPERLeftArrow等系统级组合改写成编辑器相关的词移动快捷键把CTRL[这类容易误触的组合改写成ESCact.SendKey { key Escape }把不常用的物理键改写成Backspace、Delete、Home、End等导航键统一不同键盘布局下的操作手感。四、进阶组合SendKey×MultipleSendKey每次只改写为一个按键事件。如果需要一次按键触发多个按键序列需要借助Multiple动作。Multiple定义于 config/src/keyassignment.rsMultiple(VecKeyAssignment),它按顺序执行一个动作列表。官方 Multiple 文档给出了将LeftArrow改写为逐个键入l、e、f、t四个字符的示例local act wezterm.action config.keys { { key LeftArrow, action act.Multiple { act.SendKey { key l }, act.SendKey { key e }, act.SendKey { key f }, act.SendKey { key t }, }, }, }需要注意Multiple中的每个元素可以是任意KeyAssignment因此你既可以在里面放多个SendKey模拟“输入一串文本”也可以混合SendString、ActivateTab、ScrollByPage等其他动作让一次按键同时完成“发指令 切换窗格 滚动”等复合操作。两者的关系是SendKey负责“单个按键的改写”Multiple负责“多个动作的顺序编排”。五、与其他按键注入动作的区分在 WezTerm 的KeyAssignment家族中与SendKey容易混淆的还有SendString与Nop/DisableDefaultAssignment动作作用适合场景SendKey { key, mods }注入一个结构化按键事件含修饰键需要触发 readline/vim 等依赖修饰键的快捷键或精确模拟一次按键SendString { text }直接向窗格写入一串文本字节快速输入固定命令/模板文本不涉及修饰键语义Nop什么都不做吞掉该按键屏蔽某个默认快捷键DisableDefaultAssignment禁用该按键的默认行为仅用于覆盖默认键表时与Nop配合精确覆盖默认按键从实现代码看SendString走的是pane.writer().write_all(...)的字节写入路径wezterm-gui/src/termwindow/mod.rs而SendKey走的是pane.key_down(key, mods)的按键事件路径同文件 L2747-L2755。选择哪一个取决于你希望终端程序接收的是“被敲下的键”还是“被贴入的文本”。六、小结SendKey是 WezTerm 中实现按键级重映射的标准动作由key与mods两个字段组成定义见 config/src/keyassignment.rs 与 config/src/keys.rs它的底层实现是直接向当前窗格注入一次key_down按键事件不会触发二次按键映射见 wezterm-gui/src/termwindow/mod.rs最经典的实战用法是 macOS 下将Option方向键改写为ALT-b/ALT-f从而在终端中获得 Terminal.app 同款的词级光标移动需要一次按键注入多个事件时用Multiple组合多个SendKey见 docs/config/lua/keyassignment/Multiple.md若目标是直接输入一段固定文本而非模拟按键应改用SendString。【免费下载链接】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 SendKey 动作深度指南按键重绑定与跨平台快捷键适配【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读SendKey是 WezTerm 提供的一个键盘动作KeyAssignment它允许将某个按键组合**原样转发re-emit**到当前窗格pane实现“把一个按键的效果改写成另一个按键”的按键重绑定。本文以其官方文档为基础结合仓库源码config/src/keyassignment.rs、config/src/keys.rs、wezterm-gui/src/termwindow/mod.rs讲解其核心语义、配置方式与典型实战场景如 macOS 下复刻 Terminal.app 的光标词级跳转并说明它与 Multiple 的组合用法。一、SendKey是什么核心语义与设计意图SendKey自 WezTerm 20211204-082213-a66c61ee9 版本起引入定义在 config/src/keyassignment.rs 的KeyAssignment枚举中SendKey(KeyNoAction),其官方文档给出的核心语义是将指定的按键按压事件发送给当前窗格pane。这对于重绑定某个按键组合的效果非常有用。这里需要特别澄清一个容易混淆的点重绑定效果只在“将要发送给窗格的输入”这一层生效被改写出的按键不会再次经过 WezTerm 的按键映射表去重新求值。也就是说SendKey是在键映射解析完成之后、向终端程序注入输入之前的“最后一道改写”不存在无限递归的二次映射问题。从实现上看wezterm-gui/src/termwindow/mod.rs 中SendKey的处理分支清晰地印证了这一语义SendKey(key) { use keyevent::Key; let mods key.mods; if let Key::Code(key) self.win_key_code_to_termwiz_key_code( key.key.resolve(self.config.key_map_preference), ) { pane.key_down(key, mods)?; } }可以看到处理流程是取出KeyNoAction中声明的按键码key.key与修饰键key.mods经key_map_preference决定使用物理键位还是映射键位解析最终直接调用窗格的pane.key_down(key, mods)将这一“按键按压”事件注入终端。这本质上等价于“把指定的按键当作你亲手按下”。与之形成对照的是SendStringwezterm-gui/src/termwindow/mod.rs它直接向窗格写入一串文本字节而SendKey注入的是结构化的按键事件交给终端程序自行解析为字符或控制序列。在命令面板Command Palette中SendKey也被登记为一条可搜索命令描述为 Sends {key} to the active pane, as though you typed it见 wezterm-gui/src/commands.rs。二、配置结构KeyNoAction的两个字段SendKey动作携带的数据结构是KeyNoAction定义于 config/src/keys.rs#[derive(Debug, Clone, PartialEq, Eq, FromDynamic, ToDynamic)] pub struct KeyNoAction { pub key: DeferredKeyCode, #[dynamic(default)] pub mods: Modifiers, }字段类型说明keyDeferredKeyCode要发送的按键码必填支持普通键名也支持phys:、mapped:、raw:前缀精确指定物理/映射/原始键码modsModifiers要发送的修饰键组合可省略默认无修饰键2.1key的取值形态DeferredKeyCodeconfig/src/keys.rs支持以下几种写法普通键名如b、f、LeftArrow、UpArrow、Enter等解析时同时匹配 mapped 与 phys 两套键位phys:前缀显式指定物理键码例如phys:US.B不随键盘布局/映射变化mapped:前缀显式指定映射后的键码raw:前缀指定操作系统层面的原始键码数字如raw:56。默认情况下KeyMapPreference::Mapped见 config/src/keys.rs不带前缀的键名按映射键位解析开发者也可以在配置中使用key_map_preference Physical切换为物理键位优先。2.2mods的取值mods支持常见的修饰键名称可组合CTRL、ALTmacOS 上即 Option、SHIFT、SUPERWindows 的 Win / macOS 的 Cmd、CMDmacOS 上SUPER的别名、MEHCTRLALTSHIFT的组合、以及LEADER配合 Leader 键使用。组合多个修饰键时使用|连接例如CTRL|SHIFT。三、实战场景macOS 下复刻 Terminal.app 的 Option 方向键行为SendKey最典型的应用案例来自 macOS 用户在 Terminal.app 中OptionLeftArrow/OptionRightArrow会被映射为ALT-b/ALT-f从而让大多数 Unix shell 和编辑器bash、zsh、readline、vim 等实现按词word前后移动光标。WezTerm 默认不进行这项改写因此文档给出了完整配置local act wezterm.action config.keys { -- Rebind OPT-Left, OPT-Right as ALT-b, ALT-f respectively to match Terminal.app behavior { key LeftArrow, mods OPT, action act.SendKey { key b, mods ALT, }, }, { key RightArrow, mods OPT, action act.SendKey { key f, mods ALT }, }, }这份配置的语义是当用户按下OptionLeftArrow时WezTerm 并不直接把该按键交给终端而是改写成一次Altb的按键事件注入当前窗格readline 类的行编辑库收到ALT-b后即执行“光标后退一个单词”。同理OptionRightArrow被改写为ALT-f触发“光标前进一个单词”。该示例同时展示了SendKey的两个典型应用特征入参组合与出参组合可以不同源按键是OPT修饰的方向键目标按键是ALT修饰的字母键目标按键无需绑定任何动作改写后的ALT-b不要求你在config.keys中预先定义它直接以普通按键的身份进入终端程序的处理逻辑。除了这个经典案例SendKey还可用于统一跨平台快捷键习惯例如在 Windows / Linux 上把SUPERLeftArrow等系统级组合改写成编辑器相关的词移动快捷键把CTRL[这类容易误触的组合改写成ESCact.SendKey { key Escape }把不常用的物理键改写成Backspace、Delete、Home、End等导航键统一不同键盘布局下的操作手感。四、进阶组合SendKey×MultipleSendKey每次只改写为一个按键事件。如果需要一次按键触发多个按键序列需要借助Multiple动作。Multiple定义于 config/src/keyassignment.rsMultiple(VecKeyAssignment),它按顺序执行一个动作列表。官方 Multiple 文档给出了将LeftArrow改写为逐个键入l、e、f、t四个字符的示例local act wezterm.action config.keys { { key LeftArrow, action act.Multiple { act.SendKey { key l }, act.SendKey { key e }, act.SendKey { key f }, act.SendKey { key t }, }, }, }需要注意Multiple中的每个元素可以是任意KeyAssignment因此你既可以在里面放多个SendKey模拟“输入一串文本”也可以混合SendString、ActivateTab、ScrollByPage等其他动作让一次按键同时完成“发指令 切换窗格 滚动”等复合操作。两者的关系是SendKey负责“单个按键的改写”Multiple负责“多个动作的顺序编排”。五、与其他按键注入动作的区分在 WezTerm 的KeyAssignment家族中与SendKey容易混淆的还有SendString与Nop/DisableDefaultAssignment动作作用适合场景SendKey { key, mods }注入一个结构化按键事件含修饰键需要触发 readline/vim 等依赖修饰键的快捷键或精确模拟一次按键SendString { text }直接向窗格写入一串文本字节快速输入固定命令/模板文本不涉及修饰键语义Nop什么都不做吞掉该按键屏蔽某个默认快捷键DisableDefaultAssignment禁用该按键的默认行为仅用于覆盖默认键表时与Nop配合精确覆盖默认按键从实现代码看SendString走的是pane.writer().write_all(...)的字节写入路径wezterm-gui/src/termwindow/mod.rs而SendKey走的是pane.key_down(key, mods)的按键事件路径同文件 L2747-L2755。选择哪一个取决于你希望终端程序接收的是“被敲下的键”还是“被贴入的文本”。六、小结SendKey是 WezTerm 中实现按键级重映射的标准动作由key与mods两个字段组成定义见 config/src/keyassignment.rs 与 config/src/keys.rs它的底层实现是直接向当前窗格注入一次key_down按键事件不会触发二次按键映射见 wezterm-gui/src/termwindow/mod.rs最经典的实战用法是 macOS 下将Option方向键改写为ALT-b/ALT-f从而在终端中获得 Terminal.app 同款的词级光标移动需要一次按键注入多个事件时用Multiple组合多个SendKey见 docs/config/lua/keyassignment/Multiple.md若目标是直接输入一段固定文本而非模拟按键应改用SendString。【免费下载链接】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），仅供参考
