x-ray 本身不支持直接抓取兄弟节点构成的逻辑区块，但可通过 jsdom 预处理 html，将散列的 `

` 及其后续同级内容动态包裹为独立容器，再用 x-ray 按标准父子结构解析，最终得到符合预期的 sections 数组。

在实际网页爬虫场景中，常遇到类似文档式 HTML：多个

标题平级排列，各自后跟可选的

副标题和

列表，但无统一父容器分隔各节。这种“非嵌套、靠顺序语义组织”的结构，与 X-ray 基于 CSS 选择器树形遍历的设计范式天然冲突——它无法原生表达“以某个元素为起点，收集其后所有同级兄弟直到下一个同类元素”这样的逻辑。

直接尝试 xray("h2", [...]) 会失败，因为 X-ray 会将每个

作为独立上下文，而

和

并不在其子树内；而 xray("article", [...]) 加数组语法，则只会执行一次迭代（因全文仅一个
），无法生成多节结果。

✅ 核心思路：DOM 预处理 + X-ray 后解析
借助 jsdom 构建内存 DOM，遍历所有

，将其及后续连续非-

兄弟节点（如

、

）动态包裹进新
中。这样就把线性结构转化为多个具备明确父子关系的块级容器，X-ray 即可自然地对每个

执行对象映射。

以下是完整、健壮的实现方案（含错误处理与空值兼容）：



Expanso yaml-to-json

使用 Expanso Edge 管道将 YAML 输入转换为 JSON 格式。

下载

const { JSDOM } = require('jsdom');
const xray = require('x-ray')();

// 自定义 trim 过滤器（X-ray 默认不内置）
xray.filters({
  trim: (value) => typeof value === 'string' ? value.trim() : value
});

async function parseNonNestedSections(html, url = '') {
  const dom = new JSDOM(html);
  const doc = dom.window.document;

  // 步骤1：定位所有 h2，并按逻辑分组包裹
  const h2s = doc.querySelectorAll('article h2'); // 限定在 article 内更安全
  if (h2s.length === 0) return { pageTitle: '', sections: [] };

  // 创建临时根容器，避免污染 body
  const wrapper = doc.createElement('div');
  wrapper.innerHTML = doc.querySelector('article').innerHTML;

  // 重置 wrapper 内部引用
  const h2List = wrapper.querySelectorAll('h2');

  for (let i = 0; i < h2List.length; i++) {
    const h2 = h2List[i];
    const sectionDiv = doc.createElement('section'); // 语义化标签更佳

    // 移动 h2 到新 section
    sectionDiv.appendChild(h2);

    // 收集后续同级节点，直到下一个 h2 或 null
    let next = h2.nextElementSibling;
    while (next && next.tagName !== 'H2') {
      const toMove = next;
      next = next.nextElementSibling;
      sectionDiv.appendChild(toMove);
    }

    // 插入到 wrapper 中原位置（保持顺序）
    h2.parentNode.insertBefore(sectionDiv, h2);
    h2.remove(); // 清理已移动的 h2
  }

  // 步骤2：用 X-ray 解析预处理后的 HTML
  const processedHtml = wrapper.innerHTML;

  return new Promise((resolve, reject) => {
    xray(processedHtml, {
      pageTitle: 'h1 | trim',
      sections: xray('section', [{
        subtitle: 'h3 | trim',
        elements: xray('ul li', ['| trim']) // 返回字符串数组，自动过滤空值
      }])
    })((err, result) => {
      if (err) return reject(err);
      // 确保 elements 始终为数组（即使 ul 不存在）
      result.sections = result.sections.map(sec => ({
        subtitle: sec.subtitle || undefined,
        elements: Array.isArray(sec.elements) ? sec.elements : []
      }));
      resolve(result);
    });
  });
}

// 使用示例
const sampleHtml = `
  <h1>Page title</h1>
  <article>
    <h2 id="first">Title 1</h2>
    <h3>Subtitle 1</h3>
    <ul><li>Element 1</li><li>Element 2</li><li>Element 3</li></ul>
    <h2 id="second">Title 2</h2>
    <h3>Subtitle 2</h3>
    <h2 id="third">Title 3</h2>
    <h3>Subtitle 3</h3>
    <ul><li>Element 1</li><li>Element 2</li><li>Element 3</li></ul>
  </article>
`;

parseNonNestedSections(sampleHtml)
  .then(console.log)
  .catch(console.error);

? 关键注意事项：

立即学习“前端免费学习笔记（深入）”；

• ✅ 务必限定作用域：querySelectorAll('article h2') 而非全页 h2，避免误包其他区域标题；
• ✅ 使用 section 替代 div：提升语义清晰度，且不影响 X-ray 解析；
• ✅ 显式处理空值：subtitle 可能为 undefined（当某节无

  ），elements 统一归一化为 []；

• ⚠️ 性能提示：对超大页面，频繁 DOM 操作可能有开销；若需高吞吐，建议切换至 Puppeteer 或 Cheerio + 手动遍历；
• ? 扩展性友好：该模式可轻松适配

  +

  +

  等混合结构，只需调整 sectionDiv.appendChild(...) 的条件逻辑。

  此方案在保留 X-ray 声明式优势的同时，以最小侵入性补足了其对线性语义结构的解析短板，是生产环境中兼顾可读性、可维护性与可靠性的推荐实践。