# @ciolabs/html-email-formatter 中文文档

规范地址：https://npmcn.com/package/%40ciolabs/html-email-formatter/

版本：0\.0\.5
npm 元数据更新时间：2026-02-19T20:52:33.451Z
中文译文更新时间：2026-11-09T16:25:11.711Z
软件包许可：Apache-2\.0 WITH Commons-Clause

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

原始 npm 页面：https://www.npmjs.com/package/%40ciolabs/html-email-formatter
原文对照：https://npmcn.com/package/%40ciolabs/html-email-formatter/?lang=original
项目主页：https://github.com/customerio/ciolabs/tree/main/packages/html-email-formatter#readme
源码仓库：https://github.com/customerio/ciolabs

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

- 包体积（解压后）：66.7 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2025-09-18T17:04:30.993Z
- 最新版本发布：2026-02-19T20:52:33.107Z
- 近 30 天下载量：20256（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 3 个）

## 中文简介

HTML 电子邮件内容的格式和预设

## 安装

```sh
npm install @ciolabs/html-email-formatter
```

也可以使用：`pnpm add @ciolabs/html-email-formatter`、`yarn add @ciolabs/html-email-formatter`、`bun add @ciolabs/html-email-formatter`

## README

# @ciolabs/html-电子邮件-formatter

> 用有条件的注释支持格式化并预设 HTML 电子邮件内容

电子邮件 HTML 经常包含 Microsoft Outlook 有条件的评论(`<!--[if mso]>`在格式化过程中需要特殊处理。 标准 HTML 格式化器可以打破这些注释或错误地对齐它们的缩进. 这个软件包在保留有条件的注释结构和白空间的同时安全地格式化了电子邮件 HTML.

## 为什么?

在构建 HTML 电子邮件时, 您常常需要包含对 Microsoft Outlook 兼容性 的有条件的评论 :

```html
<div>
  <!--[if mso]>
<table><tr><td>
<![endif]-->
  <p>Email content</p>
  <!--[if mso]>
</td></tr></table>
<![endif]-->
</div>
```

标准 HTML 格式化器 :

-   断开有条件的注释语法
-   错误的打开和关闭标签
-   将批注周围的重要空白位置移出

这东西能正确处理这些边缘案件.

## 安装

```bash
npm install @ciolabs/html-email-formatter
```

## 使用量

```typescript
import emailFormatter from '@ciolabs/html-email-formatter';

const html = `
<div>
<!--[if mso]>
<table><tr><td>
<![endif]-->
<p>Email content</p>
<!--[if mso]>
</td></tr></table>
<![endif]-->
</div>
`;

const formatted = emailFormatter(html);
console.log(formatted);
```

输出 :

```html
<div>
  <!--[if mso]>
  <table>
    <tr>
      <td>
  <![endif]-->
  <p>Email content</p>
  <!--[if mso]>
      </td>
    </tr>
  </table>
  <![endif]-->
</div>
```

### 有选项

前题接受两个选项 [美丽](https://www.npmjs.com/package/pretty) 财务报告和审定财务报表 [js-美丽](https://www.npmjs.com/package/js-beautify)数字 :

```typescript
const formatted = emailFormatter(html, {
  indent_size: 4,
  wrap_line_length: 80,
  preserve_newlines: false,
});
```

## 如何运作

1.  **暂时结束有条件的评论** - 转换 `<!--[if mso]>content<![endif]-->` 改为 `<!--[if mso]>-->content<!--<![endif]-->` 因此格式化器可以处理内置的 HTML
2.  **保留注释白空格** - 用途 [@ciolabs/html-保温-comment-白空间](https://npmcn.com/package/%40ciolabs/html-preserve-comment-whitespace) 以在注释周围保持间隔
3.  **格式化 HTML** - 通过标准格式运行已修改的 HTML
4.  **恢复有条件的注释** - 转换回原有条件的注释语法
5.  **对齐缩进** - 确保打开和关闭标记的缩进一致

## API 密码

### `emailFormatter(html, options?)`

格式化 HTML 电子邮件内容,同时保留有条件的注释.

**参数:**

-   `html` (字符串) - HTML 内容到格式
-   `options` (对象,可选) - 组合格式选项 [漂亮的选项](https://www.npmjs.com/package/pretty#options) 财务报告和审定财务报表 [js 美化 HTML 选项](https://beautifier.io/)

**回返情况:**

-   (字符串) - 格式化的 HTML

**常见选项 :**

-   `indent_size` (数目) - 缩进空格数( 默认: 2)
-   `wrap_line_length` (数字) - 包接前行长( 默认: 80)
-   `preserve_newlines` (boolean) - 是否保留已存在的新行( 默认: 真)
-   `max_preserve_newlines` (数目) - 要保存的最大连续新行( 默认: 2)

## 常见问题

### @ciolabs/html-email-formatter 是什么？

HTML 电子邮件内容的格式和预设

### 如何安装 @ciolabs/html-email-formatter？

在项目目录运行 npm install @ciolabs/html-email-formatter，或使用 pnpm add / yarn add / bun add。

### @ciolabs/html-email-formatter 支持 TypeScript 吗？

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

### @ciolabs/html-email-formatter 支持 ESM 还是 CommonJS？

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

### @ciolabs/html-email-formatter 可以商用吗？

@ciolabs/html-email-formatter 使用 Apache-2\.0 WITH Commons-Clause 许可。声明的许可为 Apache-2\.0 WITH Commons-Clause，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @ciolabs/html-email-formatter 的下载量有多少？

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

### @ciolabs/html-email-formatter 还在维护吗？

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