基于h2/h3的层级编号目录计数器异常问题排查

常见问题根源与修正方案 #

1. 计数器重置逻辑缺失 #

这是最常见的问题：H2未重置H3计数器，导致H3编号跨H2连续递增，或者JS遍历H2时未同步重置H3计数变量。

CSS计数器修正（推荐用于正文编号）

/* 初始化H2计数器 */
.content-container {
  counter-reset: h2;
}

h2 {
  counter-increment: h2;
  counter-reset: h3; /* 关键：每个H2开头重置H3计数器 */
}

/* 生成H2编号 */
h2::before {
  content: counter(h2) ". ";
  font-weight: inherit;
}

h3 {
  counter-increment: h3;
}

/* 生成H3层级编号 */
h3::before {
  content: counter(h2) "." counter(h3) ". ";
  font-weight: inherit;
}

JS目录生成同步修正

如果用JS生成目录，必须在遍历到H2时重置H3计数：

let h2Count = 0;
let h3Count = 0;
const tocList = document.getElementById('toc');

// 按DOM顺序遍历所有H2、H3
document.querySelectorAll('h2, h3').forEach(heading => {
  if (heading.tagName === 'H2') {
    h2Count++;
    h3Count = 0; // 重置H3计数
    // 创建目录项
    const tocItem = document.createElement('li');
    tocItem.textContent = `${h2Count}. ${heading.textContent}`;
    tocList.appendChild(tocItem);
  } else if (heading.tagName === 'H3') {
    h3Count++;
    const tocItem = document.createElement('li');
    tocItem.textContent = `${h2Count}.${h3Count}. ${heading.textContent}`;
    tocItem.style.paddingLeft = '2em'; // 目录层级缩进
    tocList.appendChild(tocItem);
  }
});

2. Paged.js分页导致计数器失效 #

Paged.js会将内容拆分到多个页面容器中，全局计数器可能跨页异常，需要将计数器绑定到内容容器而非全局：

/* 确保计数器作用域在内容容器内，不受分页影响 */
.content-container {
  counter-reset: h2;
  counter-increment: none;
}

@page {
  size: A4;
  /* 可选：在页脚显示当前页码，不影响标题计数器 */
  @bottom-right {
    content: counter(page);
  }
}

3. 正文与目录编号不同步 #

避免正文用CSS计数器、目录用JS单独计数的混合方案，推荐两种统一方式：

• 方式一：从正文CSS编号提取生成目录

  const tocList = document.getElementById('toc');
  document.querySelectorAll('h2, h3').forEach(heading => {
    const tocItem = document.createElement('li');
    // 获取CSS生成的编号（需确保::before内容可访问）
    const number = window.getComputedStyle(heading, '::before').content.replace(/"/g, '');
    tocItem.textContent = `${number} ${heading.textContent}`;
    if (heading.tagName === 'H3') tocItem.style.paddingLeft = '2em';
    tocList.appendChild(tocItem);
  });
  

• 方式二：JS统一生成正文与目录编号
  见前文的JS代码示例，同时给正文标题添加编号并生成目录，确保两边完全同步。

4. DOM结构异常 #

如果H3不是紧跟对应H2的同级/子元素（比如H3出现在下一个H2之后），会导致编号逻辑混乱，需先修正文档结构，保证H3始终属于最近的H2层级。

内容的提问来源于stack exchange，提问作者EllBrandon