js-beautify库在浏览器端格式化HTML代码的用法

一、浏览器端环境准备与资源引入方式

js-beautify 最初由 Node.js 生态广为人知，但其官方仓库一直为浏览器环境提供了独立打包的脚本文件。在浏览器中处理 HTML 代码时，开发者只需引入负责 HTML 逻辑的专门子包，而不需要加载庞大的 CSS 或 JS 格式化器，从而降低网络体积与执行开销。

1. 通过 CDN 标签直接引入

在传统的多页面应用、后台管理系统或独立的在线工具页中，最简单的方式是通过 CDN 的 <script> 标签引入。js-beautify 将不同语言的格式化器进行了拆分：

• 独立 HTML 格式化包（推荐）：引入 beautify-html.min.js。该文件仅包含 HTML 词法解析器与缩进引擎，体积精简，加载完成后会在全局对象上挂载 window.html_beautify 函数。
• 多语言聚合包：引入 beautifier.min.js。该文件聚合了 JavaScript、CSS 与 HTML 三合一的格式化能力，挂载在 window.beautifier 上，同时保持对全局 html_beautify 的兼容映射。

<!-- 推荐：仅引入浏览器端 HTML 专用格式化包 -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/js-beautify/1.15.1/beautify-html.min.js"></script>

<script>
  // 检查类库是否加载成功
  if (typeof window.html_beautify === 'function') {
    console.log('js-beautify HTML 模块就绪');
  }
</script>

2. 在现代工程化构建项目中模块化导入（Vite / Webpack）

在使用 Vue、React 或 Angular 等构建体系的前端项目中，可以通过包管理器安装并在具体业务组件中按需导入。js-beautify 内部会自动判断环境，在浏览器打包时直接提供符合 ESM 或 CommonJS 规范的纯 JavaScript 实现：

// 终端安装
// npm install js-beautify

// 业务组件中按需导入
import { html_beautify } from 'js-beautify';

// 或者导入完整套件
import beautifier from 'js-beautify';
const formatHtml = beautifier.html;

二、核心 API 快速上手与四个标准步骤

在浏览器端，格式化调用的核心 API 极其直接：html_beautify(html_source, options)。它接收一个未排版的 HTML 字符串以及一个可选的配置对象，同步返回经过缩进对齐与折行调整后的全新字符串。

为了确保从用户输入到界面呈现的稳定性，一次标准的前端格式化操作通常划分为四个关键步骤：

1. 引入并验证类库依赖：确保 html_beautify 函数在当前运行上下文中可用，避免因异步加载导致方法未定义。
2. 构建规则配置对象：根据业务呈现要求定义缩进量（如 2 空格或 4 空格）、换行限制及特定免排版标签。
3. 执行格式化转换：将原始 HTML 文本与配置参数传入 html_beautify() 并捕获转换结果。
4. 安全输出并挂载展示：将结果安全填充到展示容器（如 <pre><code> 或 <textarea>）中，避免直接操作非转义 innerHTML。

