前端实战：Javascript 格式化后的代码如何直接输出？

在前端开发日常中，我们经常需要在网页上展示代码，无论是技术博客、在线文档、教程示例，还是产品的功能演示，清晰、美观且易于阅读的代码展示都是不可或缺的。而直接输出未格式化的代码，往往难以辨认，影响用户体验。本文将深入探讨如何在前端项目中，将格式化后的 Javascript 代码（或其他语言代码）直接输出到网页上，并提供多种实现方案，从基础的 HTML/CSS 到高级的 JavaScript 库，以及性能优化和最佳实践。

引言：为何需要格式化代码输出？

想象一下，你正在阅读一篇技术文章，其中包含了一段核心代码示例。如果这段代码只是纯文本，没有语法高亮、没有正确的缩进，甚至在一行中挤满了字符，你会觉得难以阅读和理解。反之，如果代码按照其语法规则进行了颜色区分（如关键字、字符串、注释等），并保持了良好的缩进和结构，那么即使是复杂的功能也能一目了然。

格式化代码输出的价值体现在：

提升可读性： 语法高亮和缩进是代码可读性的基石。
增强用户体验： 美观的排版能让用户更愿意花时间阅读和学习。
减少理解成本： 格式化有助于快速识别代码结构和关键部分。
专业形象： 规范的代码展示体现了作者或产品对细节的关注。
易于复制和使用： 清晰的代码更容易被复制到开发环境中进行测试或修改。

本文将从最基础的 HTML 标签开始，逐步深入到使用 JavaScript 实现动态代码插入，最终聚焦于业界流行的语法高亮库，并探讨一些高级特性和实践考量。

第一章：基础篇——HTML 与 CSS 的基石

在所有花哨的 JavaScript 库之前，我们必须理解 HTML 和 CSS 在代码展示中的基本作用。

1.1 `<pre>` 和 `<code>` 标签：语义化与结构

在 HTML 中，pre 和 code 是用于表示代码内容的核心标签。

<pre> 标签（Preformatted Text）：
pre 标签用于定义预格式化的文本。这意味着标签内的文本将保留其源代码中的空格、缩进、换行等格式，而浏览器不会对其进行常规的文本流处理（如合并连续空格、自动换行）。它通常与等宽字体（monospace font）一起使用，以确保字符对齐。

html <pre> function greet(name) { console.log("Hello, " + name + "!"); } greet("World"); </pre>
<code> 标签（Code）：
code 标签用于表示计算机代码片段。它不强制保留格式（除非其父元素是 pre），但从语义上告诉浏览器和辅助技术，这段内容是代码。通常，code 标签内的文本也会以等宽字体显示。

当 code 标签作为 pre 标签的子元素时，它们共同提供了一种语义上和视觉上都非常适合展示代码块的方式。pre 负责保留格式和块级显示，code 负责标识内容为代码。

