# @gajae-code/tui 中文文档

规范地址：https://npmcn.com/package/%40gajae-code/tui/

版本：0\.21\.0
npm 元数据更新时间：2026-11-16T05:08:06.884Z
中文译文更新时间：2026-11-16T05:10:28.028Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gajae-code/tui
原文对照：https://npmcn.com/package/%40gajae-code/tui/?lang=original
项目主页：https://gajae-code.com/
源码仓库：https://github.com/Yeachan-Heo/gajae-code

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

- 包体积（解压后）：1.1 MB，78 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-05-27T18:46:32.184Z
- 最新版本发布：2026-11-16T05:08:06.548Z
- 近 30 天下载量：7058（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：158（近 12 个月 158 个）

## 中文简介

终端用户界面库,用于高效文本应用程序的差分渲染

## 安装

```sh
npm install @gajae-code/tui
```

也可以使用：`pnpm add @gajae-code/tui`、`yarn add @gajae-code/tui`、`bun add @gajae-code/tui`

## README

# @gajae-code/tui (英语)

最小终端UI框架,有差分渲染和同步输出,用于flicker无交互CLI应用程序.

## 特征

-   **区别对待**: 三战略渲染系统,只更新变化
-   **同步输出**: CSI 2026用于原子屏幕更新(无闪烁)
-   **括号粘贴模式**: 正确处理大于10行粘贴的大型粘贴
-   **基于构成部分**: 具有渲染( ) 方法的简单组件接口
-   **主题支持**: 组件接受可自定义型式的主题接口(编码代理包在这些接口上构建出一个红爪甲壳类主题)
-   **内建组件**: 文本、 截断文本、 输入、 编辑器、 Markdown、 装入器、 选择列表、 设置列表、 空间器、 图像、 框、 容器
-   **内含图像**: 在支持 Kitty 或 iTerm2 图形协议的终端中渲染图像
-   **自动完整支持**: 文件路径和斜线命令

## 快速启动

```typescript
import { TUI, Text, Editor, ProcessTerminal } from "@gajae-code/tui";

// Create terminal
const terminal = new ProcessTerminal();

// Create TUI
const tui = new TUI(terminal);

// Add components
tui.addChild(new Text("Welcome to my app!"));

const editor = new Editor(editorTheme);
editor.onSubmit = (text) => {
    console.log("Submitted:", text);
    tui.addChild(new Text(`You said: ${text}`));
};
tui.addChild(editor);

// Start
tui.start();
```

## 核心 API

### 图瓦卢

管理组件和渲染的主要容器.

#### 框架编制

`tui.enqueueBeforeRender(callback: () => void): () => void` 一个同步的, 一发准备并返回一发取消功能。 它要求a 现有 16 ms 帧时钟的正常全模渲染;不添加定时器和 不强迫或加速一个框架。 正常的、强迫的和输入式优先框架排出量 在捕捉到世代或阅读布局、组件之前, 视图源,或缓存. 普通提交请求的准备 框中不包含仅要求的后继涂料。 在排水过程中进行的登记 他们的后代在准备执行之前不能犯罪, 甚至当更新的普通请求先执行或终端输出被排入队列时也是如此.

取消会删除回调引用, 包括已经抓取的条目, 但是 尚未援引。 保留取消的手柄发布它们引用 TUI 在取消、援引(包括失败)或生命周期时召回 无效 。 后来的取消呼叫是无操作的;执行回调仍然保留 活到它的同步引用返回。 准备例外被记录 无关的回调继续, 而失败的准备的生成没有被报告为成功的承诺. 丢弃或生命周期无效的制剂立即解决现有 派遣服务员 `false`这几代人中晚到的侍从也决心 `false`, (中文(简体) ), 即使是在新的成功框架之后 退休的几代人被合并储存, 排序失败范围,与活的待决范围除外。 毗连 失败压缩成一个范围;分开的失败保留不同的范围至 保持准确的结果。 历史故障区域没有复制或扫描到 每个框架(服务员查询使用二进制搜索). 历史没有任意的过期:其数字存储为 O( 脱节失败范围) , 不以无限交替的会话为界。 空活动 待定的和孔片并不意味着有界限的历史存储或证明泄漏自由. 回调必须是同步的(不要通过ASync函数).

