在浏览器终端里显示图片：wterm Kitty图像协议与Canvas覆盖层实战

在浏览器终端里显示图片wterm Kitty图像协议与Canvas覆盖层实战【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wtermwterm 是一个面向 Web 的终端模拟器terminal emulator for the web核心用 Zig 编写并编译为约 26 KB 的 WASM渲染层直接落在 DOM 上。它通过Ghostty 内核 Canvas 覆盖层实现了 Kitty 图像协议Kitty Graphics Protocol让你在浏览器里直接显示 PNG / RGB / RGBA 图片——配合kitten icat等工具即可体验完整的流式图片传输。什么是 Kitty 图像协议浏览器终端为什么需要它传统终端只认字符。想在终端里看图历史上要么用 Sixel 这种私有协议要么用 Unicode 块字符“拼”出图效果很差。Kitty 终端提出的 Kitty Graphics Protocol 是目前的事实标准应用通过一组转义序列把图片数据支持直接传输 PNG、RGB、RGBA或文件、共享内存引用“推送”到终端终端负责解码并在屏幕上摆放。主流本地终端如 Kitty、Ghostty、WezTerm 都已支持。对浏览器终端来说难点在于像素不是文本不能塞进字符网格图片会随滚动、resize、主/备屏切换而移动必须防止恶意输出耗尽浏览器内存。wterm 的方案是内核负责协议解码DOM 层用一个独立的 Canvas 覆盖层负责绘制两者解耦。快速上手启用 Kitty 图片渲染wterm 采用可插拔内核设计。内置的轻量 Zig 内核会安全地消费 Kitty APC 数据但不渲染图片要显示图片需要换用wterm/ghostty内核基于 libghostty 编译全 VT 特性详见 ghostty 包说明。import { WTerm } from wterm/dom; import { GhosttyCore } from wterm/ghostty; const core await GhosttyCore.load(); const term new WTerm(document.getElementById(terminal), { core, maxImageWidth: 640, // 渲染宽度上限CSS 像素 maxImageHeight: 480, // 渲染高度上限 }); await term.init();React、Vue、Svelte 绑定同样支持core、maxImageWidth、maxImageHeight三个属性框架切换零成本。完整接入示例见 Ghostty 文档和 React 文档。 一个细节WTerm会从浏览器视口回答 Kitty 的像素几何查询CSI 14 t/CSI 16 t所以kitten icat --transfer-modestream image.png可以在传输前协商好显示尺寸避免传回一张远超屏幕的大图。Canvas 覆盖层wterm 如何把图片画进终端核心绘制逻辑集中在 GraphicsLayer 类中工作机制值得初学者了解独立图层容器内创建.term-images图层和.term-image-flow-spacer占位元素图层设置aria-hidden、不可聚焦、鼠标穿透不干扰文本选区、复制、键盘输入和无障碍行为按需绘制每帧从内核读取归一化的图形状态getGraphicsState()和可见图片像素getGraphicsImage()只对可见区域内的 pinned 摆位创建或复用 Canvas离屏的图片立刻释放缓存复用同一张图被多个摆位引用时共享一份解码数据通过引用计数自动回收内存护栏所有可见 Canvas 的 backing store 共享32 MiB预算且单张 Canvas 不超过 32768 像素边长超限的摆位直接跳过绝不允许终端输出任意决定浏览器内存。┌─ 终端容器 ─────────────────────────┐ │ 文本行DOM负责选区/复制/无障碍 │ │ ┌──────────┐ │ │ │ Canvas │ ← 覆盖层鼠标穿透 │ │ └──────────┘ │ └──────────────────────────────────┘图片跟随滚动视口、scrollback 与提示符排布Canvas 覆盖层最常见的翻车点是“图片不跟滚动走”。wterm 的处理跟随滚动与 resize每帧根据视口scrollTop、rowHeight、charWidth等重新定位 Canvasscrollback 中的图片在滚回可见区时会重新挂载滚出即卸载主/备屏切换切换vim/less使用的备用屏时图形状态整体失效覆盖层同步清空提示符不被图片盖住⭐自动尺寸implicit摆位在元数据中占据 0 行内核的光标仍会前进。wterm 通过 reconcileFlowReservations 在视觉 DOM 流中为图片预留渲染高度保证图片下方的 shell 提示符始终显示在图片下面而不是被“画穿”。关键配置限制图片大小与内存占用选项作用默认值maxImageWidth/maxImageHeight渲染尺寸上限CSS 像素只等比缩小、不放大不限imageStorageLimit每屏解码后的 Kitty 图片字节预算设为0可整体关闭图形32 MiBCanvas 总预算所有可见 Canvas 共享32 MiB固定护栏对应源码ghostty-core.ts、graphics-layer.ts。图形内核的契约定义getGraphicsState/getGraphicsImage可选方法见 core 包文档与 API 参考。支持边界哪些图片能用哪些不行明确边界有助于合理选型 ✅支持direct 传输的 PNG / RGB / RGBA 图片含自动尺寸stream摆位❌不支持Sixel、iTerm2/OSC 1337、动画、虚拟 Unicode 摆位、文件 / 共享内存 / URL 类媒体、图片持久化图片随屏幕状态是瞬态的被清屏即消失。非 direct 媒体会在触碰文件或共享内存之前被拒绝——这是浏览器安全的重要考量。相关文件与延伸阅读覆盖层绘制实现graphics-layer.tsGhostty 内核协议解码 WASM 补丁packages/wterm/ghostty/构建补丁说明见 README官方文档Ghostty 内核、原生 JS 集成、配置项端到端测试参考e2e 测试集总结wterm 用“Ghostty 内核解码 Canvas 覆盖层绘制 双重内存预算”的组合拳把 Kitty 图像协议完整搬进了浏览器且滚动跟随、提示符排布等体验细节都做了处理——如果你在做一个 Web IDE、SSH 网关或在线实验室这就是开箱即用的浏览器终端图片方案。【免费下载链接】wtermA terminal emulator for the web项目地址: https://gitcode.com/gh_mirrors/wterm1/wterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考