html <pre><code> function calculateSum(a, b) { // This is a comment return a + b; } const result = calculateSum(5, 10); console.log(result); // Output: 15 </code></pre>

1.2 CSS 基础样式：打造代码块外观

仅仅使用 <pre><code> 标签，代码虽然会保持格式，但外观可能过于简朴。我们可以通过 CSS 来美化它，使其更像一个专业的代码块。

“`css
/ 为代码块设置基本样式 /
pre {
background-color: #2d2d2d; / 深色背景，常见于代码编辑器 /
color: #f8f8f2; / 浅色字体，与深色背景对比鲜明 /
padding: 1em 1.5em; / 内边距 /
border-radius: 8px; / 圆角边框 /
font-family: ‘Fira Code’, ‘Cascadia Code’, ‘JetBrains Mono’, ‘Consolas’, monospace; / 等宽字体 /
font-size: 0.9em; / 字体大小 /
line-height: 1.5; / 行高 /
overflow-x: auto; / 当代码过长时显示水平滚动条 /
white-space: pre-wrap; / 允许在必要时自动换行，但保持原有空格和换行 /
word-break: break-all; / 允许在单词内断行，防止长单词溢出 /
}

/ 针对代码标签的样式，确保字体继承 /
code {
font-family: inherit; / 继承父元素 pre 的字体 /
color: inherit; / 继承父元素 pre 的颜色 /
}

/ 强调行内代码（如果需要，例如在普通文本中引用变量名） /
p > code {
background-color: rgba(135, 131, 120, 0.15);
padding: 0.2em 0.4em;
border-radius: 3px;
font-size: 0.85em;
margin: 0 0.1em;
}
“`

通过上述 CSS 规则，我们得到了一个拥有深色背景、浅色文字、圆角边框、等宽字体和水平滚动条的代码块。这大大提升了代码的视觉呈现效果。

局限性： 尽管 HTML 和 CSS 提供了基础的布局和样式，但它们无法实现语法高亮。所有代码仍然是同一种颜色，这对于理解复杂的代码逻辑仍有障碍。这就是 JavaScript 需要登场的地方。

第二章：进阶篇——JavaScript 与动态渲染

当代码内容是动态的，或者我们希望通过 JavaScript 来控制代码的插入和更新时，就需要用到 JavaScript 的 DOM 操作能力。

2.1 动态插入代码字符串

最直接的方法是获取一个代码字符串，然后将其插入到 pre 标签中。

“`html

动态插入代码

动态插入的 JavaScript 代码

“`

关键点：
* textContent vs innerHTML：在插入纯代码字符串时，务必使用 textContent。它会将所有内容视为纯文本，自动对 <、>、& 等 HTML 特殊字符进行转义，从而有效防止 XSS（跨站脚本攻击）风险。如果使用 innerHTML，则需要手动对代码字符串中的 HTML 特殊字符进行转义。
* .trim()：去除字符串开头和结尾的空白字符，使代码对齐更美观。

2.2 处理 HTML 特殊字符：安全与转义

如果你的代码字符串中包含 HTML 标签的字符（例如 <div> 中的 < 和 >），当使用 textContent 插入时，它们会被正确地显示为 < 和 >。但如果你因为某种特殊需求，非要使用 innerHTML 来插入代码（例如，你希望在代码中包含一些自定义的 HTML 标记，尽管这在代码展示中不常见且不推荐），那么你需要手动转义这些字符。

一个简单的转义函数：

“`javascript
function escapeHtml(unsafe) {
return unsafe
.replace(/&/g, “&”)
.replace(//g, “>”)
.replace(/”/g, “"”)
.replace(/’/g, “'”);
}

// 示例：
const unsafeCodeString = `

console.log(“Hello & World!”); // 这行代码中的 & 和 ” 会被转义

const codeBlock = document.getElementById(‘jsCodeBlock’);
codeBlock.innerHTML = escapeHtml(unsafeCodeString).trim(); // 使用转义后的字符串
“`

再次强调： 在绝大多数展示代码的场景中，直接使用 textContent 是最安全和推荐的做法，避免了手动转义的复杂性和潜在错误。

2.3 从外部文件加载代码

在实际应用中，代码示例通常存储在单独的文件中（如 .js 文件），而不是硬编码在 HTML 或 JavaScript 字符串中。我们可以使用 Fetch API 来异步加载这些代码文件。

“`html

从文件加载代码

从文件加载的 JavaScript 代码

“`

这种方式使得代码内容与 HTML 结构分离，更易于维护和更新。

局限性： 即使通过 JavaScript 动态插入了代码，它仍然是纯文本，没有语法高亮。为了实现真正的代码格式化（即语法高亮），我们需要引入专业的语法高亮库。

第三章：核心篇——语法高亮库的魔法

语法高亮库是实现专业代码展示的关键。它们通过解析代码字符串，识别不同的语法元素（关键字、变量、字符串、注释等），然后为这些元素包裹上带有特定 CSS 类的 <span> 标签，最终通过 CSS 样式为这些 <span> 赋予不同的颜色。

市面上有许多优秀的语法高亮库，其中最流行的是 Prism.js 和 highlight.js。

3.1 Prism.js：轻量级、可扩展且美观

Prism.js 是一个轻量级、强大且易于使用的代码语法高亮库。它具有丰富的插件生态系统和灵活的自定义能力。

核心特性：
* 轻量级： 核心库非常小。
* 语言支持： 开箱即用支持多种语言，并可通过插件扩展。
* 插件系统： 提供行号、行高亮、代码复制、显示语言等多种实用插件。
* 主题： 提供多种内置主题，也支持自定义。
* HTML 驱动： 主要通过在 <pre><code> 标签上添加 CSS 类来识别语言并高亮。

使用步骤：

引入 CSS 和 JavaScript 文件：
你可以从官方网站下载文件，或使用 CDN。通常需要一个核心 CSS 文件（定义主题颜色）和一个核心 JS 文件。根据需要，你还可以引入特定语言的 JS 文件和插件的 JS/CSS 文件。

“`html

“`
编写 HTML 结构：
在 <pre><code> 标签上添加 class="language-javascript"（或 language-html 等）来告诉 Prism.js 这段代码的语言。如果使用行号插件，还需要在 <pre> 标签上添加 class="line-numbers"。

``html <h1>Prism.js 高亮的 JavaScript 代码</h1> <pre class="line-numbers"><code class="language-javascript"> // 这是一个使用 Prism.js 高亮的 JavaScript 代码块 function greet(name) { const message =Hello, ${name}!`;
console.log(message);
// 这里可以是一个多行注释
/
* 这是一个块级注释
* 可以跨越多行
/
return message;
}
```
const person = "Alice";
greet(person);

class MyClass {
    constructor(value) {
        this.value = value;
    }
    getValue() {
        return this.value;
    }
}
const instance = new MyClass(123);
console.log(instance.getValue());

// 使用 Promise
new Promise((resolve) => {
    setTimeout(() => {
        resolve("Promise resolved!");
    }, 1000);
}).then(data => {
    console.log(data);
});
```
“`
触发高亮（如果代码是动态加载的）：
如果你的代码是静态写在 HTML 中的，Prism.js 会在页面加载完成后自动高亮。如果代码是通过 JavaScript 动态加载并插入的（如上一章的 loadCodeFromFile 例子），你需要在插入代码之后手动调用 Prism.highlightElement(element) 或 Prism.highlightAll()。

``javascript async function loadAndHighlightCode(filePath, elementId, language) { try { const response = await fetch(filePath); if (!response.ok) { throw new Error(HTTP error! status: ${response.status}`);
}
const codeString = await response.text();
const codeElement = document.getElementById(elementId);
```
    // 清除旧的类，确保正确设置语言
    codeElement.className = `language-${language}`;
    codeElement.textContent = codeString.trim();

    // 如果父元素是 pre 并且需要行号，添加相应的类
    if (codeElement.parentElement && codeElement.parentElement.tagName === 'PRE' && language === 'javascript') {
        codeElement.parentElement.classList.add('line-numbers');
    }

    // 触发 Prism.js 高亮
    Prism.highlightElement(codeElement);
    // 如果要高亮所有，用 Prism.highlightAll(); 但效率较低
} catch (error) {
    console.error('Failed to load and highlight code:', error);
    document.getElementById(elementId).textContent = `Error loading code: ${error.message}`;
}
```
}

