wterm Web终端输入处理详解鼠标追踪、Kitty键盘协议与中文输入法组合【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wtermwterm 是一个面向 Web 的开源终端模拟器其核心用 Zig 编写并编译为 WASMDOM 层则负责渲染与全部输入处理。本文带你快速看懂 wterm 的 Web 终端输入处理三大核心能力鼠标追踪Mouse Tracking、Kitty 键盘协议与中文输入法IME组合帮你理解浏览器环境下的按键、鼠标事件如何被准确转发给终端应用。为什么 Web 终端的输入处理是难点 在浏览器里运行终端输入链路和桌面终端完全不同键盘事件由KeyboardEvent描述但浏览器拿不到物理键位的完整信息不同布局如欧洲 AltGr 布局还会让同一个键产生不同含义鼠标坐标是 CSS 像素而终端应用期望的是第几行第几列需要逐像素换算成网格坐标中文等输入法有组合中和上屏两个阶段未确认的拼音不能直接发给终端。wterm 的输入逻辑集中在 input.ts 中的InputHandler类配合 kitty-keys.ts 完成协议编码。鼠标追踪5 种编码格式与坐标换算当 Vim、htop、Tmux 等应用开启鼠标模式1000 点击 / 1002 拖拽 / 1003 全量运动后wterm 会把鼠标事件按应用当前选择的编码格式上报共支持X10、UTF-81005、SGR1006、urxvt1015、SGR 像素1016五种。关键实现位于 handleMouse()坐标换算先取终端视口首行的位置与单元格宽高再把clientX/clientY换算为 1 起始的行列号或 CSS 像素1016 模式见 坐标计算片段修饰键位Shift / Alt / Ctrl 分别对应 4 / 8 / 16运动事件额外加 32滚轮事件用 64–67 区分方向X10 二进制通道X10 编码可能产生非 ASCII 字节wterm 通过可选的onBinary回调原样送出避免被 UTF-8 编码破坏无法表示的坐标会跳过而不是报错。一些贴心的细节场景wterm 的行为在回滚区scrollback上滚动保留给浏览器继续翻历史直到回到底部鼠标追踪开启时翻历史按住 Shift 滚轮即可在实时视口外查看历史1003 模式未按键运动每跨一个单元格上报一次像素模式每跨一个像素一次对应行为可在 input-mouse.test.ts 与 e2e 用例 mouse-motion.spec.ts 中验证。Kitty 键盘协议让每个按键都可分辨传统 CSI 序列分不清Ctrla字符与CtrlBackspace控制键也区分不了左右 Alt 同时按住时按 a。Kitty 键盘协议通过协商标志位解决这一问题wterm 内置核心与 Ghostty 核心均支持查询、push/pop、set、OR/NOT 等操作。wterm 在 kitty-keys.ts 定义了四个核心标志KITTY_REPORT_EVENTS11上报 press / repeat / release 事件类型KITTY_REPORT_ALTERNATES12上报 Shift 产生的替代表意字符KITTY_REPORT_ALL13全量按键上报含修饰键自身KITTY_REPORT_ASSOCIATED14附带按键关联文本解决多键盘布局歧义编码入口是 encodeKittyKey()其策略很清晰无修饰键的普通字符直接走原生文本路径不占用协议序列功能键与修饰组合才生成CSI 1;mod:eventType u形式的序列兼容回退未开启全量上报时CtrlAlt组合仍可用旧式 xterm 序列表达保证老应用行为不变。在 handleKeyDown() 中可以看到两条路径的分叉kittyKeyboardFlags()非零时走 Kitty 编码L378-L394否则回退到 xterm 风格的keyToSequence。另一个亮点是AltGr 智能直通当浏览器能识别 AltGr 产生的可打印字符时wterm 放行原生输入让欧洲布局用户即使在 Kitty 模式下也能正常输入特殊字符见 isAltGraphTextInput()。中文输入法组合候选字确认后才会发送对中文用户来说最关键的体验是打拼音时的中间态不会发给终端只有确认上屏的文字才会送达。wterm 的实现基于浏览器原生的compositionstart/compositionend事件组合开始handleCompositionStart()把透明的输入框textarea定位到终端光标处此时输入框可见拼音暂存在浏览器输入框中候选窗也自然贴近光标按键屏蔽组合期间的 keydown 事件全部跳过L321-L325防止拼音按键被误编码成控制序列组合结束handleCompositionEnd()通过e.data拿到确认文本后发送并记录提交时间与内容去重保护部分浏览器会在compositionend后又触发一次携带相同文本的input事件wterm 用 COMPOSITION_INPUT_DEDUP_MS 250 毫秒窗口 文本比对L579-L586过滤重复避免中文被发送两遍自动回到底部如果在阅读历史输出时开始输入wterm 会把视口拉回实时区域让输入文本与候选窗保持在光标附近。端到端的中文输入行为由 ime.spec.ts 持续回归协议层单测在 kitty-keys.test.ts。输入处理模块速查表 能力核心文件键盘 / 鼠标 / IME / 触摸总入口packages/wterm/dom/src/input.tsKitty 协议编码packages/wterm/dom/src/kitty-keys.ts粘贴与括号粘贴防 ESC 注入sendPaste()输入 API 与行为说明packages/wterm/dom/README.md鼠标 / 触摸 / IME 单测packages/wterm/dom/src/__tests__/e2e 输入回归鼠标、IME、触摸e2e/harness/tests/小结wterm 把浏览器输入与终端协议之间的翻译工作做得到位鼠标事件按 5 种编码精准换算为行列坐标Kitty 键盘协议在兼容旧应用的前提下消除了按键歧义中文输入法则严格遵循组合中不发送、上屏才送达的原则并加了去重保护。如果你想深入阅读建议从 input.ts 的handleKeyDown与handleMouse两个方法入手再对照 README.md 中鼠标与键盘章节的逐条说明就能完整掌握这套 Web 终端输入处理的精髓。【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考