取消寿命回归检查 Bun 的繁多快照是否退出 本地关闭/进入所有者、召回和有效载荷的路径,而所有目标 继续刻意扎根。 手柄和有意保留箭头 是积极的控制; 已退休的手柄必须失去这些路径。 本检查参考文献 释放时不假设GC收集对象。 无法证明全球泄漏 自由或排除无关模块、运行时间或测试运行者的根.

`tui.setRenderPreparationLifecycleCallbacks(callbacks: { invalidate: () => void; beforeStart: () => void } | undefined): void` 安装一个 **单人** 准备所有人. 替换或清除所有者会使其已排队和抓取的旧作品失效 呼唤它 `invalidate` 同步进行. 停止、终端损失和处置情况相同; 例外情况在不阻止取消的情况下予以记录。 处置也清除了 拥有者。 停止、不可用、无效或处理时的队列不保留任何工作. 处置将取消待制/width-setle定时器,并提交请求;稍后正常, 强制、输入优先级和调整大小的请求不能重置已处理的渲染器.

成功设置终端后, 每个 `start()` 电话 `beforeStart` 同步 在第一次强制提出要求之前 店主可以重新准备 因此重启不需要另一个 提供者事件。 设置失败不能重新武装工作; 丢弃 `beforeStart` 已登录 而其已排队的工作无效。 排水时停止/启动无法恢复 排水沟的旧快照。 这个API只是一个演示-准备生命周期接合, 不是一般生命周期事件总线.

```typescript
const tui = new TUI(terminal);
tui.addChild(component);
tui.removeChild(component);
tui.start();
tui.stop();
tui.requestRender(); // Request a re-render

// Global debug key handler (Shift+Ctrl+D)
tui.onDebug = () => console.log("Debug triggered");
```

### 手动取景口和后缀

`setBottomPinnedComponent(component)` 标出一个直接的孩子边界。 在手动取景器所有权期间,这个孩子和所有后来的直通孩子在行行后仍固定在下方,再形成可滚动道;这不需要输出源. `scrollViewportPages()` 乘车道高度减一; `scrollViewportBy()` 支持更小的行步骤并拒绝非无限三角洲.

`setViewportOutputSource({ identity, revision })` 报告语义输出变化,而不将 TUI 与消息类型相配合。 手动滚动显示准确通知的同名修改预览 `New output — type to follow`;在直播后或改变/删除身份后可以澄清,而僵化的同名修正回滚则不会.

剪接行和通知不在鼠标选取坐标记录中。 当终端太短时,在装饰或低优先级后缀行前会保留焦点直生后缀组件.

### 组件接口

所有组成部分执行:

```typescript
interface Component {
    render(width: number): string[];
    handleInput?(data: string): void;
    invalidate?(): void;
}
```

| 方法 | 说明 |
| --- | --- |
| `render(width)` | 返回一组字符串,每行一个。 每行 **不得超过 `width`** 否则TUI会出错. 使用 `truncateToWidth()` 或人工包装以确保这一点. |
| `handleInput?(data)` | 当组件有焦点并接收键盘输入时调用. 这个 `data` 字符串包含原始终端输入(可能包括ANSI逃生序列). |
| `invalidate?()` | 请求清除缓存的状态 。 部件应该从零开始在下一个 `render()` 电话. |

## 内建组件

### 集装箱

儿童组.

```typescript
const container = new Container();
container.addChild(component);
container.removeChild(component);
```

### 方框

适用于所有儿童的贴花和背景颜色的容器.

```typescript
const box = new Box(
    1, // paddingX (default: 1)
    1, // paddingY (default: 1)
    (text) => chalk.bgGray(text), // optional background function
);
box.addChild(new Text("Content"));
box.setBgFn((text) => chalk.bgBlue(text)); // Change background dynamically
```

### 文本

显示多行文字并用字包和粘贴.

```typescript
const text = new Text(
    "Hello World", // text content
    1, // paddingX (default: 1)
    1, // paddingY (default: 1)
    (text) => chalk.bgGray(text), // optional background function
);
text.setText("Updated text");
text.setCustomBgFn((text) => chalk.bgBlue(text));
```

### 截断文本

单行文本可切换以适应取景口宽度. 用于状态行和标题 .

```typescript
const truncated = new TruncatedText(
    "This is a very long line that will be truncated...",
    0, // paddingX (default: 0)
    0, // paddingY (default: 0)
);
```

### 投入

单行文字输入并横向滚动.

```typescript
const input = new Input();
input.onSubmit = (value) => console.log(value);
input.setValue("initial");
input.getValue();
```

**密钥绑定 :**