// 调用示例
// loadAndHighlightCode(‘example.js’, ‘jsCodeBlock’, ‘javascript’);
“`

3.2 highlight.js：自动语言检测的便利性

highlight.js 是另一个非常流行的语法高亮库，它的一个显著特点是能够自动检测代码语言，这对于混合了多种语言（如 HTML 中嵌入 CSS 和 JS）或语言类型不确定的场景非常方便。

核心特性：
* 自动语言检测： 无需明确指定语言，库会尝试自动识别。
* 广泛的语言支持： 支持近 200 种语言。
* 多种主题： 提供数十种预设主题。
* 兼容性： 可以在各种环境中运行。

使用步骤：

引入 CSS 和 JavaScript 文件：
同样可以从官方网站或 CDN 获取。通常需要一个主题 CSS 文件和一个核心 JS 文件。

html  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css">  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>

编写 HTML 结构：
highlight.js 推荐使用 <code> 标签，最好放置在 pre 标签内。你可以添加 class="language-javascript" 来明确指定语言，也可以省略，让 highlight.js 自动检测。

“`html

highlight.js 高亮的 JavaScript 代码


    // 这是一个使用 highlight.js 高亮的 JavaScript 代码块
    function calculateArea(radius) {
        const PI = 3.14159;
        let area = PI * radius * radius;
        return area;
    }
