# @bomb\.sh/tty 中文文档

规范地址：https://npmcn.com/package/%40bomb.sh/tty/

版本：0\.10\.0
npm 元数据更新时间：2026-10-21T19:51:05.148Z
中文译文更新时间：2026-11-08T10:43:10.493Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bomb.sh/tty
原文对照：https://npmcn.com/package/%40bomb.sh/tty/?lang=original
项目主页：https://github.com/bombshell-dev/tty#readme
源码仓库：https://github.com/bombshell-dev/tty

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：140 kB，27 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>= 22
- 运行依赖：0 个
- 首次发布：2026-06-18T20:24:58.205Z
- 最新版本发布：2026-10-21T19:51:04.647Z
- 近 30 天下载量：36264（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

用于 Clay 的终端渲染后端, 编译为 Web Assembly

## 安装

```sh
npm install @bomb.sh/tty
```

也可以使用：`pnpm add @bomb.sh/tty`、`yarn add @bomb.sh/tty`、`bun add @bomb.sh/tty`

## README

# @bomb.sh/tty (英语)

一个低等、平台独立的终端渲染器和事件解析器 Java脚本. 你用得着 `@bomb.sh/tty` 直接,或作为您的基础 拥有的框架.

## 特征

**宣告终端 UI** ——以你构建的方式构建终端接口 a 网页. `@bomb.sh/tty` 用途 [克莱](https://github.com/nicbarker/clay) 下级 引擎盖, 给你类似弹性盒的布局, 指针检测和滚动 集装箱——全部作为箱面绘图字符和ANSI 提供给终端 逃脱序列.

**无 I/ 欧** —— 说 `@bomb.sh/tty` 从不读 Stdin 或写 stdout 。 你喂饱它 字节并获得字节回. 这使得它微不足道地嵌入任何框架, 任何运行时间,任何事件循环。 你如何做 I/O没有意见,只是 纯计算.

**到处跑** 整个引擎被编译到WebAssembly,所以 `@bomb.sh/tty` 将运行在 JavaScript 运行的任何地方, 没有本地依赖, 也不给消费者任何建设步骤.

### 实例

参见此键盘示例和更多 [示例文件夹](https://npmcn.com/package/%40bomb.sh/tty/examples/README.md)。 。 。 . 此演示使用 `@bomb.sh/tty` 用于所有布局和输入解析.

#### 键盘事件

输入解码器将原始终端字节解码为结构化事件. 给你 将每个关键事件作为字符串“你好世界”键入.

![Keyboard events demo](https://npmcn.com/package/%40bomb.sh/tty/examples/keyboard/keyboard-key-events.gif)

#### 指针事件

在这里,我们看到针对指针的UI元素应用的悬浮样式 状态。 Clay驱动命中测试;不需要手动坐标数学.

![Pointer events demo](https://npmcn.com/package/%40bomb.sh/tty/examples/keyboard/keyboard-pointer-events.gif)

## 建筑

`@bomb.sh/tty` 没有做任何I/O本身。 在自动侧面,它转换UI 元素进入字节和指针事件的生序,在输入边, 它将一串生字节的流转换成结构化的事件.

### 产出

每个框,整个UI树被打包成平整字节数组并发送 给WASM的电话。 C方面,克莱运行布局,渲染命令是 走入了细胞缓冲器,缓冲器被分解出与上个帧相对. 只有实际改变的单元格产生输出. 结果是一个ANSI 可以直接写入 stdout 的逃生序列 。 每趟去WASM的旅行 帧, 双缓冲, 只有需要更改的字节键击中输出 流线.

因为WASM模块是纯粹的计算,没有I/O,它运行在任何地方 WebAssembly does: Deno, Node, Bun,浏览器,或任何其他运行时间.

```
 TypeScript                        WASM (C)
+---------------+                +---------------------------+
|               |  Uint32Array   |                           |
| UI ops...     | =============> | Clay layout               |
|               |                |   -> render commands      |
+---------------+                |   -> cell buffer (back)   |
                                 |   -> diff against (front) |
                                 |   -> escape bytes         |
+---------------+                |                           |
|               | ANSI byte array|                           |
| stdout.write  | <============= |                           |
|               |                |                           |
+---------------+                +---------------------------+
```

### 投入

来自 stdin 的 Raw 字节输入到基于 WASM 的解析器中,该解析器会识别 VT/ ANSI 逃脱序列,UTF-8代码点,以及鼠标协议(VT200,SGR,urxvt). 这个 parser 维护自己的内部缓冲, 这样部分序列会到达 读取边界自动重新组合。 一个单独的ESC字节为 释放前可配置的耐用窗口(默认为 25ms) 多字节序列时间即将到来.

```
 TypeScript                        WASM (C)
+---------------+                +---------------------------+
|               |  raw byte array|                           |
| stdin.read    | =============> | trie match (keys/seqs)    |
|               |                |   -> mouse protocol       |
|               |                |   -> UTF-8 decode         |
+---------------+                |   -> ESC codes            |
                                 |                           |
+---------------+                |                           |
|               |  events[]      |                           |
| KeyEvent      | <============= |                           |
| MouseDownEvent|                |                           |
| MouseUpEvent  |                +---------------------------+
| MouseMoveEvent|
| WheelEvent    |
| ResizeEvent   |
+---------------+
```

## 使用量

### 渲染

为此:

```
╭───────────────╮
│ Hello, World! │
╰───────────────╯
```

```typescript
import { close, createTerm, open, rgba, text } from "@bomb.sh/tty";

let term = await createTerm({ width: 80, height: 24 });

let { output } = term.render([
  open("greeting", {
    layout: { padding: { left: 1, right: 1, top: 1, bottom: 1 } },
    border: {
      color: rgba(0, 255, 0),
      left: 1,
      right: 1,
      top: 1,
      bottom: 1,
    },
    cornerRadius: { tl: 1, tr: 1, bl: 1, br: 1 },
  }),
  text("Hello, World!"),
  close(),
]);

process.stdout.write(output);
```

### 指针检测

通过指针状态 `render()` 拥有 `@bomb.sh/tty` 进行命中检测 除字节序列外的返回指针事件.

```typescript
import { close, createTerm, fixed, grow, open, rgba, text } from "@bomb.sh/tty";

let term = await createTerm({ width: 80, height: 24 });

let { output, events } = term.render(
  [
    open("root", {
      layout: { width: grow(), height: grow(), direction: "ltr" },
    }),
    open("sidebar", {
      layout: { width: fixed(20), height: grow() },
      bg: rgba(30, 30, 40),
    }),
    text("Sidebar"),
    close(),
    open("main", {
      layout: { width: grow(), height: grow() },
    }),
    text("Main content"),
    close(),
    close(),
  ],
  {
    pointer: { x: mouseX, y: mouseY, down: mouseDown },
  },
);

for (let event of events) {
  // { type: "pointerenter", id: "sidebar" }
  // { type: "pointerleave", id: "sidebar" }
  // { type: "pointerclick", id: "main" }
  console.log(event);
}

process.stdout.write(output);
```

### 输入解析

```typescript
import { createInput } from "@bomb.sh/tty";

let input = await createInput({ escLatency: 25 });

process.stdin.setRawMode(true);
let timer: ReturnType<typeof setTimeout> | undefined;

process.stdin.on("data", (buf) => {
  clearTimeout(timer);

  let { events, pending } = input.scan(new Uint8Array(buf));

  for (let event of events) {
    dispatch(event);
  }

  // if a lone ESC is pending, wait and re-scan to flush it
  if (pending) {
    timer = setTimeout(() => {
      let flush = input.scan();
      for (let event of flush.events) {
        dispatch(event);
      }
    }, pending.delay);
  }
});
```

## 发展

用于本地源构建、工具链设置和 `clay` 子模块指令,参见 [贝鲁特,md](https://npmcn.com/package/%40bomb.sh/tty/BUILD.md)。 。 。 .

快速本地验证 :

```sh
make
deno task test
```

## 常见问题

### @bomb\.sh/tty 是什么？

用于 Clay 的终端渲染后端, 编译为 Web Assembly

### 如何安装 @bomb\.sh/tty？

在项目目录运行 npm install @bomb\.sh/tty，或使用 pnpm add / yarn add / bun add。

### @bomb\.sh/tty 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bomb\.sh\_\_tty 是否存在。

### @bomb\.sh/tty 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bomb\.sh/tty 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bomb\.sh/tty 可以商用吗？

@bomb\.sh/tty 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bomb\.sh/tty 的下载量有多少？

根据 npm 官方下载统计，@bomb\.sh/tty 在 2026/10/09 – 2026/11/07 这 30 天内被下载 36,264 次，日均约 1,209 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bomb\.sh/tty 还在维护吗？

最新版本 0\.10\.0 发布于 2026/10/22（17 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/06/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。