在Web编辑器中集成JS HTML格式化功能的实现步骤

一、准备工作与技术选型

在实现HTML格式化之前，首先需要明确格式化执行的宿主环境与解析策略。浏览器端对HTML的排版不能简单使用正则表达式全局替换，因为HTML存在单标签、自闭合标签、嵌套元素、属性中包含引号与特殊字符，以及<pre>、<code>、<script>等空格敏感标签。

在主流技术选型中，业界常用成熟、轻量且纯JavaScript实现的排版库js-beautify（包含html_beautify模块）。它在体积（压缩后约数十KB）、跨浏览器兼容性以及丰富的自定义规则配置方面表现均衡，无需依赖复杂的Node环境即可直接在前端页面或Web Worker中运行。

二、步骤一：引入与配置格式化核心依赖

集成格式化功能的第一步是将解析引擎引入项目中。根据Web工程的构建方式不同，可以选择现代ESM模块方式、npm包方式或直接通过CDN引入。

1. ESM / npm 引入方式

在基于Vite、Webpack等打包工具的现代前端工程中，通过npm安装依赖：

npm install js-beautify --save

在代码中按需引入HTML格式化专用模块：

import { html as beautifyHtml } from 'js-beautify';

2. 静态页面 CDN / 独立脚本引入

如果在无构建工具的传统静态页面或简单的演示环境中，可通过Script标签引入：

<script src="https://cdn.jsdelivr.net/npm/js-beautify@1.14.9/js/lib/beautify-html.min.js"></script>
<!-- 引入后全局暴露 window.html_beautify 方法 -->

3. 制定核心格式化选项配置

HTML排版需要根据团队规范定义缩进量、最大行宽以及对特殊标签的处理策略。定义一个通用配置对象：

const defaultFormatOptions = {
  indent_size: 2,                  // 缩进空格数，通常为2或4
  indent_char: ' ',                // 缩进填充字符
  max_preserve_newlines: 1,        // 最多连续保留的空行数
  preserve_newlines: true,         // 是否保留已有空行
  wrap_line_length: 100,           // 单行最大字符数，超出则合理折行
  wrap_attributes: 'auto',         // 属性折行规则：auto | force | force-aligned
  unformatted: ['pre', 'code'],    // 严禁重新排版的标签列表，保护内部空格格式
  content_unformatted: ['pre'],    // 内容保护标签
  extra_liners: ['head', 'body', '/html'], // 需要额外换行隔开的一级结构标签
  end_with_newline: true           // 文件末尾保留一个空行
};

三、步骤二：编写HTML格式化核心适配函数

核心适配函数的主要职责是接收未排版的字符串，校验输入的有效性，在出现语法残缺或解析异常时提供降级保护，避免编辑器内容被意外清空或损坏。

/**
 * 格式化 HTML 字符串安全适配器
 * @param {string} rawHtml - 编辑器提取的原始HTML字符串
 * @param {Object} customOptions - 覆盖配置项
 * @returns {string} - 排版规整的HTML字符串
 */
function formatHtmlText(rawHtml, customOptions = {}) {
  // 1. 边界检测：空文本直接返回
  if (!rawHtml || typeof rawHtml !== 'string') {
    return rawHtml || '';
  }

  // 2. 合并配置项
  const options = Object.assign({}, defaultFormatOptions, customOptions);

  try {
    // 3. 执行核心排版逻辑
    const formatter = window.html_beautify || beautifyHtml;
    if (typeof formatter !== 'function') {
      throw new Error('未检测到有效的 HTML 格式化引擎实例');
    }
    return formatter(rawHtml, options);
  } catch (error) {
    // 4. 容错兜底：若排版发生异常，保留原代码并向控制台输出警告
    console.warn('[HTML Formatter] 排版执行失败，已保留原始内容:', error);
    return rawHtml;
  }
}

四、步骤三：绑定编辑器交互事件与快捷键

格式化功能通常通过两种方式触发：界面的“格式化”按钮点击，以及业内通用的快捷键操作（Windows/Linux 下为 Alt + Shift + F，macOS 下为 Option + Shift + F）。

不同的Web编辑器容器其取值与设值API存在差异，下面以原生 textarea、现代轻量级 CodeMirror 以及生产级 Monaco Editor 分别展示挂载方式：

1. 原生 DOM Textarea 挂载示例

function bindTextareaFormatter(textareaEl, buttonEl) {
  const triggerFormat = () => {
    const originalText = textareaEl.value;
    const formatted = formatHtmlText(originalText);
    if (formatted !== originalText) {
      // 利用原生命令写入，保留基础撤销历史
      textareaEl.focus();
      textareaEl.select();
      document.execCommand('insertText', false, formatted);
    }
  };

  // 按钮触发
  if (buttonEl) {
    buttonEl.addEventListener('click', triggerFormat);
  }

  // 快捷键监听 (Alt + Shift + F)
  textareaEl.addEventListener('keydown', (e) => {
    if (e.altKey && e.shiftKey && (e.key === 'F' || e.key === 'f')) {
      e.preventDefault();
      triggerFormat();
    }
  });
}

2. Monaco Editor 官方集成方式