const r = 10;
console.log(`The area is: ${calculateArea(r).toFixed(2)}`);

// 异步操作示例
async function fetchData() {
    try {
        const response = await fetch('https://api.example.com/data');
        const data = await response.json();
        console.log(data);
    } catch (error) {
        console.error('Error fetching data:', error);
    }
}
fetchData();



highlight.js 自动检测语言

    // highlight.js 会尝试自动检测这是 JavaScript
    const autoDetect = true;
    if (autoDetect) {
        console.log("Language detected automatically!");
    }
/* 这是多行注释 */
function greetUser(name) {
    return `Hello, ${name}!`;
}



“`

触发高亮：
在页面加载完成后，调用 hljs.highlightAll() 来高亮所有带有代码标签的元素。如果代码是动态加载的，则在插入代码后调用 hljs.highlightElement(element)。

“`javascript
// 页面加载完成后自动运行
document.addEventListener(‘DOMContentLoaded’, (event) => {
hljs.highlightAll();
});

// 如果是动态加载的代码
async function loadAndHighlightCodeHighlightJS(filePath, elementId) {
try {
const response = await fetch(filePath);
if (!response.ok) {
throw new Error(HTTP error! status: ${response.status});
}
const codeString = await response.text();
const codeElement = document.getElementById(elementId);
codeElement.textContent = codeString.trim();
```
    // 触发 highlight.js 高亮
    hljs.highlightElement(codeElement);
} catch (error) {
    console.error('Failed to load and highlight code:', error);
    document.getElementById(elementId).textContent = `Error loading code: ${error.message}`;
}
```
}

// 调用示例
// loadAndHighlightCodeHighlightJS(‘example.js’, ‘jsCodeBlockHighlightJS’);
“`

3.3 Prism.js 与 highlight.js 的选择

特性/库	Prism.js	highlight.js
核心大小	更轻量，按需加载语言和插件	核心库较大，通常包含所有常用语言
语言检测	需通过 `language-` 类手动指定语言	默认自动检测语言，也可手动指定
插件系统	丰富且模块化，提供行号、复制等高级功能	相对较少，一些功能需手动实现或社区贡献
API 易用性	`Prism.highlightAll()` 或 `Prism.highlightElement(element)`	`hljs.highlightAll()` 或 `hljs.highlightElement(element)`
主题	多种内置主题，易于自定义	更多内置主题，易于自定义
社区活跃度	非常活跃	非常活跃
使用场景	注重性能和精确控制语言，需要多种高级插件的场景	注重便利性，需要自动语言检测，对包体大小不那么敏感

总结：
* 如果你追求极致的性能，需要精细控制加载的语言和插件，并且愿意手动指定代码语言，Prism.js 是一个绝佳选择。
* 如果你更倾向于“设置即用”，希望库能自动识别语言，并且对最终的包大小不是非常敏感，highlight.js 则更加方便。

在大多数现代前端项目中，两者都能提供高质量的语法高亮效果。

第四章：交互篇——更高级的场景与功能

除了基本的语法高亮，我们还可以为代码块添加更多交互功能，提升用户体验。

4.1 代码复制功能

用户经常需要复制代码块中的内容。为代码块添加一个“复制”按钮会非常方便。Prism.js 和 highlight.js 都有插件或社区解决方案。

以原生 JavaScript 实现复制功能（兼容性更好）：

“`html


    function sayHello() {
        console.log("Hello from a copyable code block!");
    }
    sayHello();

`` **注意：** Prism.js 提供了一个copy-to-clipboard` 插件，可以更简洁地实现此功能。只需引入插件的 JS 文件，它会自动在代码块右上角添加复制按钮。

4.2 特定行高亮

在教学或文档中，我们可能需要突出显示代码块中的某一行或某几行，以强调其重要性。

Prism.js 行高亮插件：
Prism.js 有一个 line-highlight 插件，可以通过在 <pre> 标签上添加 data-line 属性来指定高亮的行。

“`html

Prism.js 行高亮


    function exampleFunction(param1, param2) { // Line 1
        // This is a comment about the function logic // Line 2
        console.log("Starting function execution..."); // Line 3 (highlighted)
        if (param1 > 10) { // Line 4
            console.log("Param1 is greater than 10."); // Line 5 (highlighted)
            return param1 * param2; // Line 6 (highlighted)
        } else { // Line 7 (highlighted)
            console.log("Param1 is 10 or less."); // Line 8
            return param1 + param2; // Line 9
        }
    }
    exampleFunction(15, 5); // Line 10

“`

4.3 代码编辑器嵌入（CodeMirror/Monaco Editor）

如果你的场景需要用户不仅能看到代码，还能直接在网页上编辑和运行代码（例如在线 IDE、交互式教程），那么专业的代码编辑器库如 CodeMirror 或 Monaco Editor（VS Code 的核心编辑器）是更好的选择。它们提供了语法高亮、自动完成、代码折叠等高级功能。

CodeMirror 简单示例：

“`html

CodeMirror 编辑器

CodeMirror 交互式代码编辑器

<br /> function helloWorld() {<br /> console.log(“Hello, CodeMirror!”);<br /> }<br /> helloWorld();<br />

“`

这种方案适用于需要高度交互性的场景，但它的资源开销也远大于纯粹的语法高亮库。

4.4 响应式设计

代码块的内容通常较宽，为了在小屏幕设备上也能良好显示，需要确保其具备响应式特性。
在基础 CSS 中我们已经包含了 overflow-x: auto; 和 white-space: pre-wrap; word-break: break-all;，这通常就足够了。

overflow-x: auto;：当内容超出容器宽度时，显示水平滚动条。
max-width: 100%;：确保代码块不会溢出父容器。
white-space: pre-wrap;：在需要时允许长行代码自动换行，同时保留原有格式。
word-break: break-all;：如果一行中的单个“单词”（例如一个很长的变量名或 URL）过长，允许其在任意位置断开以防止溢出。

这些 CSS 规则可以确保代码块在不同屏幕尺寸下都能优雅地展示。

第五章：实践考量与性能优化

在实际项目中集成代码格式化功能时，还需要考虑一些性能和用户体验方面的细节。

5.1 懒加载 (Lazy Loading)

如果你的页面包含大量代码块或你使用了功能强大的编辑器库，一次性加载所有相关资源可能会影响页面初始加载速度 (FCP/LCP)。可以考虑以下懒加载策略：

Intersection Observer API： 监听代码块进入视口时才加载对应的语法高亮库或编辑器。

“`javascript
const codeBlocks = document.querySelectorAll(‘pre code’);
const observer = new IntersectionObserver((entries, observer) => {
entries.forEach(entry => {
if (entry.isIntersecting) {
const codeElement = entry.target;
// 假设这里是加载 Prism.js 或 highlight.js 的逻辑
// 例如：动态创建

滚动至顶部

前端实战：Javascript 格式化后的代码如何直接输出？

引言：为何需要格式化代码输出？

第一章：基础篇——HTML 与 CSS 的基石

1.1 <pre> 和 <code> 标签：语义化与结构

1.2 CSS 基础样式：打造代码块外观

第二章：进阶篇——JavaScript 与动态渲染

2.1 动态插入代码字符串

动态插入的 JavaScript 代码

2.2 处理 HTML 特殊字符：安全与转义

2.3 从外部文件加载代码

从文件加载的 JavaScript 代码

第三章：核心篇——语法高亮库的魔法

3.1 Prism.js：轻量级、可扩展且美观

3.2 highlight.js：自动语言检测的便利性

highlight.js 高亮的 JavaScript 代码

highlight.js 自动检测语言

3.3 Prism.js 与 highlight.js 的选择

第四章：交互篇——更高级的场景与功能

4.1 代码复制功能

4.2 特定行高亮

Prism.js 行高亮

4.3 代码编辑器嵌入（CodeMirror/Monaco Editor）

CodeMirror 交互式代码编辑器

4.4 响应式设计

第五章：实践考量与性能优化

5.1 懒加载 (Lazy Loading)

1.1 `<pre>` 和 `<code>` 标签：语义化与结构