jsdom JavaScript DOM实现的入门教程

2501_93502106

1018人浏览 · 2025-09-25 12:23:25

2501_93502106 · 2025-09-25 12:23:25 发布

文章目录

什么是jsdom？为什么要了解它？

jsdom是一个令人惊叹的JavaScript库，它在Node.js环境中实现了Web标准的很大一部分 - 特别是WHATWG DOM和HTML标准！！！这意味着什么？简单来说，jsdom让你可以在服务器端或任何Node.js环境中使用DOM API，就像在浏览器中一样。这个功能太强大了（尤其是做测试的时候）。

很多开发者可能会想："我为什么需要在Node.js中使用DOM？"嗯，想象一下，如果你需要：

为前端应用编写单元测试，但不想启动真正的浏览器
抓取网页并分析其内容
在服务器端渲染HTML
在没有浏览器的环境中操作HTML和XML文档

jsdom正是为解决这些场景而生的！它提供了一个虚拟DOM环境，你可以在其中加载HTML、运行JavaScript，以及与DOM元素交互——所有这些都在Node.js中进行。

安装jsdom

开始使用jsdom非常简单。首先，我们需要通过npm安装它：

npm install jsdom

就这么简单！现在让我们开始探索jsdom的基本用法。

jsdom基础使用

创建一个基本的DOM

让我们从最简单的例子开始——创建一个基本的DOM：

const { JSDOM } = require("jsdom");

// 创建一个包含简单HTML的DOM
const dom = new JSDOM(`<!DOCTYPE html><p>Hello world</p>`);

// 访问DOM元素
console.log(dom.window.document.querySelector("p").textContent);
// 输出: Hello world

这段代码做了什么？我们从jsdom包中导入了JSDOM构造函数，然后用一个HTML字符串创建了一个新的DOM实例。创建后，我们可以通过dom.window.document访问document对象，就像在浏览器中一样！

使用window对象

jsdom提供了一个完整的window对象，它包含了许多在浏览器中可用的API：

const { JSDOM } = require("jsdom");
const dom = new JSDOM(`<!DOCTYPE html><body><div id="container"></div></body>`);

const { window } = dom;
const { document } = window;

// 使用DOM API创建新元素
const h1 = document.createElement("h1");
h1.textContent = "jsdom很棒！";
document.getElementById("container").appendChild(h1);

console.log(document.body.innerHTML);
// 输出: <div id="container"><h1>jsdom很棒！</h1></div>

看到了吗？我们可以使用所有熟悉的DOM方法，就像在浏览器中一样！！！

高级功能

运行脚本

默认情况下，jsdom是不执行JavaScript的。但我们可以通过配置来启用脚本执行：

const { JSDOM } = require("jsdom");

const dom = new JSDOM(`
  <!DOCTYPE html>
  <body>
    <script>
      document.body.appendChild(document.createElement("p")).textContent = "这是由脚本创建的!";
    </script>
  </body>
`, { runScripts: "dangerously" });

// 等待脚本执行
setTimeout(() => {
  console.log(dom.window.document.body.innerHTML);
  // 包含脚本创建的段落
}, 10);

注意那个runScripts: "dangerously"参数——这不是随便命名的！允许执行任意脚本确实存在安全风险，尤其是处理不可信的内容时。所以请谨慎使用这个功能。

模拟浏览器行为

jsdom还可以模拟各种浏览器行为，比如导航和点击事件：

const { JSDOM } = require("jsdom");

const dom = new JSDOM(`
  <!DOCTYPE html>
  <body>
    <button id="myButton">点击我</button>
    <script>
      document.getElementById("myButton").addEventListener("click", () => {
        document.body.appendChild(document.createElement("p")).textContent = "按钮被点击了！";
      });
    </script>
  </body>
`, { runScripts: "dangerously" });

// 模拟点击事件
const button = dom.window.document.getElementById("myButton");
button.click();

console.log(dom.window.document.body.innerHTML);
// 输出应该包含"按钮被点击了！"

这种功能在测试前端代码时特别有用。你可以模拟用户交互，而不需要真正的浏览器！

实际应用案例

用jsdom进行网页抓取

一个jsdom常见的用途是网页抓取。以下是如何使用jsdom和Node.js的fetch API来获取网页内容并解析它：

const { JSDOM } = require("jsdom");
const fetch = require("node-fetch");

