WezTerm 配置详解用disable_default_mouse_bindings完全掌控鼠标行为【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读WezTerm 默认内置了一套鼠标按键分配mouse assignment覆盖单击选中、双击选词、三击选行、滚轮滚动等常用操作。当这些默认行为与你的工作流冲突时可以通过disable_default_mouse_bindings true一键关闭全部默认鼠标绑定然后借助mouse_bindings重新定义每一件事。本文将围绕这一配置项完整梳理默认鼠标分配的清单、底层实现原理以及从零自定义鼠标行为的最佳实践。配置项说明disable_default_mouse_bindings该选项定义在配置结构中默认值为false。字段声明见 config/src/config.rs#[dynamic(default)] pub mouse_bindings: VecMouse, #[dynamic(default)] pub disable_default_mouse_bindings: bool,官方参考文档 docs/config/lua/config/disable_default_mouse_bindings.md 的说明非常直接默认值false默认鼠标分配会被启用当设置为true时默认的鼠标分配将全部不再生效从而允许你对这些分配进行精确控制。local wezterm require wezterm local config {} config.disable_default_mouse_bindings true return config关键点一旦开启系统默认的鼠标行为选中、复制、滚轮、粘贴等会全部消失。此时必须显式注册每一个你需要的绑定否则鼠标将失去对应的默认功能。开启后会被关闭的默认鼠标绑定要理解这个开关的价值先要清楚它到底关掉了什么。完整清单记录在 docs/config/mouse.md 的 Default Mouse Assignments 一节也逐条硬编码在 wezterm-gui/src/inputmap.rs 中。以下表中act是wezterm.action的别名local act wezterm.action事件修饰键动作三击左键按下Triple Left DownNONEact.SelectTextAtMouseCursor(Line)双击左键按下Double Left DownNONEact.SelectTextAtMouseCursor(Word)单击左键按下Single Left DownNONEact.SelectTextAtMouseCursor(Cell)单击左键按下SHIFTact.ExtendSelectionToMouseCursor(Cell)单击左键按下ALTact.SelectTextAtMouseCursor(Block)单击左键抬起Single Left UpSHIFTact.CompleteSelectionOrOpenLinkAtMouseCursor(ClipboardAndPrimarySelection)单击左键抬起NONEact.CompleteSelectionOrOpenLinkAtMouseCursor(ClipboardAndPrimarySelection)单击左键抬起ALTact.CompleteSelection(ClipboardAndPrimarySelection)双击左键抬起NONEact.CompleteSelection(ClipboardAndPrimarySelection)三击左键抬起NONEact.CompleteSelection(ClipboardAndPrimarySelection)单击左键拖拽Single Left DragNONEact.ExtendSelectionToMouseCursor(Cell)单击左键拖拽ALTact.ExtendSelectionToMouseCursor(Block)单击左键按下ALTSHIFTact.ExtendSelectionToMouseCursor(Block)单击左键抬起ALTSHIFTact.CompleteSelection(ClipboardAndPrimarySelection)双击左键拖拽NONEact.ExtendSelectionToMouseCursor(Word)三击左键拖拽NONEact.ExtendSelectionToMouseCursor(Line)单击中键按下NONEact.PasteFrom(PrimarySelection)单击左键拖拽SUPERact.StartWindowDrag单击左键拖拽CTRLSHIFTact.StartWindowDrag滚轮向上NONEact.ScrollByCurrentEventWheelDelta滚轮向下NONEact.ScrollByCurrentEventWheelDelta其中ScrollByCurrentEventWheelDelta是滚轮滚动动作相关内容见 ScrollByCurrentEventWheelDelta 参考窗口拖拽动作StartWindowDrag自 20210314 版本起提供块选择相关绑定自 20220624 版本起提供。底层实现默认绑定是如何被屏蔽的disable_default_mouse_bindings的实际生效逻辑位于 wezterm-gui/src/inputmap.rs。在InputMap::new中WezTerm 先收集你在mouse_bindings中配置的绑定再判断是否注册默认绑定if !config.disable_default_mouse_bindings { m!( [ /* 滚轮、选择、复制、粘贴、窗口拖拽等默认绑定 */ ], ); }随后会执行一层“去重与展开”逻辑inputmap.rs所有值为DisableDefaultAssignment的条目会被剔除retain这对应官方约定的“用act.DisableDefaultAssignment取消某个默认绑定”的能力alt_screen Any的条目会被展开成True与False两个独立条目确保在主屏幕与 alt screen如全屏编辑器、less等应用下都按预期匹配。从源码结构可以推断disable_default_mouse_bindings true的效果等价于让上面整个默认注册宏不执行最终mouse映射表只保留mouse_bindings中用户显式声明的条目。值得注意的是该开关只影响鼠标分配键盘默认绑定的开关是独立的disable_default_key_bindings见 config/src/config.rs两者互不影响。配置解析层面的支撑如下用户自定义鼠标绑定的收集入口是Config::mouse_bindings()config/src/config.rs把VecMouse转换成以(MouseEventTrigger, MouseEventTriggerMods)为键的映射表Mouse结构体包含event、mods、action三个字段定义在 config/src/keys.rsMouseEventTriggerMods额外支持mouse_reporting与alt_screen两个可选字段config/src/keys.rsalt_screen支持true、false、Any三种取值解析逻辑见 config/src/keys.rs默认值为Any。配合mouse_bindings重建你的绑定开启disable_default_mouse_bindings后需要通过config.mouse_bindings逐条声明绑定。每个条目包含以下字段event触发事件包含事件类型Down/Up/Drag、连续点击次数streak以及鼠标键buttonLeft/Right/Middle滚轮为{ WheelUp 1 }/{ WheelDown 1 }mods需要按下的修饰键语义与键盘绑定的mods完全一致详见 Configuring Key Assignmentsaction匹配后执行的动作mouse_reporting可选布尔值默认false用于限定仅在 pane 的鼠标上报状态匹配时才生效alt_screen可选字段默认Any可设为true或false限定仅在对应 alt screen 状态下匹配。事件在 Lua 中的写法与streak对应关系如下事件Lua 表示三击左键按下event{Down{streak3, buttonLeft}}双击左键抬起event{Up{streak2, buttonLeft}}单击左键拖拽event{Drag{streak1, buttonLeft}}事件识别器支持任意streak值例如想要四击绑定直接写streak4即可。示例一重写默认选择行为local wezterm require wezterm local act wezterm.action local config {} config.disable_default_mouse_bindings true config.mouse_bindings { -- 右键单击向终端发送字符串 woot { event { Down { streak 1, button Right } }, mods NONE, action act.SendString woot, }, -- 修改默认单击行为只选择文本不打开超链接 { event { Up { streak 1, button Left } }, mods NONE, action act.CompleteSelection ClipboardAndPrimarySelection, }, -- 改为 CTRL单击打开超链接 { event { Up { streak 1, button Left } }, mods CTRL, action act.OpenLinkAtMouseCursor, }, } return config示例二用滚轮配合修饰键调整字号local wezterm require wezterm local act wezterm.action local config {} config.disable_default_mouse_bindings true config.mouse_bindings { -- 按住 CTRL 向上滚动增大字体 { event { Down { streak 1, button { WheelUp 1 } } }, mods CTRL, action act.IncreaseFontSize, }, -- 按住 CTRL 向下滚动减小字体 { event { Down { streak 1, button { WheelDown 1 } } }, mods CTRL, action act.DecreaseFontSize, }, } return config滚轮事件中的streak与增量统一写为1只是为了匹配事件如果需要读取实际滚动增量可以在处理动作时使用window:current_event()见 window:current_event。实战陷阱只绑定Up事件的注意点如果你只绑定了某个鼠标键的Up事件而没有绑定对应的Down事件Down事件仍然会被发送给正在运行的程序。如果该程序启用了鼠标追踪例如 tmux、vim 的 mouse 支持就会产生程序收到了Down却没收到Up的怪异行为。官方文档 docs/config/mouse.md 明确建议同时把对应的Down事件绑定为act.Nop以吞掉它local wezterm require wezterm local act wezterm.action local config {} config.disable_default_mouse_bindings true config.mouse_bindings { -- 绑定 CTRL单击 的 Up 事件用于打开超链接 { event { Up { streak 1, button Left } }, mods CTRL, action act.OpenLinkAtMouseCursor, }, -- 同时禁用 Down 事件避免程序收到孤立的按下事件 { event { Down { streak 1, button Left } }, mods CTRL, action act.Nop, }, } return config与鼠标上报mouse reporting的关系默认情况下终端里运行的应用不会响应鼠标事件但应用可以通过转义序列请求鼠标事件追踪。需要注意当应用启用鼠标追踪时鼠标事件不会与你的鼠标绑定匹配而是直接透传给应用按住SHIFT可以绕过鼠标上报捕获事件不会被传给应用而是按仿佛没按 SHIFT的方式去匹配你的绑定通过 bypass_mouse_reporting_modifiers 可以自定义这组绕过修饰键。mouse_reportingtrue的绑定会阻止 pane 中的应用收到对应鼠标事件因此官方建议尽量避免除非你明确知道自己在做什么此时仍可通过按住绕过修饰键把事件发给应用。验证与排错运行wezterm show-keys可以查看当前生效的完整键盘与鼠标绑定表是确认自定义绑定是否按预期注册的最直接手段参考 show-keys 命令说明排查问题时可以先检查配置是否被正确加载、disable_default_mouse_bindings是否被其他配置片段意外覆盖所有可用的动作KeyAssignment均可在 KeyAssignment 参考 中查阅绑定动作时应优先从这里选取合法的动作名。总结disable_default_mouse_bindings是 WezTerm 鼠标体系中最彻底的自定义入口默认值为false置为true后会清空内置的二十余条鼠标分配选中、复制、粘贴、滚轮、窗口拖拽等并强制你通过mouse_bindings逐条重建。结合 docs/config/mouse.md 中的默认分配清单与 wezterm-gui/src/inputmap.rs 的注册逻辑你既可以理解默认行为从何而来也能以最小代价构建一套完全符合个人习惯的鼠标交互方案。【免费下载链接】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 配置详解：用 `disable_default_mouse_bindings` 完全掌控鼠标行为
WezTerm 配置详解用disable_default_mouse_bindings完全掌控鼠标行为【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读WezTerm 默认内置了一套鼠标按键分配mouse assignment覆盖单击选中、双击选词、三击选行、滚轮滚动等常用操作。当这些默认行为与你的工作流冲突时可以通过disable_default_mouse_bindings true一键关闭全部默认鼠标绑定然后借助mouse_bindings重新定义每一件事。本文将围绕这一配置项完整梳理默认鼠标分配的清单、底层实现原理以及从零自定义鼠标行为的最佳实践。配置项说明disable_default_mouse_bindings该选项定义在配置结构中默认值为false。字段声明见 config/src/config.rs#[dynamic(default)] pub mouse_bindings: VecMouse, #[dynamic(default)] pub disable_default_mouse_bindings: bool,官方参考文档 docs/config/lua/config/disable_default_mouse_bindings.md 的说明非常直接默认值false默认鼠标分配会被启用当设置为true时默认的鼠标分配将全部不再生效从而允许你对这些分配进行精确控制。local wezterm require wezterm local config {} config.disable_default_mouse_bindings true return config关键点一旦开启系统默认的鼠标行为选中、复制、滚轮、粘贴等会全部消失。此时必须显式注册每一个你需要的绑定否则鼠标将失去对应的默认功能。开启后会被关闭的默认鼠标绑定要理解这个开关的价值先要清楚它到底关掉了什么。完整清单记录在 docs/config/mouse.md 的 Default Mouse Assignments 一节也逐条硬编码在 wezterm-gui/src/inputmap.rs 中。以下表中act是wezterm.action的别名local act wezterm.action事件修饰键动作三击左键按下Triple Left DownNONEact.SelectTextAtMouseCursor(Line)双击左键按下Double Left DownNONEact.SelectTextAtMouseCursor(Word)单击左键按下Single Left DownNONEact.SelectTextAtMouseCursor(Cell)单击左键按下SHIFTact.ExtendSelectionToMouseCursor(Cell)单击左键按下ALTact.SelectTextAtMouseCursor(Block)单击左键抬起Single Left UpSHIFTact.CompleteSelectionOrOpenLinkAtMouseCursor(ClipboardAndPrimarySelection)单击左键抬起NONEact.CompleteSelectionOrOpenLinkAtMouseCursor(ClipboardAndPrimarySelection)单击左键抬起ALTact.CompleteSelection(ClipboardAndPrimarySelection)双击左键抬起NONEact.CompleteSelection(ClipboardAndPrimarySelection)三击左键抬起NONEact.CompleteSelection(ClipboardAndPrimarySelection)单击左键拖拽Single Left DragNONEact.ExtendSelectionToMouseCursor(Cell)单击左键拖拽ALTact.ExtendSelectionToMouseCursor(Block)单击左键按下ALTSHIFTact.ExtendSelectionToMouseCursor(Block)单击左键抬起ALTSHIFTact.CompleteSelection(ClipboardAndPrimarySelection)双击左键拖拽NONEact.ExtendSelectionToMouseCursor(Word)三击左键拖拽NONEact.ExtendSelectionToMouseCursor(Line)单击中键按下NONEact.PasteFrom(PrimarySelection)单击左键拖拽SUPERact.StartWindowDrag单击左键拖拽CTRLSHIFTact.StartWindowDrag滚轮向上NONEact.ScrollByCurrentEventWheelDelta滚轮向下NONEact.ScrollByCurrentEventWheelDelta其中ScrollByCurrentEventWheelDelta是滚轮滚动动作相关内容见 ScrollByCurrentEventWheelDelta 参考窗口拖拽动作StartWindowDrag自 20210314 版本起提供块选择相关绑定自 20220624 版本起提供。底层实现默认绑定是如何被屏蔽的disable_default_mouse_bindings的实际生效逻辑位于 wezterm-gui/src/inputmap.rs。在InputMap::new中WezTerm 先收集你在mouse_bindings中配置的绑定再判断是否注册默认绑定if !config.disable_default_mouse_bindings { m!( [ /* 滚轮、选择、复制、粘贴、窗口拖拽等默认绑定 */ ], ); }随后会执行一层“去重与展开”逻辑inputmap.rs所有值为DisableDefaultAssignment的条目会被剔除retain这对应官方约定的“用act.DisableDefaultAssignment取消某个默认绑定”的能力alt_screen Any的条目会被展开成True与False两个独立条目确保在主屏幕与 alt screen如全屏编辑器、less等应用下都按预期匹配。从源码结构可以推断disable_default_mouse_bindings true的效果等价于让上面整个默认注册宏不执行最终mouse映射表只保留mouse_bindings中用户显式声明的条目。值得注意的是该开关只影响鼠标分配键盘默认绑定的开关是独立的disable_default_key_bindings见 config/src/config.rs两者互不影响。配置解析层面的支撑如下用户自定义鼠标绑定的收集入口是Config::mouse_bindings()config/src/config.rs把VecMouse转换成以(MouseEventTrigger, MouseEventTriggerMods)为键的映射表Mouse结构体包含event、mods、action三个字段定义在 config/src/keys.rsMouseEventTriggerMods额外支持mouse_reporting与alt_screen两个可选字段config/src/keys.rsalt_screen支持true、false、Any三种取值解析逻辑见 config/src/keys.rs默认值为Any。配合mouse_bindings重建你的绑定开启disable_default_mouse_bindings后需要通过config.mouse_bindings逐条声明绑定。每个条目包含以下字段event触发事件包含事件类型Down/Up/Drag、连续点击次数streak以及鼠标键buttonLeft/Right/Middle滚轮为{ WheelUp 1 }/{ WheelDown 1 }mods需要按下的修饰键语义与键盘绑定的mods完全一致详见 Configuring Key Assignmentsaction匹配后执行的动作mouse_reporting可选布尔值默认false用于限定仅在 pane 的鼠标上报状态匹配时才生效alt_screen可选字段默认Any可设为true或false限定仅在对应 alt screen 状态下匹配。事件在 Lua 中的写法与streak对应关系如下事件Lua 表示三击左键按下event{Down{streak3, buttonLeft}}双击左键抬起event{Up{streak2, buttonLeft}}单击左键拖拽event{Drag{streak1, buttonLeft}}事件识别器支持任意streak值例如想要四击绑定直接写streak4即可。示例一重写默认选择行为local wezterm require wezterm local act wezterm.action local config {} config.disable_default_mouse_bindings true config.mouse_bindings { -- 右键单击向终端发送字符串 woot { event { Down { streak 1, button Right } }, mods NONE, action act.SendString woot, }, -- 修改默认单击行为只选择文本不打开超链接 { event { Up { streak 1, button Left } }, mods NONE, action act.CompleteSelection ClipboardAndPrimarySelection, }, -- 改为 CTRL单击打开超链接 { event { Up { streak 1, button Left } }, mods CTRL, action act.OpenLinkAtMouseCursor, }, } return config示例二用滚轮配合修饰键调整字号local wezterm require wezterm local act wezterm.action local config {} config.disable_default_mouse_bindings true config.mouse_bindings { -- 按住 CTRL 向上滚动增大字体 { event { Down { streak 1, button { WheelUp 1 } } }, mods CTRL, action act.IncreaseFontSize, }, -- 按住 CTRL 向下滚动减小字体 { event { Down { streak 1, button { WheelDown 1 } } }, mods CTRL, action act.DecreaseFontSize, }, } return config滚轮事件中的streak与增量统一写为1只是为了匹配事件如果需要读取实际滚动增量可以在处理动作时使用window:current_event()见 window:current_event。实战陷阱只绑定Up事件的注意点如果你只绑定了某个鼠标键的Up事件而没有绑定对应的Down事件Down事件仍然会被发送给正在运行的程序。如果该程序启用了鼠标追踪例如 tmux、vim 的 mouse 支持就会产生程序收到了Down却没收到Up的怪异行为。官方文档 docs/config/mouse.md 明确建议同时把对应的Down事件绑定为act.Nop以吞掉它local wezterm require wezterm local act wezterm.action local config {} config.disable_default_mouse_bindings true config.mouse_bindings { -- 绑定 CTRL单击 的 Up 事件用于打开超链接 { event { Up { streak 1, button Left } }, mods CTRL, action act.OpenLinkAtMouseCursor, }, -- 同时禁用 Down 事件避免程序收到孤立的按下事件 { event { Down { streak 1, button Left } }, mods CTRL, action act.Nop, }, } return config与鼠标上报mouse reporting的关系默认情况下终端里运行的应用不会响应鼠标事件但应用可以通过转义序列请求鼠标事件追踪。需要注意当应用启用鼠标追踪时鼠标事件不会与你的鼠标绑定匹配而是直接透传给应用按住SHIFT可以绕过鼠标上报捕获事件不会被传给应用而是按仿佛没按 SHIFT的方式去匹配你的绑定通过 bypass_mouse_reporting_modifiers 可以自定义这组绕过修饰键。mouse_reportingtrue的绑定会阻止 pane 中的应用收到对应鼠标事件因此官方建议尽量避免除非你明确知道自己在做什么此时仍可通过按住绕过修饰键把事件发给应用。验证与排错运行wezterm show-keys可以查看当前生效的完整键盘与鼠标绑定表是确认自定义绑定是否按预期注册的最直接手段参考 show-keys 命令说明排查问题时可以先检查配置是否被正确加载、disable_default_mouse_bindings是否被其他配置片段意外覆盖所有可用的动作KeyAssignment均可在 KeyAssignment 参考 中查阅绑定动作时应优先从这里选取合法的动作名。总结disable_default_mouse_bindings是 WezTerm 鼠标体系中最彻底的自定义入口默认值为false置为true后会清空内置的二十余条鼠标分配选中、复制、粘贴、滚轮、窗口拖拽等并强制你通过mouse_bindings逐条重建。结合 docs/config/mouse.md 中的默认分配清单与 wezterm-gui/src/inputmap.rs 的注册逻辑你既可以理解默认行为从何而来也能以最小代价构建一套完全符合个人习惯的鼠标交互方案。【免费下载链接】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），仅供参考