# @elastic/pretty-printer 中文文档

规范地址：https://npmcn.com/package/%40elastic/pretty-printer/

版本：4\.39\.0
npm 元数据更新时间：2026-11-11T12:58:21.160Z
中文译文更新时间：2026-11-13T10:36:58.624Z
软件包许可：Elastic-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40elastic/pretty-printer
原文对照：https://npmcn.com/package/%40elastic/pretty-printer/?lang=original
源码仓库：https://github.com/elastic/esql-js

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

- 包体积（解压后）：159 kB，22 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-07-02T10:28:03.687Z
- 最新版本发布：2026-11-11T12:58:20.810Z
- 近 30 天下载量：549280（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

一个通用的Wadler-Lindig文档代数和布局引擎,用于宽度感知的漂亮打印.

## 安装

```sh
npm install @elastic/pretty-printer
```

也可以使用：`pnpm add @elastic/pretty-printer`、`yarn add @elastic/pretty-printer`、`bun add @elastic/pretty-printer`

## README

# @ 有弹性/ 漂亮- 打印器

基于 Wadler- Lindig 文档的通用美化打印库 代数( Philip Wadler, _"一个更漂亮的打印机"_, 2003; 克里斯蒂安·林迪格严格 (第3条)。 执行在很大程度上取自普雷蒂埃的内部 `doc-printer`。 。 。 .

它没有包含ESQQL, PromQL, 或其他域知识—— 它是独立的 使用的布局引擎 `@elastic/esql`画得很漂亮,出版过很多 工程可以在同一项目上构建宽度认识格式 `Doc` IR (英语).

## 安装

```sh
npm install @elastic/pretty-printer
```

## 如何运作

漂亮印刷是一个两相过程:

1.  **构建** (单位:千美元) _文档树_ (单位:千美元)`Doc`)使用组合器(见下文)。 树 描述 _结构_ 它没有混凝土线 断裂或缩进.
2.  **版式** 树变成一串混凝土 排版引擎是否适合 尽可能在每一行(最多 `printWidth`),断开 `group` 平面显示会超过可用宽度的节点.

示例

```ts
import { text, group, indent, line, softline, join, layout } from '@elastic/pretty-printer';

const doc = group([
  text('SELECT'),
  indent([line, join(
    [text(','), line],
    [text('a'), text('b'), text('c')])]
  ),
  line,
  text('FROM t'),
]);

layout(doc, { printWidth: 40 });
// SELECT
//   a,
//   b,
//   c
// FROM t

layout(doc, { printWidth: 80 });
// SELECT a, b, c FROM t
```

## `layout(tree, opts?)`

主入门. 需要一个 _打印树_ 并返回已格式化的字符串.

选项 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `printWidth` | `number` | `80` | 目标最大行宽. |
| `tabWidth` | `number` | `2` | 每个缩进的空格 . |
| `useTabs` | `boolean` | `false` | 缩进分页而不是空格. |
| `endOfLine` | `'\n'` | `'\r\n'` | `'\r'` | `'\n'` | 线起字符. |

## 组合符/命令

打印机提供一组用于构建打印的梳理器( 或“ 命令 ”) 树 这些是描述产出结构的构件.

### 初级

-   `text(string)` ——文字,以正字印刷. 必须 **没有** 包含 新行字符.
-   `Doc[]` (阵)——协和. 将一系列文件剩余到 对.

### 换行符

-   `line` —空间 `" "` 平面模式; _新行 + 缩进_ 在中断模式中.
-   `softline` - 没什么 `""` 平面模式; _新行 + 缩进_ 在中断模式中.
-   `hardline` 总是 _新行 + 缩进_。强迫附件组 中断.
-   `hardlineWithoutBreakParent` - 喜欢 `hardline` 但确实 **没有** 部队 要打破的母组.
-   `literalline` - 硬线断开后缩进 _根号_ 职位 (设置于 `markAsRoot`)取而代之的是目前的筑巢水平. 保留 正在沿着白色空间。 包围各集团的军队要瓦解.
-   `literallineWithoutBreakParent` - 喜欢 `literalline` 但确实 **没有** 强制母组断开.

### 分组