下面是一个完整的、可直接在浏览器中运行的原生 HTML + JS 实操范例：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>js-beautify 浏览器端实战范例</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/js-beautify/1.15.1/beautify-html.min.js"></script>
  <style>
    .box { display: flex; gap: 16px; margin-top: 10px; }
    textarea, pre { width: 48%; height: 260px; font-family: monospace; font-size: 13px; }
    pre { background: #1e1e1e; color: #d4d4d4; padding: 12px; overflow: auto; border-radius: 4px; }
  </style>
</head>
<body>
  <h3>HTML 实时在线格式化</h3>
  <button id="formatBtn">执行格式化</button>

  <div class="box">
    <textarea id="inputHtml" placeholder="在此粘贴凌乱的 HTML 代码..."><div class="card"><h1>测试标题</h1><p>一段示例文本<span>高亮</span></p><ul><li>列表1</li><li>列表2</li></ul></div></textarea>
    <pre><code id="outputDisplay"></code></pre>
  </div>

  <script>
    document.getElementById('formatBtn').addEventListener('click', function() {
      const rawHtml = document.getElementById('inputHtml').value;
      
      // 步骤 2：定制配置项
      const options = {
        indent_size: 2,
        indent_char: ' ',
        max_preserve_newlines: 1,
        preserve_newlines: true,
        indent_inner_html: false,
        wrap_line_length: 80,
        extra_liners: []
      };

      // 步骤 3：调用核心方法
      const formatted = window.html_beautify(rawHtml, options);

      // 步骤 4：安全赋值给展示容器（使用 textContent 防止代码被当作真实 DOM 执行）
      document.getElementById('outputDisplay').textContent = formatted;
    });
  </script>
</body>
</html>

三、常用配置项详解与场景调优

html_beautify 提供了丰富的参数选项，用于精确控制 HTML 标签的嵌套层次、空行留白以及行内元素的换行规则。如果使用默认配置，部分标签（如 <head>、<body>）之前会自动插入额外的空行，且每级缩进默认为 4 个空格。在不同的前端场景中，通常需要针对性地进行微调。

典型配置模版推荐

在工程开发中，常见的排版诉求主要分为两类：一是编辑器或对话框中的代码局部预览，二是整页 HTML 文档的标准化格式化。以下提供两套经过实践检验的配置预设：

// 预设 A：局部 HTML 代码片段预览（轻量、紧凑、无冗余空行）
const snippetOptions = {
  indent_size: 2,
  indent_char: ' ',
  preserve_newlines: true,
  max_preserve_newlines: 1,
  wrap_line_length: 0,          // 保持单行自然长度，配合 CSS 滚动条
  extra_liners: [],             // 清空默认插入空行规则
  indent_inner_html: true,
  content_unformatted: ['pre', 'textarea', 'code']
};

// 预设 B：标准完整 HTML 页面排版（适合代码导出与整篇展示）
const fullPageOptions = {
  indent_size: 4,
  indent_char: ' ',
  preserve_newlines: true,
  max_preserve_newlines: 2,
  wrap_line_length: 100,        // 超长标签属性自动换行对齐
  extra_liners: ['head', 'body', '/html'],
  indent_inner_html: false,     // 保持 head 与 body 顶格，符合常见代码风格
  end_with_newline: true        // 文件末尾保留一个换行符
};

四、进阶场景与工程化注意事项

1. 大文本排版与 Web Worker 异步解耦

由于 JavaScript 在浏览器中单线程运行，html_beautify 的语法分析和正则匹配完全依赖主线程 CPU。当处理体积超过 50KB（或上千行深层嵌套 DOM）的复杂 HTML 时，同步格式化调用可能产生 100ms 至数秒的执行延迟，直接导致浏览器页面出现卡顿、无法响应点击或掉帧。

在生产级工程中，处理大文本或频繁自动格式化（如实时监听输入）时，应当将格式化任务转移到 Web Worker 中执行：

// worker.js: 后台格式化工作线程
importScripts('https://cdnjs.cloudflare.com/ajax/libs/js-beautify/1.15.1/beautify-html.min.js');

self.onmessage = function(e) {
  const { code, options } = e.data;
  try {
    const result = html_beautify(code, options);
    self.postMessage({ success: true, data: result });
  } catch (err) {
    self.postMessage({ success: false, error: err.message });
  }
};

在主页面中通过异步 Promise 调用 Worker，主界面在计算过程中依然能保持平滑动画和流畅交互：

// main.js: 主线程封装调用
const beautifyWorker = new Worker('worker.js');

function formatHtmlAsync(code, options) {
  return new Promise((resolve, reject) => {
    beautifyWorker.onmessage = (e) => {
      if (e.data.success) resolve(e.data.data);
      else reject(new Error(e.data.error));
    };
    beautifyWorker.postMessage({ code, options });
  });
}

2. 浏览器端输出安全与 XSS 防护

必须明确：js-beautify 是一个代码排版格式化工具，它不承担任何 HTML 安全清洗（Sanitization）或防 XSS 注入的职责。如果代码中包含恶意的 <img src=x onerror=alert(1)>，格式化器会如实保留并为其排版。

• 纯代码展示场景：必须使用 element.textContent = result 或将结果赋给 <textarea>.value。浏览器会将所有标签符号自动作为纯文本实体处理，杜绝脚本执行。
• DOM 实时预览场景：如果业务需要将格式化后的 HTML 实时渲染为页面可视元素（例如富文本所见即所得编辑器），在注入 innerHTML 前必须通过专门的安全清洗库（如 DOMPurify.sanitize(result)）去除潜在恶意脚本。

五、常见问题与排错指南

1. 为什么控制台报错“html_beautify is not defined”？

这通常是由以下两个原因引起的：

• 引入了错误的语言子包：CDN 上提供了 beautify-css.min.js 和 beautify.min.js。如果仅引入了 CSS 单独子包，全局对象上将只有 css_beautify，不存在 html_beautify。必须确认加载的是 beautify-html.min.js。
• 脚本加载时序问题：如果通过动态创建 script 标签或异步属性（async/defer）加载脚本，在脚本尚未下载解析完毕前就调用该函数会引发报错。应确保在 onload 回调中或 DOMContentLoaded 后触发调用。

2. 为什么 <pre> 或 <textarea> 内的代码排版错乱？

<pre> 标签对内部的换行与空格极为敏感。如果原 HTML 中包含 <pre>，而配置中的 content_unformatted 未将其包含在内，格式化器会强行给其中的代码每行追加缩进空格，导致渲染到界面时缩进成倍增加。排查时应确保 options.content_unformatted 显式包含 'pre' 与 'textarea'。

3. 为什么标签的属性没有自动换行对齐？

默认情况下，wrap_line_length 设为 0，表示对长行不进行约束。即使一个 <div> 上写了十几个 class 和 data 属性，格式化器也不会主动将其折叠为多行。如果希望长属性列表换行排版，应将 wrap_line_length 设为一个合理的数值（如 80），并可配合 wrap_attributes: "force-aligned" 参数，强制将换行后的属性与首个属性垂直对齐。