` 光标位置 API 详解)
WezTerm 开发实战pane:get_cursor_position()光标位置 API 详解【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermpane:get_cursor_position()是 WezTerm 暴露给 Lua 脚本的光标状态查询接口它返回当前 pane窗格中终端光标的稳定坐标、形状与可见性常用于快速选择、复制粘贴、滚动条渲染、状态栏定制等场景。本文将基于官方文档并结合 WezTerm 仓库源码完整讲解该 API 的返回值结构、字段语义、底层实现与实战用法帮助你直接在 wezterm.lua 配置中调用它。一、API 总览pane:get_cursor_position()在 WezTerm 的 Lua API 中属于pane对象的方法从版本20201031-154415-9614e117开始提供。调用它不需要任何参数返回一个表示StableCursorPosition结构的 Lua 表用来标识光标的水平位置x垂直位置y形状shape可见性visibility它和pane:get_dimensions()、pane:get_lines_as_text()、pane:has_unseen_output()等 API 同属 pane 对象的方法族在 lua-api-crates/mux/src/pane.rs 中统一注册供 wezterm.lua 与插件调用。二、返回值字段详解返回值是一个 Lua 表包含四个字段字段类型含义xnumber光标的水平单元格索引cell index从 0 开始ynumber光标的垂直稳定行索引stable row indexshapeenum string光标的形状对应CursorShape枚举visibilityenum string光标的可见性对应CursorVisibility枚举1.x水平单元格索引x表示光标所在列以单元格cell为单位从 0 开始计数。它表示终端渲染网格中的列位置而不是像素坐标如果要把光标渲染到屏幕上还需要结合字体度量、单元格宽度等参数换算。在 mux/src/renderable.rs 中StableCursorPosition结构体的定义为pub struct StableCursorPosition { pub x: usize, pub y: StableRowIndex, pub shape: termwiz::surface::CursorShape, pub visibility: termwiz::surface::CursorVisibility, }这里x的类型是usize无符号整数所以它不会是负数。2.y稳定行索引y是光标的稳定行索引StableRowIndex这是 WezTerm 中一个重要的概念。终端屏幕带有滚动缓冲区scrollback普通可视行号会随着滚动而漂移而稳定行索引是从滚动缓冲顶部开始的绝对行号不会因为视图滚动而改变。从 mux/src/renderable.rs 的terminal_get_cursor_position函数可以看到这种换算的实现pub fn terminal_get_cursor_position(term: mut Terminal) - StableCursorPosition { let pos term.cursor_pos(); StableCursorPosition { x: pos.x, y: term.screen().visible_row_to_stable_row(pos.y), shape: pos.shape, visibility: pos.visibility, } }关键一步是term.screen().visible_row_to_stable_row(pos.y)终端内部记录的是可视行号pos.y通过visible_row_to_stable_row将其转换为稳定行号再返回给 Lua。这意味着y的值是全局滚动上下文中的行号而不是当前视口内的相对行号。这一点在实现跳转到光标所在行计算光标距视口顶部距离等场景时非常关键。3.shape光标形状shape返回CursorShape枚举值。在 wezterm-surface/src/lib.rs 中定义如下pub enum CursorShape { Default, BlinkingBlock, SteadyBlock, BlinkingUnderline, SteadyUnderline, BlinkingBar, SteadyBar, }也就是说shape可能的取值包括Default默认形状BlinkingBlock闪烁的方块SteadyBlock常亮的方块BlinkingUnderline闪烁的下划线SteadyUnderline常亮的下划线BlinkingBar闪烁的竖条SteadyBar常亮的竖条这些形状通常由终端控制序列如 DECSCUSR或用户的cursor_style配置决定。该枚举还提供了is_blinking()方法判断是否为闪烁形态从源码可以推断Blinking*前缀的三个变体都返回true。4.visibility光标可见性visibility返回CursorVisibility枚举值定义于 wezterm-surface/src/lib.rspub enum CursorVisibility { Hidden, Visible, }可能的取值只有Hidden隐藏和Visible可见两种。某些全屏应用如 vim 在特定模式下、TUI 程序切换 alt screen 时会隐藏光标此时visibility即为Hidden。三、调用方式与 Lua 绑定在 Lua 中通过 pane 对象直接调用即可local pos pane:get_cursor_position() wezterm.log_info(string.format( cursor at x%s y%s shape%s visibility%s, pos.x, pos.y, pos.shape, pos.visibility ))该方法的 Lua 绑定注册在 lua-api-crates/mux/src/pane.rsmethods.add_method(get_cursor_position, |_, this, _: ()| { let mux get_mux()?; let pane this.resolve(mux)?; Ok(pane.get_cursor_position()) });从绑定代码可以看出方法签名固定为无参数_: ()内部通过get_mux()获取 mux 实例this.resolve(mux)把 Lua 侧传入的 pane 对象解析为具体的 pane 实现返回值通过impl_lua_conversion_dynamic!(StableCursorPosition)自动转换为 Lua 表见 mux/src/renderable.rs 中的宏调用因此结构体字段名与 Lua 表字段一一对应。这也解释了为什么在任何配置上下文如 key assignment、event handler、自定义函数中拿到 pane 对象后都能零依赖地调用该方法。四、仓库中的实际应用示例get_cursor_position在 WezTerm 仓库内部多处被使用这些使用方式对编写自己的配置非常有参考价值。1. 快速选择QuickSelect与复制覆盖层wezterm-gui/src/overlay/quickselect.rs 与 wezterm-gui/src/overlay/copy.rs 中覆盖层overlay渲染时都需要把光标位置固定到正确的地方覆盖层关闭后再将光标恢复到原位置。其内部通过记录光标位置并在 overlay 生命周期内恢复来实现。2. 光标渲染与 prevcursor 追踪wezterm-gui/src/termwindow/render/pane.rs 在渲染 pane 时读取StableCursorPosition来决定光标绘制位置而 wezterm-gui/src/termwindow/prevcursor.rs 定义了一个专门保存上一个光标位置的结构体pub struct PrevCursorPos { pos: StableCursorPosition, }其update(mut self, newpos: StableCursorPosition)方法会在每次渲染时记录新的光标位置用于实现光标移动时只重绘受影响区域的优化。从源码结构可以推断正因为StableCursorPosition是CopyEq的轻量结构体才能在渲染管线中被频繁地传递、比较和缓存。3. 多路复用协议中的传输在 codec/src/lib.rs 中cursor_position: StableCursorPosition作为 mux 协议消息Renderable相关消息的一个字段被序列化传输在 wezterm-client/src/pane/clientpane.rs 中远端 pane 的光标位置信息会被解析出来供本地渲染使用。这意味着即使运行在远端如 SSH、tmux domain 场景Lua 中拿到的光标位置依然与本地渲染保持一致。五、实战在 wezterm.lua 中定制光标信息展示下面是一个完整的实战示例注册update-right-status事件在右侧状态栏实时显示当前 pane 的光标位置与形态。local wezterm require wezterm local config {} -- 光标形状的中文/可读名称映射 local shape_names { Default def, BlinkingBlock blk*, SteadyBlock blk, BlinkingUnderline uln*, SteadyUnderline uln, BlinkingBar bar*, SteadyBar bar, } wezterm.on(update-right-status, function(window, pane) local pos pane:get_cursor_position() local shape shape_names[pos.shape] or pos.shape local vis pos.visibility Visible and on or off window:set_right_status(wezterm.format { { Foreground { AnsiColor Blue } }, { Text string.format(⯇ %d:%d %s/%s, pos.x, pos.y, shape, vis) }, }) end) return config关键点update-right-status回调中可以直接拿到pane对象无需额外查表pos.shape与pos.visibility是枚举对应的字符串可以直接用于比较如上面pos.visibility Visiblex、y是数字可参与算术运算例如计算光标距视口首行的距离时需结合pane:get_dimensions()的viewport_rows与稳定行换算注意y是全局稳定行号而非视口内相对行号。六、注意事项与边界y是稳定行索引不要把它当作视口内的行号直接用于渲染计算需要时请结合pane:get_dimensions()返回的scrollback_top做差值换算。无参数调用调用时不要传参数传入参数会导致类型不匹配报错。版本前提该 API 自20201031-154415-9614e117版本起可用更早版本调用会失败。返回值是副本语义返回的是结构体的 Lua 表拷贝修改返回的pos表不会影响终端内部状态如果你需要恢复光标位置建议自己保存x/y并在合适时机通过pane:send_paste或相关 escape sequence 方式处理。七、进一步阅读方法绑定注册位置lua-api-crates/mux/src/pane.rs结构体定义与稳定行换算实现mux/src/renderable.rs光标形状与可见性枚举定义wezterm-surface/src/lib.rs光标渲染与位置追踪wezterm-gui/src/termwindow/render/pane.rs、wezterm-gui/src/termwindow/prevcursor.rs多路复用协议中的光标位置字段codec/src/lib.rs、wezterm-client/src/pane/clientpane.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 开发实战pane:get_cursor_position()光标位置 API 详解【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermpane:get_cursor_position()是 WezTerm 暴露给 Lua 脚本的光标状态查询接口它返回当前 pane窗格中终端光标的稳定坐标、形状与可见性常用于快速选择、复制粘贴、滚动条渲染、状态栏定制等场景。本文将基于官方文档并结合 WezTerm 仓库源码完整讲解该 API 的返回值结构、字段语义、底层实现与实战用法帮助你直接在 wezterm.lua 配置中调用它。一、API 总览pane:get_cursor_position()在 WezTerm 的 Lua API 中属于pane对象的方法从版本20201031-154415-9614e117开始提供。调用它不需要任何参数返回一个表示StableCursorPosition结构的 Lua 表用来标识光标的水平位置x垂直位置y形状shape可见性visibility它和pane:get_dimensions()、pane:get_lines_as_text()、pane:has_unseen_output()等 API 同属 pane 对象的方法族在 lua-api-crates/mux/src/pane.rs 中统一注册供 wezterm.lua 与插件调用。二、返回值字段详解返回值是一个 Lua 表包含四个字段字段类型含义xnumber光标的水平单元格索引cell index从 0 开始ynumber光标的垂直稳定行索引stable row indexshapeenum string光标的形状对应CursorShape枚举visibilityenum string光标的可见性对应CursorVisibility枚举1.x水平单元格索引x表示光标所在列以单元格cell为单位从 0 开始计数。它表示终端渲染网格中的列位置而不是像素坐标如果要把光标渲染到屏幕上还需要结合字体度量、单元格宽度等参数换算。在 mux/src/renderable.rs 中StableCursorPosition结构体的定义为pub struct StableCursorPosition { pub x: usize, pub y: StableRowIndex, pub shape: termwiz::surface::CursorShape, pub visibility: termwiz::surface::CursorVisibility, }这里x的类型是usize无符号整数所以它不会是负数。2.y稳定行索引y是光标的稳定行索引StableRowIndex这是 WezTerm 中一个重要的概念。终端屏幕带有滚动缓冲区scrollback普通可视行号会随着滚动而漂移而稳定行索引是从滚动缓冲顶部开始的绝对行号不会因为视图滚动而改变。从 mux/src/renderable.rs 的terminal_get_cursor_position函数可以看到这种换算的实现pub fn terminal_get_cursor_position(term: mut Terminal) - StableCursorPosition { let pos term.cursor_pos(); StableCursorPosition { x: pos.x, y: term.screen().visible_row_to_stable_row(pos.y), shape: pos.shape, visibility: pos.visibility, } }关键一步是term.screen().visible_row_to_stable_row(pos.y)终端内部记录的是可视行号pos.y通过visible_row_to_stable_row将其转换为稳定行号再返回给 Lua。这意味着y的值是全局滚动上下文中的行号而不是当前视口内的相对行号。这一点在实现跳转到光标所在行计算光标距视口顶部距离等场景时非常关键。3.shape光标形状shape返回CursorShape枚举值。在 wezterm-surface/src/lib.rs 中定义如下pub enum CursorShape { Default, BlinkingBlock, SteadyBlock, BlinkingUnderline, SteadyUnderline, BlinkingBar, SteadyBar, }也就是说shape可能的取值包括Default默认形状BlinkingBlock闪烁的方块SteadyBlock常亮的方块BlinkingUnderline闪烁的下划线SteadyUnderline常亮的下划线BlinkingBar闪烁的竖条SteadyBar常亮的竖条这些形状通常由终端控制序列如 DECSCUSR或用户的cursor_style配置决定。该枚举还提供了is_blinking()方法判断是否为闪烁形态从源码可以推断Blinking*前缀的三个变体都返回true。4.visibility光标可见性visibility返回CursorVisibility枚举值定义于 wezterm-surface/src/lib.rspub enum CursorVisibility { Hidden, Visible, }可能的取值只有Hidden隐藏和Visible可见两种。某些全屏应用如 vim 在特定模式下、TUI 程序切换 alt screen 时会隐藏光标此时visibility即为Hidden。三、调用方式与 Lua 绑定在 Lua 中通过 pane 对象直接调用即可local pos pane:get_cursor_position() wezterm.log_info(string.format( cursor at x%s y%s shape%s visibility%s, pos.x, pos.y, pos.shape, pos.visibility ))该方法的 Lua 绑定注册在 lua-api-crates/mux/src/pane.rsmethods.add_method(get_cursor_position, |_, this, _: ()| { let mux get_mux()?; let pane this.resolve(mux)?; Ok(pane.get_cursor_position()) });从绑定代码可以看出方法签名固定为无参数_: ()内部通过get_mux()获取 mux 实例this.resolve(mux)把 Lua 侧传入的 pane 对象解析为具体的 pane 实现返回值通过impl_lua_conversion_dynamic!(StableCursorPosition)自动转换为 Lua 表见 mux/src/renderable.rs 中的宏调用因此结构体字段名与 Lua 表字段一一对应。这也解释了为什么在任何配置上下文如 key assignment、event handler、自定义函数中拿到 pane 对象后都能零依赖地调用该方法。四、仓库中的实际应用示例get_cursor_position在 WezTerm 仓库内部多处被使用这些使用方式对编写自己的配置非常有参考价值。1. 快速选择QuickSelect与复制覆盖层wezterm-gui/src/overlay/quickselect.rs 与 wezterm-gui/src/overlay/copy.rs 中覆盖层overlay渲染时都需要把光标位置固定到正确的地方覆盖层关闭后再将光标恢复到原位置。其内部通过记录光标位置并在 overlay 生命周期内恢复来实现。2. 光标渲染与 prevcursor 追踪wezterm-gui/src/termwindow/render/pane.rs 在渲染 pane 时读取StableCursorPosition来决定光标绘制位置而 wezterm-gui/src/termwindow/prevcursor.rs 定义了一个专门保存上一个光标位置的结构体pub struct PrevCursorPos { pos: StableCursorPosition, }其update(mut self, newpos: StableCursorPosition)方法会在每次渲染时记录新的光标位置用于实现光标移动时只重绘受影响区域的优化。从源码结构可以推断正因为StableCursorPosition是CopyEq的轻量结构体才能在渲染管线中被频繁地传递、比较和缓存。3. 多路复用协议中的传输在 codec/src/lib.rs 中cursor_position: StableCursorPosition作为 mux 协议消息Renderable相关消息的一个字段被序列化传输在 wezterm-client/src/pane/clientpane.rs 中远端 pane 的光标位置信息会被解析出来供本地渲染使用。这意味着即使运行在远端如 SSH、tmux domain 场景Lua 中拿到的光标位置依然与本地渲染保持一致。五、实战在 wezterm.lua 中定制光标信息展示下面是一个完整的实战示例注册update-right-status事件在右侧状态栏实时显示当前 pane 的光标位置与形态。local wezterm require wezterm local config {} -- 光标形状的中文/可读名称映射 local shape_names { Default def, BlinkingBlock blk*, SteadyBlock blk, BlinkingUnderline uln*, SteadyUnderline uln, BlinkingBar bar*, SteadyBar bar, } wezterm.on(update-right-status, function(window, pane) local pos pane:get_cursor_position() local shape shape_names[pos.shape] or pos.shape local vis pos.visibility Visible and on or off window:set_right_status(wezterm.format { { Foreground { AnsiColor Blue } }, { Text string.format(⯇ %d:%d %s/%s, pos.x, pos.y, shape, vis) }, }) end) return config关键点update-right-status回调中可以直接拿到pane对象无需额外查表pos.shape与pos.visibility是枚举对应的字符串可以直接用于比较如上面pos.visibility Visiblex、y是数字可参与算术运算例如计算光标距视口首行的距离时需结合pane:get_dimensions()的viewport_rows与稳定行换算注意y是全局稳定行号而非视口内相对行号。六、注意事项与边界y是稳定行索引不要把它当作视口内的行号直接用于渲染计算需要时请结合pane:get_dimensions()返回的scrollback_top做差值换算。无参数调用调用时不要传参数传入参数会导致类型不匹配报错。版本前提该 API 自20201031-154415-9614e117版本起可用更早版本调用会失败。返回值是副本语义返回的是结构体的 Lua 表拷贝修改返回的pos表不会影响终端内部状态如果你需要恢复光标位置建议自己保存x/y并在合适时机通过pane:send_paste或相关 escape sequence 方式处理。七、进一步阅读方法绑定注册位置lua-api-crates/mux/src/pane.rs结构体定义与稳定行换算实现mux/src/renderable.rs光标形状与可见性枚举定义wezterm-surface/src/lib.rs光标渲染与位置追踪wezterm-gui/src/termwindow/render/pane.rs、wezterm-gui/src/termwindow/prevcursor.rs多路复用协议中的光标位置字段codec/src/lib.rs、wezterm-client/src/pane/clientpane.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），仅供参考
