WezTerm Pane 对象完全指南Lua API 方法详解与实战配置【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读Pane窗格对象是 WezTerm Lua 配置体系中最重要的运行时对象之一它代表一个正在运行的终端窗格封装了其伪终端PTY、关联进程以及解析后的屏幕与滚动缓冲scrollback状态。无论是自定义状态栏、实现“在编辑器中打开回滚内容”、根据密码输入或 mux 延迟动态调整配色还是用脚本完成分屏与发送文本都离不开对Pane对象各种方法的调用。本文将逐一讲解Pane对象的全部可用方法并给出可直接复制使用的完整 Lua 配置示例与源码实现佐证帮助你在自己的 WezTerm 配置中高效操作与探查任意窗格。Pane对象是什么在较新版本20221119-145034-49b9839f起中WezTerm 取消了此前 mux 层与 gui 层分别创建的MuxPane和Pane两套对象只保留底层 mux 窗格并在文档中统称为Pane。这一点在 pane/mux_pane.md 中也有体现——pane:mux_pane()方法已被标记为 deprecated在 nightly 版本中直接返回其自身。Pane对象通常是作为事件回调参数传入你的代码的例如update-status、format-tab-title、user-var-changed等事件它是 WezTerm 进程中某个存活实例的句柄。它跟踪以下内容伪终端或真实的串行终端以及关联的进程解析后的屏幕状态与滚动缓冲。通过Pane对象你可以向关联进程发送输入也可以探查该窗格的终端仿真状态。从源码结构看mux/src/pane.rs中定义了一个核心 trait mux/src/pane.rspub trait Pane: Downcast Send SyncLua 层所暴露的Pane方法即对应此 trait 中的pane_id()、get_cursor_position()、get_dimensions()、get_title()、get_semantic_zones()、get_current_working_dir()、is_alt_screen_active()等接口例如get_cursor_position返回StableCursorPositionmux/src/pane.rs、get_metadata默认返回Value::Nullmux/src/pane.rs。这从底层印证了文档中“方法返回值是结构体的 Lua 表示”的说法。激活与导航pane:activate()自20230408-112425-69ae8472起可用。激活聚焦该窗格及其所在的标签页常用于脚本化的焦点切换。pane:move_to_new_tab()自20230326-111934-3666303c起可用。在该窗格所在的窗口中新建一个标签页并将该窗格移动过去。它返回新创建的 MuxTab 对象以及包含它的 MuxWindow 对象config.keys { { key !, mods LEADER | SHIFT, action wezterm.action_callback(function(win, pane) local tab, window pane:move_to_new_tab() end), }, }pane:move_to_new_window([WORKSPACE])自20230326-111934-3666303c起可用。新建一个窗口并把该窗格移入其中。WORKSPACE参数可选指定新窗口关联的 workspace 名称不指定时使用当前活动 workspace。返回新创建的MuxTab与MuxWindow对象config.keys { { key !, mods LEADER | SHIFT, action wezterm.action_callback(function(win, pane) local tab, window pane:move_to_new_window() end), }, }对应的 CLI 命令是wezterm cli move-pane-to-new-tab详见 cli/move-pane-to-new-tab.md其支持--new-window、--window-id、--workspace与--pane-id等参数。pane:tab()与pane:window()均自20220807-113146-c2fee766起可用。pane:tab()返回包含该窗格的 MuxTab 对象当pane是 GUI 管理的 overlay 窗格如 debug overlay时返回nil因为这些窗格不受 mux 层管理。pane:window()返回包含该窗格所在标签页的 MuxWindow 对象。pane:pane_id()自20201031-154415-9614e117起可用。返回窗格的数字 id。该 id 用于在内部 multiplexer 中标识窗格也可以配合wezterm cli的--pane-id参数见 cli/index.md 的 Targeting Panes 一节指定操作对象。pane:get_domain_name()自20220624-141144-bd1b7c5d起可用。返回与该窗格关联的 domain 的名称domain 即 multiplexer 域的抽象如DefaultDomain或自定义域。状态探查光标、尺寸与标题pane:get_cursor_position()自20201031-154415-9614e117起可用。返回StableCursorPosition结构体的 Lua 表示包含四个字段x—— 水平单元格索引y—— 垂直稳定行索引stable row indexshape——CursorShape枚举值visibility——CursorVisibility枚举值。pane:get_dimensions()自20201031-154415-9614e117起可用。返回RenderableDimensions结构体的 Lua 表示描述了视口与滚动缓冲的尺寸和位置cols—— 列数viewport_rows—— 窗口可见区域的垂直单元格数scrollback_rows—— 滚动缓冲与视口的总行数physical_top—— 物理非滚动缓冲屏幕顶部以稳定索引表示scrollback_top—— 滚动缓冲顶部即 WezTerm 记忆的最早一行。get_dimensions()是所有“取整段文本/按坐标定位”方法的基础下面会看到大量pane:get_dimensions().scrollback_rows的用法。pane:get_title()自20201031-154415-9614e117起可用。返回窗格标题默认通常是wezterm但可通过应用发送的OSC 1图标/标签页标题和OSC 2窗口标题转义序列修改。其返回优先级为若OSC 1设置了非空字符串则返回之否则返回OSC 2的值。若标题仍为wezterm且是本地窗格WezTerm 会尝试解析前台进程的可执行路径并用其替代。注意Windows 上 OS 层 PTY 的默认行为是在新程序附加控制台时隐式发送OSC 2序列。pane:get_tty_name()自20230408-112425-69ae8472起可用。返回 tty 设备名不可用时返回nil。限制仅对本地窗格可用mux 窗格及通过ssh连接的远程窗格无法获取仅 Unix 系统有对应概念Windows 不可用。示例——在状态栏右侧显示 tty 名local wezterm require wezterm wezterm.on(update-status, function(window, pane) local tty pane:get_tty_name() if tty then window:set_right_status(tty) else window:set_right_status end end) return {}当前工作目录与进程信息pane:get_current_working_dir()自20201031-154415-9614e117起可用。返回窗格当前工作目录若未知则返回nil。目录来源为应用发送的 OSC 7即 shell-integration.md 中描述的“通知终端工作目录”机制。如果从未收到 OSC 7且窗格对应本地进程则 WezTerm 会Unix 上确定附着到 PTY 的process group leader前台进程Windows 上用启发式方法推断等效的前台进程。随后用操作系统相关代码解析工作目录。各平台支持情况OS是否支持macOS是自20201031-154415-9614e117起Linux是自20201031-154415-9614e117起Windows是自20220101-133340-7edc5b5a起返回值是URI 字符串而非普通文件路径——因为应用可以把它设成 FTP URL 等其他类型。自20240127-113634-bbcac864起该方法返回一个 Url 对象提供scheme、file_path、username、password、host、path、fragment、query等字段方便解码与操作 URL。pane:get_foreground_process_info()自20220624-141144-bd1b7c5d起可用。返回对应前台进程的 LocalProcessInfo 对象。限制与注意事项仅对本地窗格可用mux 窗格与ssh远程窗格无法获取远程进程信息Unix 上查询 process group leader前台进程Windows 无此概念改为检查原始启动程序的进程树假设“最新生成的子孙进程”为前台进程目前仅 Linux、macOS 与 Windows 支持查询路径FreeBSD 等系统暂不支持查询可能因 WezTerm 不可控的原因失败查询进程信息有运行时开销过度使用可能拖慢 WezTerm。若无法确定进程则返回nil。示例——在右侧状态栏显示 pid 与可执行文件名local wezterm require wezterm -- 等价于 POSIX basename(3) -- 给定 /foo/bar 返回 bar -- 给定 c:\\foo\\bar 返回 bar function basename(s) return string.gsub(s, (.*[/\\])(.*), %2) end wezterm.on(update-right-status, function(window, pane) local info pane:get_foreground_process_info() if info then window:set_right_status( tostring(info.pid) .. .. basename(info.executable) ) else window:set_right_status end end) return {}pane:get_foreground_process_name()自20220101-133340-7edc5b5a起可用。返回窗格可执行映像的路径未知时返回nil。限制与get_foreground_process_info()相同。示例——状态栏显示可执行文件名local wezterm require wezterm function basename(s) return string.gsub(s, (.*[/\\])(.*), %2) end wezterm.on(update-right-status, function(window, pane) window:set_right_status(basename(pane:get_foreground_process_name())) end) return {}另见 get_foreground_process_info。读取文本物理行、逻辑行与带样式输出pane:get_lines_as_text([nlines])自20201031-154415-9614e117起可用。返回视口内物理行可能被折行的、组成终端显示矩阵一行的文本的纯文本表示不含颜色等属性。参数与行为细节nlines可选指定要获取的行数缺省为视口行数窗格高度每行尾部空格被去除行间以\n连接末尾空行会被剥离因此当窗格只有几行输出时返回的行数可能比你预期的少需要逻辑行时改用get_logical_lines_as_text见 get_lines_as_text.md。示例——按CTRLE将整个回滚与可视区域写入临时文件并在vim中打开local wezterm require wezterm local io require io local os require os local act wezterm.action wezterm.on(trigger-vim-with-scrollback, function(window, 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() -- 开新窗口运行 vim 打开该文件 window:perform_action( act.SpawnCommandInNewWindow { args { vim, name }, }, pane ) -- 等待 vim 读完文件再删除窗口创建与进程派生相对本脚本是异步的 wezterm.sleep_ms(1000) os.remove(name) end) return { keys { { key E, mods CTRL, action act.EmitEvent trigger-vim-with-scrollback, }, }, }pane:get_lines_as_escapes([nlines])自20240127-113634-bbcac864起可用。与get_lines_as_text类似但返回的字符串包含ANSI 转义序列从而保留文本颜色与样式适合管道传给支持 ANSI 的分页器。要取整个回滚同样用pane:get_lines_as_escapes(pane:get_dimensions().scrollback_rows)示例——按CTRLE用less -fr分页查看带颜色的完整回滚local wezterm require wezterm local io require io local os require os local act wezterm.action wezterm.on(trigger-less-with-scrollback, function(window, pane) local text pane:get_lines_as_escapes(pane:get_dimensions().scrollback_rows) local name os.tmpname() local f io.open(name, w) f:write(text) f:flush() f:close() window:perform_action( act.SpawnCommandInNewWindow { args { less, -fr, name }, }, pane ) wezterm.sleep_ms(1000) os.remove(name) end) return { keys { { key E, mods CTRL, action act.EmitEvent trigger-less-with-scrollback, }, }, }另见 get_lines_as_text.md。pane:get_logical_lines_as_text([nlines])自20220101-133340-7edc5b5a起可用。返回视口内逻辑行折行前的原始输入行的文本表示同样不含颜色属性。WezTerm 并不存储逻辑行而是通过物理行中保存的元数据重新计算出来过长的逻辑行会被强制折行以限制窗口缩放与选择操作时的重排成本。尾部空格去除、\n连接、末尾空行剥离等行为与get_lines_as_text一致。取整个回滚pane:get_logical_lines_as_text(pane:get_dimensions().scrollback_rows)pane:get_text_from_region(start_x, start_y, end_x, end_y)自20230320-124340-559cb7b0起可用。返回指定区域的文本start_x/end_x—— 起始与结束单元格列0 为最左列start_y/end_y—— 起始与结束行使用稳定行索引可通过pane:get_dimensions()获取当前有效的 scrollback 顶部与视口顶部稳定索引。区域内的文本会展开为逻辑行表示而非按物理显示宽度折行的形式。语义区域Semantic Zones操作语义区域依赖 shell integration见 shell-integration.md——即用OSC 133把输出标记为Prompt、Input和Output三种区域。启用后你可以据此实现“跳到上一条命令的提示符”“一键选中整段命令输出”等能力WezTerm 内置的ScrollToPrompt动作即基于此见 keyassignment/ScrollToPrompt.md。pane:get_semantic_zones([zone_type])自20230320-124340-559cb7b0起可用。省略zone_type时返回窗格内定义的全部语义区域列表指定时只返回该类型区域。zone_type合法取值为PromptInputOutputpane:get_semantic_zone_at(x, y)自20230320-124340-559cb7b0起可用。解析包裹给定x、y坐标的语义区域x为单元格列索引0 为最左列y为稳定行索引。配合get_cursor_position与get_text_from_semantic_zone可以取出当前光标所在命令区域的完整文本function get_zone_around_cursor(pane) local cursor pane:get_cursor_position() -- 用 x-1 是因为光标可能位于区域外一格 local zone pane:get_semantic_zone_at(cursor.x - 1, cursor.y) if zone then return pane:get_text_from_semantic_zone(zone) end return nil endpane:get_text_from_semantic_zone(zone)自20230320-124340-559cb7b0起可用。便捷方法内部即对传入的zone调用get_text_from_region()。zone对象可由get_semantic_zone_at()或get_semantic_zones()获取。元数据与状态感知pane:get_metadata()自20220903-194523-3bb1ed61起可用。返回关于窗格的元数据返回值取决于底层窗格实例不支持的窗格返回nil。建议用local meta pane:get_metadata() or {}兜底。可能的键如下。password_input仅本地窗格会填充的布尔值。当本地 PTY 似乎配置为密码输入模式本地回显关闭、规范输入模式开启时为true。示例——输入密码时把配色切换到夸张的红色系local wezterm require wezterm wezterm.on(update-status, function(window, pane) local meta pane:get_metadata() or {} local overrides window:get_config_overrides() or {} if meta.password_input then overrides.color_scheme Red Alert else overrides.color_scheme nil end window:set_config_overrides(overrides) end) return {}is_tardy仅 multiplexer 客户端窗格会填充的布尔值。当 WezTerm 正在等待 mux 服务器响应时为true常与since_last_response_ms配合。since_last_response_ms仅 multiplexer 客户端窗格会填充的整数。距最近一次 mux 服务器响应经过的毫秒数。示例——在状态栏显示 mux 延迟local wezterm require wezterm wezterm.on(update-status, function(window, pane) local meta pane:get_metadata() or {} if meta.is_tardy then local secs meta.since_last_response_ms / 1000.0 window:set_right_status(string.format(tardy: %5.1fs⏳, secs)) end end) return {}pane:has_unseen_output()自20220319-142410-0fcdea07起可用。若自该窗格上次被聚焦以来有新输出则返回true。类似的基于PaneInformation.has_unseen_output给标签页着色示例见 PaneInformation。pane:is_alt_screen_active()自20220807-113146-c2fee766起可用。返回该窗格的备用屏幕alternate screen是否激活。备用屏幕由特定转义码激活没有滚动缓冲适合vim、less这类全屏程序任意绘制而不破坏用户回滚退出时它们会发送转义码回到普通屏幕。pane:get_progress()nightly返回与窗格关联的进度状态。终端复位时默认为None。应用可用 ConEmu 风格的进度 OSC 序列改写它ESC ] 9 ; 4 ; st ; pr ST其中st的含义st行为Lua 端表示0进度设为NoneNone1进度值设为pr数字0-100{ Percentage pr }2设置错误状态pr可选缺省为 0{ Error pr }3设置不确定indeterminate状态Indeterminate4设置暂停状态pr可选WezTerm 不支持—处理该 OSC 后若状态有变化WezTerm 会触发标签栏更新进而触发format-tab-title等事件见 window-events/format-tab-title。WezTerm 本身不直接消费该进度信息但你可以在 Lua 中读取它来按进度定制标签样式。下面示例用 Nerd Font 圆形符号展示进度百分比并按成功/错误调整颜色local wezterm require wezterm local function tab_title(tab_info) local title tab_info.tab_title if title and #title 0 then return title end return tab_info.active_pane.title end local PCT_GLYPHS { wezterm.nerdfonts.md_circle_slice_1, wezterm.nerdfonts.md_circle_slice_2, wezterm.nerdfonts.md_circle_slice_3, wezterm.nerdfonts.md_circle_slice_4, wezterm.nerdfonts.md_circle_slice_5, wezterm.nerdfonts.md_circle_slice_6, wezterm.nerdfonts.md_circle_slice_7, wezterm.nerdfonts.md_circle_slice_8, } local function pct_glyph(pct) local slot math.floor(pct / 12) return PCT_GLYPHS[slot 1] end wezterm.on( format-tab-title, function(tab, tabs, panes, config, hover, max_width) local progress tab.active_pane.progress or None local title tab_title(tab) local elements { { Text string.format(%d: , tab.tab_index 1) }, } if progress ~ None then local color green local status if progress.Percentage ~ nil then status pct_glyph(progress.Percentage) elseif progress.Error ~ nil then status pct_glyph(progress.Error) color red elseif progress Indeterminate then status ~ else status wezterm.serde.json_encode(progress) end table.insert(elements, { Foreground { Color color } }) table.insert(elements, { Text status }) table.insert(elements, { Foreground Default }) end table.insert(elements, { Text .. title .. }) return elements end ) return wezterm.config_builder()pane:get_user_vars()自20210502-130208-bff6815d起可用。返回该窗格上已赋值的用户变量表。用户变量由 iterm2 定义的转义序列设置WezTerm 同样识别下面的 Bash 函数设置foobar该函数同样包含在 WezTerm 的 shell integration 脚本中见 shell-integration.md__wezterm_set_user_var() { if hash base64 2/dev/null ; then if [[ -z ${TMUX} ]] ; then printf \033]1337;SetUserVar%s%s\007 $1 echo -n $2 | base64 else printf \033Ptmux;\033\033]1337;SetUserVar%s%s\007\033\\ $1 echo -n $2 | base64 fi fi } __wezterm_set_user_var foo bar提示在 tmux 中传递该序列需要在 tmux.conf 中设置set -g allow-passthrough on。在配置中读取wezterm.log_info(foo var is .. pane:get_user_vars().foo)设置用户变量会在包含该窗格的窗口中触发事件user-var-changed可直接在变量变化时采取行动、update-status更新左右状态栏同时标题与标签栏区域会更新并触发相关事件。该变化会传播到所有已连接的 multiplexer 客户端。写入与发送输入、粘贴与注入pane:send_text(text)自20220624-141144-bd1b7c5d起可用。将文本原样发送到窗格。pane:send_paste(text)自20220624-141144-bd1b7c5d起可用。把text发送到窗格输入效果如同从剪贴板粘贴但不涉及剪贴板。换行符会依据canonicalize_pasted_newlines设置重写若窗格所连终端处于 bracketed paste 模式则文本以 bracketed paste 形式发送且换行符不会被重写。pane:paste(text)自20201031-154415-9614e117起可用。是send_paste的别名仅为兼容旧版本保留。pane:inject_output(text)自20221119-145034-49b9839f起可用。把文本可含转义序列发送到当前窗格的输出侧由终端仿真器解析执行因此可以用来强制终端处理修改当前模式的转义序列也可以直接向终端输出人可读文本。注意如果你用该方法移动了光标位置显示会随之改变并可能让文本 UI 程序混乱。示例——按ALTk向当前窗格输出斜体的hello therelocal wezterm require wezterm return { keys { { key k, mods ALT, action wezterm.action_callback(function(window, pane) pane:inject_output \r\n\x1b[3mhello there\r\n end), }, }, }并非所有窗格都支持此方法——目前本地窗格可用multiplexer 窗格不可用。分屏pane:split{}自20220624-141144-bd1b7c5d起可用。把pane分屏并在新窗格中启动程序返回新Pane对象local new_pane pane:split {}无参数时左右对半分右半屏运行默认程序。支持的参数如下。args指定要启动的命令参数数组省略则启动该 domain 的默认程序。pane:split { args { top } }cwd指定程序的工作目录省略时遵循default_cwd规则。pane:split { cwd /tmp }set_environment_variables为本次命令调用追加环境变量。pane:split { set_environment_variables { FOO BAR } }domain指定程序要派生到的 multiplexer domain。默认值为CurrentPaneDomain使用默认域。可指定配置中定义的域名pane:split { domain { DomainName my.name } }也可直接使用默认域pane:split { domain DefaultDomain }direction新窗格的放置方向可选值Right—— 左右分屏新窗格在右Left—— 左右分屏新窗格在左Top—— 上下分屏新窗格在上Bottom—— 上下分屏新窗格在下。pane:split { direction Top }top_level若为true不把pane对半切分而是切分其所在标签页让新窗格占据标签页的完整范围。pane:split { direction Bottom, top_level true }size控制新窗格大小数值小于1.0表示占可用空间的比例0.5即 50%大于等于1表示单元格数。默认值0.5。下面示例在pane内创建两次分割最终形成三个各占 1/3 的窗格pane:split { direction Top, size 0.333 } pane:split { direction Top, size 0.5 }从配置层看分屏能力也通过SplitPane动作暴露给键盘绑定其结构体定义于 config/src/keyassignment.rs即你可以在keys中使用act.SplitPane{...}达到等效效果。综合实战组合 Pane API 构建一个“一键导出会话”脚本将前述 API 组合起来可以实现一个相对完整的功能按下快捷键把当前窗格的完整回滚带样式导出为文件并在less中查看。其流程覆盖了get_dimensions()、get_lines_as_escapes()、wezterm.on事件与SpawnCommandInNewWindowlocal wezterm require wezterm local io require io local os require os local act wezterm.action wezterm.on(export-scrollback-to-less, function(window, pane) local dims pane:get_dimensions() local text pane:get_lines_as_escapes(dims.scrollback_rows) local name os.tmpname() local f io.open(name, w) f:write(text) f:flush() f:close() window:perform_action(act.SpawnCommandInNewWindow { args { less, -r, name } }, pane) wezterm.sleep_ms(1000) os.remove(name) end) return { keys { { key E, mods CTRL|SHIFT, action act.EmitEvent export-scrollback-to-less }, }, }类似地把get_lines_as_escapes换成get_lines_as_text即可得到纯文本版本适合直接导入编辑器、发邮件或交给其他 CLI 工具处理再结合get_user_vars、get_metadata与update-status事件就能打造出自定义的“会话感知状态栏”。小结Pane对象把 WezTerm 的窗格抽象成了 Lua 层一套统一、可编程的接口其核心实现位于 mux/src/pane.rs 的Panetrait导航与组织activate、move_to_new_tab、move_to_new_window、tab、window、pane_id、get_domain_name状态探查get_cursor_position、get_dimensions、get_title、get_tty_name、has_unseen_output、is_alt_screen_active、get_progress、get_metadata、get_user_vars工作目录与进程get_current_working_dir、get_foreground_process_info、get_foreground_process_name文本读取get_lines_as_text、get_lines_as_escapes、get_logical_lines_as_text、get_text_from_region、get_semantic_zones、get_semantic_zone_at、get_text_from_semantic_zone写入send_text、send_paste、paste、inject_output、split。掌握了这五类方法你就拥有了从事件回调中读取、操作和扩展任意窗格状态的完整工具箱可以据此实现状态栏增强、回滚导出、密码感知配色、mux 延迟监控、进度标签等高级定制。【免费下载链接】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），仅供参考