-   `Enter` - 提交
-   `Ctrl+A` 编号 : `Ctrl+E` - 线路始末
-   `Ctrl+W` 或者说 `Alt+Backspace` - 向后删除单词
-   `Ctrl+U` - 删除为行首
-   `Ctrl+K` - 删除到行尾
-   `Ctrl+Left` 编号 : `Ctrl+Right` - 文字导航
-   `Alt+Left` 编号 : `Alt+Right` - 文字导航
-   箭头密钥, 后空格, 按预期删除工作

### 编辑器

多行文本编辑器,具有自动完成,文件完成和粘贴处理功能.

```typescript
interface SymbolTheme {
    cursor: string;
    ellipsis: string;
    boxRound: {
        topLeft: string;
        topRight: string;
        bottomLeft: string;
        bottomRight: string;
        horizontal: string;
        vertical: string;
    };
    boxSharp: {
        topLeft: string;
        topRight: string;
        bottomLeft: string;
        bottomRight: string;
        horizontal: string;
        vertical: string;
        teeDown: string;
        teeUp: string;
        teeLeft: string;
        teeRight: string;
        cross: string;
    };
    table: {
        topLeft: string;
        topRight: string;
        bottomLeft: string;
        bottomRight: string;
        horizontal: string;
        vertical: string;
        teeDown: string;
        teeUp: string;
        teeLeft: string;
        teeRight: string;
        cross: string;
    };
    quoteBorder: string;
    hrChar: string;
    spinnerFrames: string[];
}

interface EditorTheme {
    borderColor: (str: string) => string;
    selectList: SelectListTheme;
    symbols: SymbolTheme;
}

const editor = new Editor(theme);
editor.onSubmit = (text) => console.log(text);
editor.onChange = (text) => console.log("Changed:", text);
editor.disableSubmit = true; // Disable submit temporarily
editor.setAutocompleteProvider(provider);
editor.borderColor = (s) => chalk.blue(s); // Change border dynamically
```

**特征 :**

-   多行编辑并装有字包
-   斜线命令自动完成( 类型) `/`(中文(简体) )
-   文件路径自动完成( 按 `Tab`(中文(简体) )
-   大型粘贴处理( > 10行创建) `[paste #1 +50 lines]` 标记)
-   水平行上方/下方编辑器
-   假光标渲染( 隐藏真实光标)

**密钥绑定 :**

-   `Enter` - 提交
-   `Shift+Enter`, (中文(简体) ), `Ctrl+Enter`,或 `Alt+Enter` - 新线(依赖地铁,Alt+Enter最可靠)
-   `Tab` - 自动完成
-   `Ctrl+K` - 删除行
-   `Alt+D` 编号 : `Alt+Delete` - 删除前面的字
-   `Ctrl+A` 编号 : `Ctrl+E` - 线路始末
-   `Ctrl+-` - 撤销上次编辑
-   箭头密钥, 后空格, 按预期删除工作

### 标记

以语法加亮和主题支持来标记下.

```typescript
interface MarkdownTheme {
    heading: (text: string) => string;
    link: (text: string) => string;
    linkUrl: (text: string) => string;
    code: (text: string) => string;
    codeBlock: (text: string) => string;
    codeBlockBorder: (text: string) => string;
    quote: (text: string) => string;
    quoteBorder: (text: string) => string;
    hr: (text: string) => string;
    listBullet: (text: string) => string;
    bold: (text: string) => string;
    italic: (text: string) => string;
    strikethrough: (text: string) => string;
    underline: (text: string) => string;
    highlightCode?: (code: string, lang?: string) => string[];
    symbols: SymbolTheme;
}

interface DefaultTextStyle {
    color?: (text: string) => string;
    bgColor?: (text: string) => string;
    bold?: boolean;
    italic?: boolean;
    strikethrough?: boolean;
    underline?: boolean;
}

const md = new Markdown(
    "# Hello\n\nSome **bold** text",
    1, // paddingX
    1, // paddingY
    theme, // MarkdownTheme
    defaultStyle, // optional DefaultTextStyle
    2, // optional code block indent (spaces)
);
md.setText("Updated markdown");
```

**特征 :**

-   标题、粗体、斜体、代码块、列表、链接、块词
-   HTML 标记作为纯文本渲染
-   可选语法高亮通过 `highlightCode`
-   铺设支持
-   为性能进行缓冲

### 装入器

动画装入自旋器.

