# ansi-escapes 中文文档

规范地址：https://npmcn.com/package/ansi-escapes/

版本：7\.3\.0
npm 元数据更新时间：2026-02-04T16:21:10.344Z
中文译文更新时间：2026-11-05T02:19:26.768Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/ansi-escapes
原文对照：https://npmcn.com/package/ansi-escapes/?lang=original
项目主页：https://github.com/sindresorhus/ansi-escapes#readme
源码仓库：https://github.com/sindresorhus/ansi-escapes

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

- 包体积（解压后）：22 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2015-08-14T15:26:46.205Z
- 最新版本发布：2026-02-04T16:21:10.230Z
- 近 30 天下载量：524105237（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 1 个）

## 中文简介

用于操纵终端的ANSI转义码

## 安装

```sh
npm install ansi-escapes
```

也可以使用：`pnpm add ansi-escapes`、`yarn add ansi-escapes`、`bun add ansi-escapes`

## README

# ansi-escapes

> [ANSI转义码](https://www2.ccs.neu.edu/research/gpc/VonaUtils/vona/terminal/vtansi.htm) 用于操作终端

## 安装

```sh
npm install ansi-escapes
```

## 用法

```js
import ansiEscapes from 'ansi-escapes';

// Moves the cursor two rows up and to the left
process.stdout.write(ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft);
//=> '\u001B[2A\u001B[1000D'
```

或者使用命名的导出…

```js
import {cursorUp, cursorLeft} from 'ansi-escapes';

// etc, as above...
```

**你也可以在浏览器中使用Xterm.js：**

```js
import ansiEscapes from 'ansi-escapes';
import {Terminal} from 'xterm';
import 'xterm/css/xterm.css';

const terminal = new Terminal({…});

// Moves the cursor two rows up and to the left
terminal.write(ansiEscapes.cursorUp(2) + ansiEscapes.cursorLeft);
//=> '\u001B[2A\u001B[1000D'
```

## API

### cursorTo (x, y)

设置光标的绝对位置。 `x0` `y0` 在屏幕的左上方。

### cursorMove (x, y)

设置光标相对于当前位置的位置。

### cursorUp(计数)

将游标向上移动指定数量的行。默认是 `1`。

### cursorDown(计数)

将光标向下移动指定数量的行。默认是 `1`。

### cursorForward(计数)

将光标向前移动指定数量的列。默认是 `1`。

### cursorBackward(计数)

将光标向后移动指定数量的列。默认是 `1`。

### cursorLeft

将光标移到左侧。

### cursorSavePosition

保存光标位置。

### cursorRestorePosition

恢复保存的光标位置。

### cursorGetPosition

获取光标位置。

### cursorNextLine

将光标移动到下一行。

### cursorPrevLine

将光标移动到前一行。

### cursorHide

隐藏的光标。

### cursorShow

显示光标。

### eraseLines(计数)

从当前游标位置向上擦除指定的行数。

### eraseEndLine

从当前光标位置擦除到当前行的末尾。

### eraseStartLine

从当前光标位置擦除到当前行的开头。

### eraseLine

擦除当前的整个行。

### eraseDown

从当前行到屏幕底部擦除屏幕。

### eraseUp

从当前行到屏幕顶部擦除屏幕。

### eraseScreen

擦除屏幕并将光标移动到左上角位置。

### scrollUp

向上滚动显示一行。

### scrollDown

向下滚动显示一行。

### clearViewport

只清除可见的终端屏幕（视口），而不影响回滚缓冲区或终端状态。

这是一个更安全的选择 `clearScreen` 这在各个终端上都是一致的。

### clearScreen

清除终端屏幕。

> \[!警告) 这使用RIS (Reset to Initial State)，它也可以清除一些终端（xterm.js， VTE）中的回滚缓冲区并重置终端模式。考虑使用 `clearViewport()` 为了更安全的viewport清除。

### clearTerminal

清除整个终端，包括回滚缓冲区。（不仅仅是可见的部分）

### enterAlternativeScreen

进入 [选择屏幕](https://terminalguide.namepad.de/mode/p47/)。

### exitAlternativeScreen

退出 [选择屏幕](https://terminalguide.namepad.de/mode/p47/),假设 `enterAlternativeScreen` 以前叫过。

### beginSynchronizedOutput

开始 [同步输出](https://contour-terminal.org/vt-extensions/synchronized-output/) 减少渲染时的闪烁。

### endSynchronizedOutput

结束 [同步输出](https://contour-terminal.org/vt-extensions/synchronized-output/)。

### synchronizedOutput(文本)

将输出封装在 [同步输出](https://contour-terminal.org/vt-extensions/synchronized-output/) 在渲染过程中减少闪烁的序列。

### 哔哔声

输出蜂鸣声。

### 链接(文本、网址)

创建一个可点击的链接。

[支持终端。](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) 使用 [`supports-hyperlinks`](https://github.com/jamestalmage/supports-hyperlinks) 检测链路支持。

### 图像(filePath、期权?)

显示图像。

看到 [term-img](https://github.com/sindresorhus/term-img) 用于更高级别的模块。

#### 输入

类型: `Buffer`

图像缓冲区。通常读入 `fs.readFile()`。

#### 选项

类型: `object`

##### 宽度

##### 高度

类型: `string | number`

宽度和高度以数字后跟一个单位或单词“auto”的形式给出。

-   `N`： N个字符单元。
-   `Npx`： N像素。
-   `N%`：会话宽度或高度的百分之N。
-   `auto`：图像的固有尺寸将被用来确定一个合适的尺寸。

##### preserveAspectRatio

类型: `boolean`  
默认值: `true`

### setCwd(路径?)

类型: `string`  
默认值: `process.cwd()`

为iTerm2和ConEmu设置当前工作目录。

### iTerm.setCwd(路径?)

类型: `string`  
默认值: `process.cwd()`

[通知iTerm2](https://www.iterm2.com/documentation-escape-codes.html) 对当前目录的语义历史进行帮助和启用 [点击cmd键的相对路径](https://coderwall.com/p/b7e82q/quickly-open-files-in-iterm-with-cmd-click)。

### ConEmu.setCwd(路径?)

类型: `string`  
默认值: `process.cwd()`

[通知ConEmu](https://conemu.github.io/en/AnsiEscapeCodes.html#ConEmu_specific_OSC) 关于shell当前工作目录。

### 摘要。注释(消息、期权?)

创建转义代码以在iTerm2中显示“注释”。

注释如下所示：

![](https://user-images.githubusercontent.com/924465/64382136-b60ac700-cfe9-11e9-8a35-9682e8dc4b72.png)

看到 [专有转义码文档](https://iterm2.com/documentation-escape-codes.html) 了解更多信息。

#### 消息

类型: `string`

要在注释中显示的消息。

这个 `|` 字符是不允许的，将被剥夺。

#### 选项

类型: `object`

##### 长度

类型: `number`  
默认值：该行的剩余部分

要注释的列数非零。

##### x

类型: `number`  
默认：光标位置

起始X坐标。

必须与 `y` 和 `length`。

##### y

类型: `number`  
默认：光标位置

从Y坐标开始。

必须与 `x` 和 `length`。

##### isHidden

类型: `boolean`  
默认值: `false`

创建一个“隐藏”注释。

以这种方式创建的注释可以使用“Show Annotations”iTerm命令显示。

## 相关

-   [ansi-styles](https://github.com/chalk/ansi-styles) -终端样式字符串的ANSI转义码

## 常见问题

### ansi-escapes 是什么？

用于操纵终端的ANSI转义码

### 如何安装 ansi-escapes？

在项目目录运行 npm install ansi-escapes，或使用 pnpm add / yarn add / bun add。

### ansi-escapes 支持 TypeScript 吗？

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

### ansi-escapes 支持 ESM 还是 CommonJS？

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

### ansi-escapes 需要什么版本的 Node\.js？

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

### ansi-escapes 可以商用吗？

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

### ansi-escapes 的下载量有多少？

根据 npm 官方下载统计，ansi-escapes 在 2026/10/05 – 2026/11/03 这 30 天内被下载 524,105,237 次，日均约 17,470,175 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### ansi-escapes 还在维护吗？

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