# ansi-styles 中文文档

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

版本：7\.0\.0
npm 元数据更新时间：2026-07-26T14:57:37.001Z
中文译文更新时间：2026-11-04T08:41:44.501Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：22.1 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2013-07-31T23:00:29.145Z
- 最新版本发布：2026-07-26T14:57:36.835Z
- 近 30 天下载量：2775039877（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 1 个）

## 中文简介

在终端中样式化字符串的ANSI转义码

## 安装

```sh
npm install ansi-styles
```

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

## README

# ansi-styles

> [ANSI转义码](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors_and_Styles) 用于对终端中的字符串进行样式化

你可能想要更高级的 [粉笔](https://github.com/chalk/chalk) 模块，用于对字符串进行样式化。

![](https://npmcn.com/package/ansi-styles/screenshot.png)

## 安装

```sh
npm install ansi-styles
```

## 用法

```js
import styles from 'ansi-styles';

console.log(`${styles.green.open}Hello world!${styles.green.close}`);


// Color conversion between 256/truecolor
// NOTE: When converting from truecolor to 256 colors, the original color
//       may be degraded to fit the new color palette. This means terminals
//       that do not support 16 million colors will best-match the
//       original color.
console.log(`${styles.color.ansi(styles.rgbToAnsi(199, 20, 250))}Hello World${styles.color.close}`)
console.log(`${styles.color.ansi256(styles.rgbToAnsi256(199, 20, 250))}Hello World${styles.color.close}`)
console.log(`${styles.color.ansi16m(...styles.hexToRgb('#abcdef'))}Hello World${styles.color.close}`)
```

## API

### `open` 和 `close`

每种风格都有一个 `open` 和 `close` 财产。

### `modifierNames`， `foregroundColorNames`， `backgroundColorNames`， `underlineColorNames`, `colorNames`

为方便起见，所有支持的样式字符串都公开为字符串数组。 `colorNames` 是 `foregroundColorNames` 和 `backgroundColorNames`． 中的下划线颜色名称保持分开 `underlineColorNames`。

如果你需要验证输入，这可能很有用：

```js
import {modifierNames, foregroundColorNames} from 'ansi-styles';

console.log(modifierNames.includes('bold'));
//=> true

console.log(foregroundColorNames.includes('pink'));
//=> false
```

## 风格

### 修饰符

-   `reset`
-   `bold`
-   `dim`
-   `italic` _（不被广泛支持）_
-   `underline` -在文本下面画一条水平线。 _（不被广泛支持）_
-   `underlineDouble` -在文本下面放一条双水平线。 _（不被广泛支持）_
-   `underlineCurly` -在文本下方放置一条卷曲的水平线。 _（不被广泛支持）_
-   `underlineDotted` -在文本下面画一条虚线。 _（不被广泛支持）_
-   `underlineDashed` -在文本下面放一条虚线。 _（不被广泛支持）_
-   `overline` _支持vte终端、GNOME终端、mintty、Git Bash。_
-   `inverse`
-   `hidden`
-   `strikethrough` _（不被广泛支持）_

### 颜色

-   `black`
-   `red`
-   `green`
-   `yellow`
-   `blue`
-   `magenta`
-   `cyan`
-   `white`
-   `blackBright` (别名: `gray`， `grey`）
-   `redBright`
-   `greenBright`
-   `yellowBright`
-   `blueBright`
-   `magentaBright`
-   `cyanBright`
-   `whiteBright`

### 背景颜色

-   `bgBlack`
-   `bgRed`
-   `bgGreen`
-   `bgYellow`
-   `bgBlue`
-   `bgMagenta`
-   `bgCyan`
-   `bgWhite`
-   `bgBlackBright` (别名: `bgGray`， `bgGrey`）
-   `bgRedBright`
-   `bgGreenBright`
-   `bgYellowBright`
-   `bgBlueBright`
-   `bgMagentaBright`
-   `bgCyanBright`
-   `bgWhiteBright`

### 下划线颜色

下划线颜色的设置独立于文本颜色，因此只有在应用下划线样式时，颜色才可见。 _（不被广泛支持）_

与文本和背景颜色不同，下划线颜色没有基本的16色形式。命名下划线颜色和 `underlineColor.ansi()` 使用256色调色板中的前16个条目。 `underlineColor.ansi256()` 发出256色的逃逸光，并且 `underlineColor.ansi16m()` 发出真彩色的光。

-   `underlineBlack`
-   `underlineRed`
-   `underlineGreen`
-   `underlineYellow`
-   `underlineBlue`
-   `underlineMagenta`
-   `underlineCyan`
-   `underlineWhite`
-   `underlineBlackBright` (别名: `underlineGray`， `underlineGrey`）
-   `underlineRedBright`
-   `underlineGreenBright`
-   `underlineYellowBright`
-   `underlineBlueBright`
-   `underlineMagentaBright`
-   `underlineCyanBright`
-   `underlineWhiteBright`

## 高级用法

默认情况下，您将获得一个样式映射，但是样式也可以作为组使用。它们是不可枚举的，所以除非显式地访问它们，否则它们不会显示出来。这使得在更高级的模块中只公开一个子集变得更容易。

-   `styles.modifier`
-   `styles.color`
-   `styles.bgColor`
-   `styles.underlineColor`

###### 样式组示例

```js
import styles from 'ansi-styles';

console.log(styles.color.green.open);
```

各样式的主要SGR参数见下 `styles.codes`，它返回 `Map` 打开代码作为键，关闭代码作为值。参数化的样式，例如 `4:2` 和 `58;5;0` 都是由它们的首要参数决定的， `4` 和 `58` 分别。

###### 样式代码示例

```js
import styles from 'ansi-styles';

console.log(styles.codes.get(36));
//=> 39
```

## 16 / 256 / 1600万（TrueColor）支持

`ansi-styles` 允许在各种颜色格式和ANSI转义之间进行转换，支持16,256和 [1600万种颜色](https://github.com/termstandard/colors)。

支持以下颜色空间：

-   `rgb`
-   `hex`
-   `ansi256`
-   `ansi`

要使用这些，使用预期的输出调用相关的转换函数，例如：

```js
import styles from 'ansi-styles';

styles.color.ansi(styles.rgbToAnsi(100, 200, 15)); // RGB to 16 color ansi foreground code
styles.bgColor.ansi(styles.hexToAnsi('#C0FFEE')); // HEX to 16 color ansi foreground code

styles.color.ansi256(styles.rgbToAnsi256(100, 200, 15)); // RGB to 256 color ansi foreground code
styles.bgColor.ansi256(styles.hexToAnsi256('#C0FFEE')); // HEX to 256 color ansi foreground code
styles.underlineColor.ansi(styles.rgbToAnsi(100, 200, 15)); // RGB to underline code using the first 16 palette entries

styles.color.ansi16m(100, 200, 15); // RGB to 16 million color foreground code
styles.bgColor.ansi16m(...styles.hexToRgb('#C0FFEE')); // Hex (RGB) to 16 million color foreground code

styles.underlineColor.ansi256(styles.hexToAnsi256('#C0FFEE')); // HEX to 256 color underline code
styles.underlineColor.ansi16m(...styles.hexToRgb('#C0FFEE')); // Hex (RGB) to 16 million color underline code
```

## 相关

-   [ansi-escapes](https://github.com/sindresorhus/ansi-escapes) -用于操作终端的ANSI转义码

## 维护人员

-   [Sindre Sorhus](https://github.com/sindresorhus)
-   [Josh Junon](https://github.com/qix-)

## 常见问题

### ansi-styles 是什么？

在终端中样式化字符串的ANSI转义码

### 如何安装 ansi-styles？

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

### ansi-styles 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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