```typescript
const loader = new Loader(
    tui, // TUI instance for render updates
    (s) => chalk.cyan(s), // spinner color function
    (s) => chalk.gray(s), // message color function
    "Loading...", // message (default: "Loading...")
);
loader.start();
loader.setMessage("Still loading...");
loader.stop();
```

### 可切换连接器

以 Escape 密钥处理方式扩展加载器, 并中止用于取消ASync 操作的信号 .

```typescript
const loader = new CancellableLoader(
    tui, // TUI instance for render updates
    (s) => chalk.cyan(s), // spinner color function
    (s) => chalk.gray(s), // message color function
    "Working...", // message
);
loader.onAbort = () => done(null); // Called when user presses Escape
doAsyncWork(loader.signal).then(done);
```

**属性 :**

-   `signal: AbortSignal` - 用户按出逃时中止
-   `aborted: boolean` - 装载器是否中止
-   `onAbort?: () => void` - 用户按出逃时召回

### 选择列表

与键盘导航交互选择列表 .

```typescript
interface SelectItem {
    value: string;
    label: string;
    description?: string;
    hint?: string; // Autocomplete hint consumed by Editor; SelectList does not render it
    disabled?: boolean; // Dimmed, unselectable entry (see "Disabled items")
}

interface SelectListTheme {
    selectedPrefix: (text: string) => string;
    selectedText: (text: string) => string;
    description: (text: string) => string;
    scrollInfo: (text: string) => string;
    noMatch: (text: string) => string;
    symbols: SymbolTheme;
}

const list = new SelectList(
    [
        { value: "opt1", label: "Option 1", description: "First option" },
        { value: "opt2", label: "Option 2", description: "Second option" },
    ],
    5, // maxVisible
    theme, // SelectListTheme
);

list.onSelect = (item) => console.log("Selected:", item);
list.onCancel = () => console.log("Cancelled");
list.onSelectionChange = (item) => console.log("Highlighted:", item);
list.setFilter("opt"); // Filter items
list.setSelectedIndex(1); // Select first enabled item at/after index 1, then search backward
```

**控件 :**

-   箭头按键:在列表边缘进行导航并围入
-   PageUp/PageDown: 以可见的页面移动,并在列表边界上夹住
-   输入: 选择
-   逃脱: 取消

**已禁用的项目 :**

与 `disabled: true` 保持可见但永远无法被选中 :

-   它们变得暗淡 `theme.description`),从不显示选择光标.
-   跳过被禁条目时箭头键包; PageUp/PageDown 跳过被禁目标并夹住列表边界.
-   过滤( E)`setFilter`) 将选择重排为第一个 _启用_ 目 录(续).
-   `setSelectedIndex(i)` 在被夹住的索引上或之后选择第一个启用的项目,然后倒向后.
-   `onSelect` 财务报告和审定财务报表 `onSelectionChange` 永远不会收到一个已禁用的项目.
-   当每个可见物品被禁用时, `getSelectedItem()` 返回时 `null` 没有 行显示光标。 箭头键包住取景口,PageUp/PageDown夹住它, 和滚动指标报告 `(-/N)` 不要求选择的行.

### 设置列表

设置带有值循环和子菜单的面板 .

```typescript
interface SettingItem {
    id: string;
    label: string;
    description?: string;
    currentValue: string;
    values?: string[]; // If provided, Enter/Space cycles through these
    submenu?: (currentValue: string, done: (selectedValue?: string) => void) => Component;
}

interface SettingsListTheme {
    label: (text: string, selected: boolean) => string;
    value: (text: string, selected: boolean) => string;
    description: (text: string) => string;
    cursor: string;
    hint: (text: string) => string;
}

const settings = new SettingsList(
    [
        { id: "theme", label: "Theme", currentValue: "dark", values: ["dark", "light"] },
        { id: "model", label: "Model", currentValue: "gpt-4", submenu: (val, done) => modelSelector },
    ],
    10, // maxVisible
    theme, // SettingsListTheme
    (id, newValue) => console.log(`${id} changed to ${newValue}`),
    () => console.log("Cancelled"),
);
settings.updateValue("theme", "light");
```

**控件 :**

-   箭头密钥: 导航
-   输入/ 空间: 激活( 周期值或打开子菜单)
-   逃脱: 取消

### 空间器

垂直间距的空行.

```typescript
const spacer = new Spacer(2); // 2 empty lines (default: 1)
```

### 图像