-   `group(tree, opts?)` ——核心断裂决定单元. 尝试制作 打印树节点平平(单行)。 如果超过所剩宽度,则开关 以中断模式。 选项 : `shouldBreak` (断力), `id` (符号表示 与 `ifBreak`编号 :`indentIfBreak`) (中文(简体) ).
-   `conditionalGroup(states, opts?)` ——多州集团. 提供 从最紧凑到最扩展的替代布局。 发动机各试一试 顺序并使用第一个适合的;如果一个适合,最后一个状态是 以中断模式提供.
-   `fill(parts)` ——包装布局. `parts` 在内容和 换行文件 : `[item, line, item, line, ...]`填充每行 许多在断裂前合适的物品——不同于 `group`,这是所有或什么都没有.

### 缩进

-   `indent(tree)` ——将缩进增加一个分页级别.
-   `align(n, tree)` 精确地增加缩进 `n` 空格( 不为 选项卡级别)。 特殊值 : `-1` (第一级), `Number.NEGATIVE_INFINITY` (重置为根), `{ type: 'root' }` (当前标记) 缩入为根).
-   `dedent(tree)` 将缩进减少一个级别。 简指 `align(-1, tree)`。 。 。 .
-   `dedentToRoot(tree)` ——将缩进重置为根(栏0或 职位设置 `markAsRoot`) (中文(简体) ).
-   `markAsRoot(tree)` ——将当前缩进标为"根" 职位 `literalline`。 。 。 .

### 有条件的内容

-   `ifBreak(breakDoc, flatDoc?, opts?)` - 释放 `breakDoc` 当 附加组(或引用的组) `groupId`处于中断模式; 否则会发射 `flatDoc`。 。 。 .
-   `indentIfBreak(tree, opts)` 有条件地缩进 `doc` 基于 引用组模式 。 优化形式 `ifBreak(indent(tree), doc, { groupId })`设置 `negate: true` 倒转.
-   `breakParent` ——强迫所有先辈群体决裂. 宣传期间 预通( :`propagateBreaks`) (中文(简体) ).

### 注释行后缀( L)

-   `lineSuffix(tree)` - 缓冲 `doc` 并放出在电流末端 线条,就在下行中断前。 用于跟踪评论.
-   `lineSuffixBoundary` - 强行取消任何待决事项 `lineSuffix` 内容. 防止跟踪评论泄露过去的合成边界.

### 杂项

-   `label(lbl, tree)` 注释一个不透明标签的医生 语言特异性heuristic introduction. 中国植物物种信息数据库. 没有影响布局 .
-   `trim` —— 从当前输出中删除所有后端的空白 立场.
-   `cursor` 用于光标位置跟踪的占位符。 排版引擎 发出一个监视器; 呼叫者可以找到它, 以保存光标位置 格式化.
-   `join(separator, trees)` - 加入一系列文件与 `separator` 每一对之间.
-   `bracketedList(open, close, sep, items)` - 分组的方便, 缩入括号内的清单。 平地 : `(a, b, c)`断开 :
    
    ```
    (
      a,
      b,
      c
    )
    ```
    
-   `addAlignmentToDoc(doc, size, tabWidth)` - 转换绝对值 缩入巢中大小 `indent`编号 :`align` 内部包装 `dedentToRoot`。 。 。 . 用于嵌入内容需要特定的缩进级.

## 倾斜

-   `traverse(doc, { onEnter?, onExit? })` - 一般深度第一横贯 使用显式堆栈(不重复)的多克树。 返回时 `false` 从 `onEnter` 跳过节点的孩子.

## 常见问题

### @elastic/pretty-printer 是什么？

一个通用的Wadler-Lindig文档代数和布局引擎,用于宽度感知的漂亮打印\.

### 如何安装 @elastic/pretty-printer？

在项目目录运行 npm install @elastic/pretty-printer，或使用 pnpm add / yarn add / bun add。

### @elastic/pretty-printer 支持 TypeScript 吗？

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

### @elastic/pretty-printer 支持 ESM 还是 CommonJS？

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

### @elastic/pretty-printer 可以商用吗？

@elastic/pretty-printer 使用 Elastic-2\.0 许可。声明的许可为 Elastic-2\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @elastic/pretty-printer 的下载量有多少？

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

### @elastic/pretty-printer 还在维护吗？

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