async function scrapeWebsite(url) {
  try {
    const response = await fetch(url);
    const html = await response.text();
    const dom = new JSDOM(html);
    const { document } = dom.window;
    
    // 例如，获取所有标题
    const headings = Array.from(document.querySelectorAll("h1, h2, h3"));
    return headings.map(heading => ({
      level: heading.tagName,
      text: heading.textContent.trim()
    }));
  } catch (error) {
    console.error("抓取过程中出错:", error);
    return [];
  }
}

// 使用示例
scrapeWebsite("https://example.com").then(headings => {
  console.log("找到的标题:", headings);
});

这个例子展示了如何获取页面上的所有标题元素。当然，你可以根据需要修改选择器来提取任何你感兴趣的内容。

使用jsdom进行单元测试

jsdom最强大的应用之一是在前端代码的单元测试中。许多测试框架（如Jest）已经内置了jsdom支持，但你也可以手动设置：

const { JSDOM } = require("jsdom");
const fs = require("fs");
const path = require("path");

// 假设我们有一个简单的HTML文件和一个JavaScript文件要测试
const html = fs.readFileSync(path.resolve(__dirname, "./index.html"), "utf8");
const dom = new JSDOM(html, { runScripts: "dangerously" });

// 将DOM注入到全局作用域，这样测试框架可以使用它
global.window = dom.window;
global.document = dom.window.document;
global.navigator = dom.window.navigator;

// 现在你可以加载你的JavaScript代码并进行测试
// 例如，如果你有一个toggle-button.js文件：
require("./toggle-button.js");

// 然后你可以测试它
function testToggleButton() {
  const button = document.getElementById("toggle");
  const element = document.getElementById("target");
  
  // 初始状态
  console.assert(element.style.display === "none", "元素应该初始隐藏");
  
  // 点击按钮
  button.click();
  console.assert(element.style.display === "block", "点击后元素应该显示");
  
  // 再次点击
  button.click();
  console.assert(element.style.display === "none", "再次点击后元素应该隐藏");
  
  console.log("测试通过！");
}

testToggleButton();

这个简单的测试框架展示了如何使用jsdom来测试DOM交互。当然，在实际项目中，你可能会使用Jest、Mocha或其他测试框架，它们通常提供更完整的测试环境。

jsdom的局限性

虽然jsdom很强大，但它并不是浏览器的完整替代品。有一些限制需要注意：

不完整的API实现 - jsdom实现了很多Web API，但不是全部。比如，Canvas、WebGL和一些更高级的API支持有限或不支持。
性能 - 处理大型或复杂的DOM结构时，jsdom可能比真正的浏览器慢。
CSS限制 - 虽然jsdom可以解析CSS，但它不会渲染页面，所以基于视觉的测试（如元素是否可见）可能不准确。
布局和计算样式 - jsdom不执行布局计算，所以getComputedStyle()和getBoundingClientRect()等方法可能返回不准确的结果。

了解这些限制很重要，这样你就能知道何时使用jsdom，何时需要一个真正的浏览器测试环境（如Puppeteer或Selenium）。

使用技巧

记得清理资源 - 当你使用完jsdom实例后，最好调用window.close()来释放资源，特别是在长时间运行的程序中：

const { JSDOM } = require("jsdom");
const dom = new JSDOM(`<!DOCTYPE html><p>Hello</p>`);

// 使用DOM...

// 完成后清理
dom.window.close();

处理异步脚本 - 如果你的HTML包含异步加载的脚本，可能需要等待它们完成：

const { JSDOM } = require("jsdom");

// 创建一个Promise，在所有资源加载完成后解析
function createDOM(html) {
  return new Promise((resolve) => {
    const dom = new JSDOM(html, {
      runScripts: "dangerously",
      resources: "usable"
    });
    
    dom.window.addEventListener("load", () => {
      resolve(dom);
    });
  });
}

// 使用
createDOM(`<!DOCTYPE html><script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>`)
  .then(dom => {
    // 现在jQuery已加载，可以使用它
    console.log(typeof dom.window.$); // 应该输出 "function"
    dom.window.close();
  });

结合Fetch API - 结合Node的fetch能力可以创建强大的网页处理工具：

const { JSDOM } = require("jsdom");
const fetch = require("node-fetch");

async function getLinksFromPage(url) {
  const response = await fetch(url);
  const html = await response.text();
  const dom = new JSDOM(html);
  
  const links = Array.from(dom.window.document.querySelectorAll("a"))
    .map(a => a.href);
  
  dom.window.close();
  return links;
}