# @cjser/cli-truncate 中文文档

规范地址：https://npmcn.com/package/%40cjser/cli-truncate/

版本：6\.2\.0-cjser\.2
npm 元数据更新时间：2026-10-31T18:23:04.463Z
中文译文更新时间：2026-10-31T19:54:28.137Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cjser/cli-truncate
原文对照：https://npmcn.com/package/%40cjser/cli-truncate/?lang=original
源码仓库：https://code.moenext.com/3rdeye/cjser

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

- 包体积（解压后）：24.7 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2026-05-07T05:07:39.834Z
- 最新版本发布：2026-10-31T18:23:04.289Z
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

将字符串截断为终端中的特定宽度

## 安装

```sh
npm install @cjser/cli-truncate
```

也可以使用：`pnpm add @cjser/cli-truncate`、`yarn add @cjser/cli-truncate`、`bun add @cjser/cli-truncate`

## README

# cli-truncate

> 将字符串截断为终端中的特定宽度

优雅地处理 [ANSI逃](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors_and_Styles)． 就像一个字符串样式 [`chalk`](https://github.com/chalk/chalk)． 它还支持Unicode代理字符对和全宽字符。

## 安装

```sh
npm install cli-truncate
```

## 使用

```js
import cliTruncate from 'cli-truncate';

cliTruncate('unicorn', 4);
//=> 'uni…'

// Truncate at different positions
cliTruncate('unicorn', 4, {position: 'start'});
//=> '…orn'

cliTruncate('unicorn', 4, {position: 'middle'});
//=> 'un…n'

cliTruncate('unicorns rainbow dragons', 6, {position: 'end'});
//=> 'unico…'

cliTruncate('\u001B[31municorn\u001B[39m', 4);
//=> '\u001B[31muni…\u001B[39m'

// Truncate Unicode surrogate pairs
cliTruncate('uni\uD83C\uDE00corn', 6);
//=> 'uni\uD83C\uDE00…'

// Truncate fullwidth characters
cliTruncate('안녕하세요', 3);
//=> '안…'

// Truncate the paragraph to the terminal width
const paragraph = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.';
cliTruncate(paragraph, process.stdout.columns ?? 80);
//=> 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula…'
```

> \[!请注意) 截断样式文本（ANSI转义）时，截断字符在断点处继承为的样式 `position: 'start'` 和 `position: 'end'`． 这并不适用于 `position: 'middle'`.

## API

### 拼写（文本、列、选项？）

#### 文本

类型: `string`

要截断的文本。

#### 列

类型: `number`

在终端中占用的有限列数。

#### 选项

类型: `object`

##### 位置

类型: `string`  
默认值: `'end'`  
价值观: `'start' | 'middle' | 'end'`

截断字符串的位置。

##### 空间

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

在文本和省略号之间添加一个空格。

```js
import cliTruncate from 'cli-truncate';

cliTruncate('unicorns', 5, {space: false});
//=> 'unic…'

cliTruncate('unicorns', 5, {space: true});
//=> 'uni …'

cliTruncate('unicorns', 6, {position: 'start', space: true});
//=> '… orns'

cliTruncate('unicorns', 7, {position: 'middle', space: true});
//=> 'uni … s'
```

##### preferTruncationOnSpace

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

如果距离实际断点在3个字符以内，则用空格截断字符串。

```js
import cliTruncate from 'cli-truncate';

cliTruncate('unicorns rainbow dragons', 20, {position: 'start', preferTruncationOnSpace: true});
//=> '…rainbow dragons'

// Without preferTruncationOnSpace
cliTruncate('unicorns rainbow dragons', 20, {position: 'start'});
//=> '…rns rainbow dragons'

cliTruncate('unicorns rainbow dragons', 20, {position: 'middle', preferTruncationOnSpace: true});
//=> 'unicorns…dragons'

cliTruncate('unicorns rainbow dragons', 6, {position: 'end', preferTruncationOnSpace: true});
//=> 'unico…'

// preferTruncationOnSpace has no effect if space isn't found within 3 characters
cliTruncate('unicorns rainbow dragons', 6, {position: 'middle', preferTruncationOnSpace: true});
//=> 'uni…ns'
```

##### truncationCharacter

类型: `string`  
默认值: `…`

在断点处使用的字符。

```js
import cliTruncate from 'cli-truncate';

cliTruncate('unicorns', 5, {position: 'end'});
//=> 'unic…'

cliTruncate('unicorns', 5, {position: 'end', truncationCharacter: '.'});
//=> 'unic.'

cliTruncate('unicorns', 5, {position: 'end', truncationCharacter: ''});
//=> 'unico'
```

## 相关

-   [wrap-ansi](https://github.com/chalk/wrap-ansi) -用ANSI转义码对字符串进行换行
-   [slice-ansi](https://github.com/chalk/slice-ansi) -使用ANSI转义码对字符串进行切片

## cjser

这个包是由cjser为仍然需要的项目生成的commonjs兼容的构建 `require()` 支持。源版本与原始的npm包版本匹配，对这个生成的构建带有cjser预发布后缀。 原始存储库: [https://github.com/sindresorhus/cli-truncate](https://github.com/sindresorhus/cli-truncate)

## 常见问题

### @cjser/cli-truncate 是什么？

将字符串截断为终端中的特定宽度

### 如何安装 @cjser/cli-truncate？

在项目目录运行 npm install @cjser/cli-truncate，或使用 pnpm add / yarn add / bun add。

### @cjser/cli-truncate 支持 TypeScript 吗？

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

### @cjser/cli-truncate 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cjser/cli-truncate 需要什么版本的 Node\.js？

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

### @cjser/cli-truncate 可以商用吗？

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

### @cjser/cli-truncate 还在维护吗？

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