在 VS Code 网页版同款的 Monaco Editor 中，最佳实践并非手动监听按键，而是注册 Monaco 内置的 DocumentFormattingEditProvider，让其自动与编辑器的右键菜单、命令面板（F1）和快捷键系统无缝融合：

// 为 Monaco 的 html 语言注册官方格式化提供者
monaco.languages.registerDocumentFormattingEditProvider('html', {
  provideDocumentFormattingEdits(model, options, token) {
    const fullRange = model.getFullModelRange();
    const rawText = model.getValue();
    const formattedText = formatHtmlText(rawText, {
      indent_size: options.tabSize,
      indent_char: options.insertSpaces ? ' ' : '\t'
    });

    return [
      {
        range: fullRange,
        text: formattedText
      }
    ];
  }
});

五、步骤四：处理格式化后的光标定位与撤销历史

很多简单的集成容易出现一个让使用者非常沮丧的问题：点击格式化后，编辑器光标瞬间跳回到文档最顶部第0行，或者按下 Ctrl + Z 无法恢复到排版前的状态。

这是因为直接使用 editor.value = newText 会将输入框的整个底层DOM节点重置，导致撤销历史链条被斩断，选择区（Selection Range）丢失。

1. 光标相对位置映射算法

在排版过程中，代码内部新增了大量换行和空格，导致字符总数发生改变。要将光标恢复到用户正在编辑的相同代码位置，需要根据“光标前面的有效字符数量（非空白字符）”进行坐标重定位：

/**
 * 根据非空白字符数量映射新文本中的光标位置
 * @param {string} oldText - 格式化前文本
 * @param {string} newText - 格式化后文本
 * @param {number} oldCursor - 格式化前光标位置索引
 * @returns {number} - 格式化后的新光标索引
 */
function calculateNewCursorPosition(oldText, newText, oldCursor) {
  // 提取旧光标之前的文本，计算非空白字符总数
  const prefix = oldText.slice(0, oldCursor);
  const nonWhitespaceCount = prefix.replace(/\s/g, '').length;

  if (nonWhitespaceCount === 0) return 0;

  // 在新文本中向前扫描，直到遇到相同数量的非空白字符
  let count = 0;
  for (let i = 0; i < newText.length; i++) {
    if (!/\s/.test(newText[i])) {
      count++;
    }
    if (count === nonWhitespaceCount) {
      return i + 1; // 恢复至该字符之后
    }
  }

  return newText.length;
}

2. 原子化事务回写

对于现代编辑器，必须使用其自带的事务 API（如 Monaco 的 editor.executeEdits() 或 CodeMirror 6 的 view.dispatch()）进行单步变更替换。这样，格式化过程会被视作一个原子化操作（Atomic Operation），用户只需按一次 Ctrl + Z 即可完整回退至排版前状态。

六、步骤五：大文件性能优化——引入 Web Worker 异步执行

当HTML文档体积达到数百KB或数万行标签时，执行词法分词和AST树遍历可能需要数十毫秒至数百毫秒。如果直接在浏览器主线程运行，会导致页面出现明显的掉帧甚至UI卡顿。

解决方案是将排版计算剥离至后台的 Web Worker 中异步执行：

// 1. 定义 worker 脚本 (html-format.worker.js)
self.onmessage = function (e) {
  const { id, code, options } = e.data;
  try {
    // 假设 worker 内部已 importScripts 引入 beautify
    const formatted = self.html_beautify(code, options);
    self.postMessage({ id, success: true, result: formatted });
  } catch (err) {
    self.postMessage({ id, success: false, error: err.message, result: code });
  }
};

// 2. 主线程异步调用封装
class AsyncHtmlFormatter {
  constructor(workerUrl) {
    this.worker = new Worker(workerUrl);
    this.requestId = 0;
    this.callbacks = new Map();

    this.worker.onmessage = (e) => {
      const { id, result } = e.data;
      if (this.callbacks.has(id)) {
        const resolve = this.callbacks.get(id);
        this.callbacks.delete(id);
        resolve(result);
      }
    };
  }

  format(code, options) {
    return new Promise((resolve) => {
      const id = ++this.requestId;
      this.callbacks.set(id, resolve);
      this.worker.postMessage({ id, code, options });
    });
  }
}

七、步骤六：结果验证与边界场景测试

功能编写完成后，需要使用多种边界情况的HTML代码对格式化功能进行全面验证。下表列出了关键测试场景及预期结果：

八、常见问题排查与注意事项

1. 为什么格式化后页面展示的文字空格变了？

在 HTML 标准规范中，普通的连续空格和换行符在渲染时会被折叠为一个空格。但如果在 <pre> 或带有 CSS white-space: pre 的容器内，格式化工具擅自添加的缩进空格会被真实渲染出来。 排查对策：必须确保配置中的 unformatted 数组包含 'pre'、'code'、'textarea' 等元素。

2. 为什么连续按快捷键会导致多次重复计算？

当用户频繁敲击格式化快捷键时，若上一次格式化尚未完成即触发下一次，会产生竞态条件并浪费计算资源。 解决对策：在触发函数上增加防抖（Debounce）或者执行锁标记（isFormatting），在当前排版未结束前忽略重复触发。