WezTerm Lua 指南使用window:spawn_tab{}在指定窗口内新建标签页【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwindow:spawn_tab{}是 WezTerm 中MuxWindow多路复用窗口对象提供的一个异步 Lua 方法用于在当前窗口内新建一个标签页并启动指定程序同时返回与该标签页关联的MuxTab、MuxPane与MuxWindow对象。本文以 spawn_tab.md 为骨架结合 lua-api-crates/mux 与 config/src/keyassignment.rs 的源码实现系统讲解该方法的全部参数、返回值、底层执行链路并给出可复制的 Lua 配置示例。方法签名与返回值spawn_tab是注册在MuxWindow上的异步方法在 window.rs 中可以看到它的注册方式methods.add_async_method(spawn_tab, |_, this, spawn: SpawnTab| async move { spawn.spawn(this).await });在 Lua 侧的基本调用形式为local tab, pane, window window:spawn_tab {}调用成功后返回三个对象分别对应tabMuxTab对象代表新建的标签页paneMuxPane对象代表标签页内的窗格windowMuxWindow对象即标签页所属的窗口。这三个对象均来自多路复用器Mux层因此不仅能驱动当前 GUI 窗口中的标签页也适用于通过wezterm connect、wezterm ssh等连接到的远端多路复用域是编写跨窗口/跨域自动化脚本的基础设施。同时该方法是异步方法需要在支持协程的环境如on_spawn、on_new_tab等事件回调或wezterm.mux相关脚本中调用。参数详解调用时传入的 Lua 表会被动态转换为config::keyassignment::SpawnCommand结构体见 keyassignment.rs其中args、cwd、set_environment_variables与domain均被支持。当传入空表{}时会启动该域的默认程序通常是用户的默认 shell。args指定要启动的命令参数数组。省略时使用域domain的默认程序window:spawn_tab { args { top } }args是一个字符串数组第一个元素是可执行文件其余为命令行参数。底层实现位于 lib.rsSpawnTab通过CommandBuilderFrag将args、cwd、环境变量等信息转换为真正的CommandBuilder再交给 Mux 层执行。因此这里的语义与wezterm.mux.spawn、wezterm.spawn保持一致给出{ top }即执行top给出{ bash, -l }即执行bash -l。cwd指定程序的工作目录。若省略遵循 default_cwd 的规则通常为用户的 home 目录也可能是 wezterm 启动时的工作目录具体因域而异window:spawn_tab { cwd /tmp }在 keyassignment.rs 的源码注释中可以看到cwd缺省时通常会使用用户的 home 目录但也可能是 wezterm 进程启动时的工作目录对于某些域而言可能是该域中其他合适的位置。set_environment_variables为本次命令调用额外设置的环境变量以键值对形式传入window:spawn_tab { set_environment_variables { FOO BAR } }该字段的类型为HashMapString, String见 keyassignment.rs且是否生效取决于目标域的实现——本地域的spawn_tab会把它们合并进子进程环境而对某些远端域如 SSH 域则取决于域自身的策略。需要清空某个环境变量时可在键上使用FOO 的方式由底层 CommandBuilder 处理。domain指定程序被启动到哪个多路复用域中。默认值是CurrentPaneDomain即使用当前活动窗格所在的域window:spawn_tab { domain { DomainName my.name } }domain的可选值由 SpawnTabDomain 枚举 定义在 Lua 中可写成{ DomainName ... }或{ DomainId N }枚举变体含义Lua 写法DefaultDomain使用默认域{ DefaultDomain {} }CurrentPaneDomain使用当前窗格所在域默认值省略domain即可DomainName(String)按名称使用某个已配置的域{ DomainName my.name }DomainId(usize)按 ID 使用某个域{ DomainId 1 }从 Default 实现 可以看到SpawnTabDomain的默认值正是Self::CurrentPaneDomain这保证了「不指定域时新标签页与当前活动窗格处于同一域」这一符合直觉的行为——如果你在一个通过wezterm ssh打开的远程标签页里调用spawn_tab {}新标签页默认也会开在同一个 SSH 域中。底层执行链路从 Lua 调用到新标签页诞生理解spawn_tab的真实行为需要看它在 Mux 层的实现。SpawnTab结构体及其实现在 lib.rs 中核心流程如下解析窗口与尺寸先通过window.resolve(mux)拿到MuxWindow对应的Window对象取其第 0 个标签页的尺寸作为新标签页的初始尺寸若窗口暂无标签页则回退到配置中的initial_size。记录当前活动窗格保存当前活动窗格的pane_id用于确定默认域CurrentPaneDomain。构建命令调用self.cmd_builder.to_command_builder()将 Lua 参数args、cwd、环境变量转换为CommandBuilder。交给 Mux 统一调度调用mux.spawn_tab_or_window(Some(window.0), self.domain, cmd_builder, cwd, size, pane, ...)由 Mux 完成真实的创建过程。这一步是整个多路复用架构的核心无论是 GUI 本地域、SSH 域还是unix/tls域最终都汇聚到同一个spawn_tab_or_window入口因此spawn_tab的返回对象对远端域同样有效。返回结果将新建的MuxTab、MuxPane以及window_id对应的MuxWindow包装后返回给 Lua 调用方。可见spawn_tab并非 GUI 层「画」出一个标签页那么简单——它完整走了一遍 Mux 的标签创建协议这也是为什么它能返回可供后续操作如tab:set_title、pane:send_text、window:set_workspace等使用的对象句柄。实战示例示例一为当前窗口追加一个默认 shell 标签页local wezterm require wezterm wezterm.on(new-tab-button-clicked, function(window, pane) -- 使用默认程序shell新建标签页 local tab, pane, new_window window:spawn_tab {} end)示例二新建标签页并执行指定命令local tab, pane, win window:spawn_tab { args { htop }, cwd /var/log, set_environment_variables { COLUMNS 200 }, }示例三指定多路复用域local tab, pane, win window:spawn_tab { args { tmux, attach }, domain { DomainName unix }, }示例四结合MuxWindow的其他方法完成自动化由于spawn_tab返回的第三个值是MuxWindow可以直接对其继续调用 window.rs 中注册的其它方法例如set_workspace、get_title、tabs等local tab, pane, win window:spawn_tab { args { top } } win:set_workspace(monitoring)版本与注意事项window:spawn_tab{}自20220624-141144-bd1b7c5d版本起可用见 spawn_tab.md 开头的since标记低于该版本会出现方法不存在的错误。该方法属于异步方法应在 WezTerm 提供协程上下文的 Lua 回调中使用。set_environment_variables是否生效取决于目标域的实现远端域需要确认其环境变量传递策略。更多MuxWindow方法可参考 window.rs更多 Mux 层的标签/窗格/窗口 API 文档见 docs/config/lua/MuxWindow 目录。【免费下载链接】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 指南：使用 `window:spawn_tab{}` 在指定窗口内新建标签页
WezTerm Lua 指南使用window:spawn_tab{}在指定窗口内新建标签页【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwindow:spawn_tab{}是 WezTerm 中MuxWindow多路复用窗口对象提供的一个异步 Lua 方法用于在当前窗口内新建一个标签页并启动指定程序同时返回与该标签页关联的MuxTab、MuxPane与MuxWindow对象。本文以 spawn_tab.md 为骨架结合 lua-api-crates/mux 与 config/src/keyassignment.rs 的源码实现系统讲解该方法的全部参数、返回值、底层执行链路并给出可复制的 Lua 配置示例。方法签名与返回值spawn_tab是注册在MuxWindow上的异步方法在 window.rs 中可以看到它的注册方式methods.add_async_method(spawn_tab, |_, this, spawn: SpawnTab| async move { spawn.spawn(this).await });在 Lua 侧的基本调用形式为local tab, pane, window window:spawn_tab {}调用成功后返回三个对象分别对应tabMuxTab对象代表新建的标签页paneMuxPane对象代表标签页内的窗格windowMuxWindow对象即标签页所属的窗口。这三个对象均来自多路复用器Mux层因此不仅能驱动当前 GUI 窗口中的标签页也适用于通过wezterm connect、wezterm ssh等连接到的远端多路复用域是编写跨窗口/跨域自动化脚本的基础设施。同时该方法是异步方法需要在支持协程的环境如on_spawn、on_new_tab等事件回调或wezterm.mux相关脚本中调用。参数详解调用时传入的 Lua 表会被动态转换为config::keyassignment::SpawnCommand结构体见 keyassignment.rs其中args、cwd、set_environment_variables与domain均被支持。当传入空表{}时会启动该域的默认程序通常是用户的默认 shell。args指定要启动的命令参数数组。省略时使用域domain的默认程序window:spawn_tab { args { top } }args是一个字符串数组第一个元素是可执行文件其余为命令行参数。底层实现位于 lib.rsSpawnTab通过CommandBuilderFrag将args、cwd、环境变量等信息转换为真正的CommandBuilder再交给 Mux 层执行。因此这里的语义与wezterm.mux.spawn、wezterm.spawn保持一致给出{ top }即执行top给出{ bash, -l }即执行bash -l。cwd指定程序的工作目录。若省略遵循 default_cwd 的规则通常为用户的 home 目录也可能是 wezterm 启动时的工作目录具体因域而异window:spawn_tab { cwd /tmp }在 keyassignment.rs 的源码注释中可以看到cwd缺省时通常会使用用户的 home 目录但也可能是 wezterm 进程启动时的工作目录对于某些域而言可能是该域中其他合适的位置。set_environment_variables为本次命令调用额外设置的环境变量以键值对形式传入window:spawn_tab { set_environment_variables { FOO BAR } }该字段的类型为HashMapString, String见 keyassignment.rs且是否生效取决于目标域的实现——本地域的spawn_tab会把它们合并进子进程环境而对某些远端域如 SSH 域则取决于域自身的策略。需要清空某个环境变量时可在键上使用FOO 的方式由底层 CommandBuilder 处理。domain指定程序被启动到哪个多路复用域中。默认值是CurrentPaneDomain即使用当前活动窗格所在的域window:spawn_tab { domain { DomainName my.name } }domain的可选值由 SpawnTabDomain 枚举 定义在 Lua 中可写成{ DomainName ... }或{ DomainId N }枚举变体含义Lua 写法DefaultDomain使用默认域{ DefaultDomain {} }CurrentPaneDomain使用当前窗格所在域默认值省略domain即可DomainName(String)按名称使用某个已配置的域{ DomainName my.name }DomainId(usize)按 ID 使用某个域{ DomainId 1 }从 Default 实现 可以看到SpawnTabDomain的默认值正是Self::CurrentPaneDomain这保证了「不指定域时新标签页与当前活动窗格处于同一域」这一符合直觉的行为——如果你在一个通过wezterm ssh打开的远程标签页里调用spawn_tab {}新标签页默认也会开在同一个 SSH 域中。底层执行链路从 Lua 调用到新标签页诞生理解spawn_tab的真实行为需要看它在 Mux 层的实现。SpawnTab结构体及其实现在 lib.rs 中核心流程如下解析窗口与尺寸先通过window.resolve(mux)拿到MuxWindow对应的Window对象取其第 0 个标签页的尺寸作为新标签页的初始尺寸若窗口暂无标签页则回退到配置中的initial_size。记录当前活动窗格保存当前活动窗格的pane_id用于确定默认域CurrentPaneDomain。构建命令调用self.cmd_builder.to_command_builder()将 Lua 参数args、cwd、环境变量转换为CommandBuilder。交给 Mux 统一调度调用mux.spawn_tab_or_window(Some(window.0), self.domain, cmd_builder, cwd, size, pane, ...)由 Mux 完成真实的创建过程。这一步是整个多路复用架构的核心无论是 GUI 本地域、SSH 域还是unix/tls域最终都汇聚到同一个spawn_tab_or_window入口因此spawn_tab的返回对象对远端域同样有效。返回结果将新建的MuxTab、MuxPane以及window_id对应的MuxWindow包装后返回给 Lua 调用方。可见spawn_tab并非 GUI 层「画」出一个标签页那么简单——它完整走了一遍 Mux 的标签创建协议这也是为什么它能返回可供后续操作如tab:set_title、pane:send_text、window:set_workspace等使用的对象句柄。实战示例示例一为当前窗口追加一个默认 shell 标签页local wezterm require wezterm wezterm.on(new-tab-button-clicked, function(window, pane) -- 使用默认程序shell新建标签页 local tab, pane, new_window window:spawn_tab {} end)示例二新建标签页并执行指定命令local tab, pane, win window:spawn_tab { args { htop }, cwd /var/log, set_environment_variables { COLUMNS 200 }, }示例三指定多路复用域local tab, pane, win window:spawn_tab { args { tmux, attach }, domain { DomainName unix }, }示例四结合MuxWindow的其他方法完成自动化由于spawn_tab返回的第三个值是MuxWindow可以直接对其继续调用 window.rs 中注册的其它方法例如set_workspace、get_title、tabs等local tab, pane, win window:spawn_tab { args { top } } win:set_workspace(monitoring)版本与注意事项window:spawn_tab{}自20220624-141144-bd1b7c5d版本起可用见 spawn_tab.md 开头的since标记低于该版本会出现方法不存在的错误。该方法属于异步方法应在 WezTerm 提供协程上下文的 Lua 回调中使用。set_environment_variables是否生效取决于目标域的实现远端域需要确认其环境变量传递策略。更多MuxWindow方法可参考 window.rs更多 Mux 层的标签/窗格/窗口 API 文档见 docs/config/lua/MuxWindow 目录。【免费下载链接】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），仅供参考