将支持 Kitty 图形协议( Kitty, Ghostty, Wez Term) 或 iTerm2 内置图像的终端内置图像 。 返回到不支持的终端上的文本占位符 .

```typescript
interface ImageTheme {
    fallbackColor: (str: string) => string;
}

interface ImageOptions {
    maxWidthCells?: number;
    maxHeightCells?: number;
    filename?: string;
}

const image = new Image(
    base64Data, // base64-encoded image data
    "image/png", // MIME type
    theme, // ImageTheme
    options, // optional ImageOptions
);
tui.addChild(image);
```

所支持的格式:PNG,JPEG,GIF,WebP. 从图像头自动解析尺寸 .

## 自动完成

### 组合自动完成器

支持斜线命令和文件路径.

```typescript
import { CombinedAutocompleteProvider } from "@gajae-code/tui";
import { getProjectDir } from "@gajae-code/utils";

const provider = new CombinedAutocompleteProvider(
    [
        { name: "help", description: "Show help" },
        { name: "clear", description: "Clear screen" },
        { name: "delete", description: "Delete last message" },
    ],
    getProjectDir(), // base path for file completion
);

editor.setAutocompleteProvider(provider);
```

**特征 :**

-   类型 `/` 显示斜线命令
-   新闻 `Tab` 文件路径补全
-   与 `~/`, (中文(简体) ), `./`, (中文(简体) ), `../`,以及 `@` 前缀
-   可附加文件的过滤器 `@` 前缀

## 密钥检测

用于检测键盘输入的帮助器功能( 支持 Kitty 键盘协议 ):

```typescript
import {
    isEnter,
    isEscape,
    isTab,
    isShiftTab,
    isArrowUp,
    isArrowDown,
    isArrowLeft,
    isArrowRight,
    isCtrlA,
    isCtrlC,
    isCtrlE,
    isCtrlK,
    isCtrlO,
    isCtrlP,
    isCtrlLeft,
    isCtrlRight,
    isAltLeft,
    isAltRight,
    isShiftEnter,
    isAltEnter,
    isShiftCtrlO,
    isShiftCtrlD,
    isShiftCtrlP,
    isBackspace,
    isDelete,
    isHome,
    isEnd,
    // ... and more
} from "@gajae-code/tui";

if (isCtrlC(data)) {
    process.exit(0);
}
```

## 区别对待

TUI使用三个渲染策略:

1.  **第一个**: 输出所有行而不清理回滚
2.  **视图端口上方的宽度已更改或更改**: 清除屏幕并全部重置
3.  **普通更新**: 将光标移动到第一个已更改行上, 清除到结束, 渲染已更改行

所有更新都包含在 **同步输出** (单位:千美元)`\x1b[?2026h` . `\x1b[?2026l`用于原子,无闪光渲染.

## 终端接口

TUI 与执行 `Terminal` 接口 :

```typescript
interface Terminal {
    start(onInput: (data: string) => void, onResize: () => void): void;
    stop(): void;
    write(data: string): void;
    get columns(): number;
    get rows(): number;
    moveBy(lines: number): void;
    hideCursor(): void;
    showCursor(): void;
    clearLine(): void;
    clearFromCursor(): void;
    clearScreen(): void;
}
```

**内建实施:**

-   `ProcessTerminal` - 用途 `process.stdin/stdout`
-   `VirtualTerminal` - 测试(用途) `@xterm/headless`(中文(简体) )

## 公用事业

```typescript
import { Ellipsis, visibleWidth, truncateToWidth, wrapTextWithAnsi } from "@gajae-code/tui";

// Get visible width of string (ignoring ANSI codes, uses Bun.stringWidth)
const width = visibleWidth("\x1b[31mHello\x1b[0m"); // 5

// Truncate string to width (preserving ANSI codes, adds ellipsis)
const truncated = truncateToWidth("Hello World", 8); // "Hello…" (default: Ellipsis.Unicode)

// Truncate without ellipsis
const truncatedNoEllipsis = truncateToWidth("Hello World", 8, Ellipsis.Omit); // "Hello Wo"

// Wrap text to width (Bun.wrapAnsi word wrap, trims line ends, preserves ANSI)
const lines = wrapTextWithAnsi("This is a long line that needs wrapping", 20);
// ["This is a long line", "that needs wrapping"]
```

## 创建自定义组件

当创建自定义组件时, **返回的每行 `render()` 不得超过 `width` 参数**。如果有线比终端宽,则TUI会出错.

### 处理输入

使用密钥检测工具处理键盘输入 :

```typescript
import { isEnter, isEscape, isArrowUp, isArrowDown, isCtrlC, isTab, isBackspace } from "@gajae-code/tui";
import type { Component } from "@gajae-code/tui";

class MyInteractiveComponent implements Component {
    private selectedIndex = 0;
    private items = ["Option 1", "Option 2", "Option 3"];

    onSelect?: (index: number) => void;
    onCancel?: () => void;

    handleInput(data: string): void {
        if (isArrowUp(data)) {
            this.selectedIndex = Math.max(0, this.selectedIndex - 1);
        } else if (isArrowDown(data)) {
            this.selectedIndex = Math.min(this.items.length - 1, this.selectedIndex + 1);
        } else if (isEnter(data)) {
            this.onSelect?.(this.selectedIndex);
        } else if (isEscape(data) || isCtrlC(data)) {
            this.onCancel?.();
        }
    }

    render(width: number): string[] {
        return this.items.map((item, i) => {
            const prefix = i === this.selectedIndex ? "> " : "  ";
            return truncateToWidth(prefix + item, width);
        });
    }
}
```

### 处理行宽

利用所提供的水电设施确保线路符合:

```typescript
import { visibleWidth, truncateToWidth } from "@gajae-code/tui";
import type { Component } from "@gajae-code/tui";

class MyComponent implements Component {
    private text: string;

    constructor(text: string) {
        this.text = text;
    }

    render(width: number): string[] {
        // Option 1: Truncate long lines
        return [truncateToWidth(this.text, width)];

        // Option 2: Check and pad to exact width
        const line = this.text;
        const visible = visibleWidth(line);
        if (visible > width) {
            return [truncateToWidth(line, width)];
        }
        // Pad to exact width (optional, for backgrounds)
        return [line + " ".repeat(width - visible)];
    }
}
```

### ANSI 守则考虑

`visibleWidth()`, (中文(简体) ), `truncateToWidth()`,以及 `wrapTextWithAnsi()` 正确处理 ANSI 逃生代码 :

-   `visibleWidth()` 计算宽度时忽略 ANSI 代码(通过 `Bun.stringWidth`(中文(简体) )
-   `truncateToWidth()` 保存 ANSI 代码并在切换时正确关闭
-   `wrapTextWithAnsi()` 保存 ANSI 代码, 而文字包装和剪切线结束

```typescript
import chalk from "chalk";

const styled = chalk.red("Hello") + " " + chalk.blue("World");
const width = visibleWidth(styled); // 11 (not counting ANSI codes)
const truncated = truncateToWidth(styled, 8); // Red "Hello" + " W..." with proper reset
```

### 缓存

就性能而言,组件应缓存其产出,并仅在必要时重新交付:

```typescript
class CachedComponent implements Component {
    private text: string;
    private cachedWidth?: number;
    private cachedLines?: string[];

    render(width: number): string[] {
        if (this.cachedLines && this.cachedWidth === width) {
            return this.cachedLines;
        }

        const lines = [truncateToWidth(this.text, width)];

        this.cachedWidth = width;
        this.cachedLines = lines;
        return lines;
    }

    invalidate(): void {
        this.cachedWidth = undefined;
        this.cachedLines = undefined;
    }
}
```

## 示例

见 `test/chat-simple.ts` 用于完整聊天接口示例:

-   带有自定义背景颜色的下沉信件
-   回复时正在装入自旋器
-   有自动完成和斜线命令的编辑器
-   信件之间的空格

运行它:

```bash
npx tsx test/chat-simple.ts
```

## 发展

```bash
# Install dependencies (from monorepo root)
npm install

# Run type checking
npm run check

# Run the demo
npx tsx test/chat-simple.ts
```

## 常见问题

### @gajae-code/tui 是什么？

终端用户界面库,用于高效文本应用程序的差分渲染

### 如何安装 @gajae-code/tui？

在项目目录运行 npm install @gajae-code/tui，或使用 pnpm add / yarn add / bun add。

### @gajae-code/tui 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gajae-code/tui 支持 ESM 还是 CommonJS？

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

### @gajae-code/tui 可以商用吗？

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

### @gajae-code/tui 的下载量有多少？

根据 npm 官方下载统计，@gajae-code/tui 在 2026/10/16 – 2026/11/14 这 30 天内被下载 7,058 次，日均约 235 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gajae-code/tui 还在维护吗？

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

