Cloud Convert API转HTML到DOCX时counter-reset失效，UI显示正常

问题背景 #

使用Cloud Convert API将包含CSS计数器（counter-reset/counter-increment）的HTML转换为DOCX时，标题编号（如1. Heading、1.1 Sub-heading）无法正常生成，DOCX文件中缺失这些编号，但浏览器UI显示正常。

相关代码：

body {
  font: smaller sans-serif;
  counter-reset: h1 h2;
}
h1:before {
  content: counter(h1) ". ";
  counter-increment: h1;
}
h1 {
  counter-reset: h2;
}
h2:before {
  content: counter(h1) "." counter(h2) ". ";
  counter-increment: h2;
}

<h1>Heading</h1>
<h2>Sub-heading</h2>
<h2>Sub-heading</h2>
<h1>Heading</h1>
<h2>Sub-heading</h2>
<h2>Sub-heading</h2>

可行解决方案 #

1. 改用DOCX原生标题样式（推荐）

Cloud Convert对DOCX原生样式的支持远优于自定义CSS计数器，直接给HTML标题关联DOCX内置样式，让转换工具自动生成带编号的标题：

h1 {
  mso-style-name: "Heading 1";
  mso-style-id: 1;
  font: bold 16pt sans-serif;
}
h2 {
  mso-style-name: "Heading 2";
  mso-style-id: 2;
  font: bold 14pt sans-serif;
  margin-left: 2em;
}

DOCX的内置标题样式默认带有层级编号，转换后会自动继承这一特性。

2. 预渲染标题编号到HTML内容

如果要保留原有HTML结构，用JavaScript提前将计数器生成的编号直接写入标题文本，避免依赖CSS转换：

<script>
  let h1Count = 1;
  document.querySelectorAll('h1').forEach(h1 => {
    h1.textContent = `${h1Count}. ${h1.textContent}`;
    let h2Count = 1;
    let sibling = h1.nextElementSibling;
    while (sibling?.tagName === 'H2') {
      sibling.textContent = `${h1Count}.${h2Count}. ${sibling.textContent}`;
      h2Count++;
      sibling = sibling.nextElementSibling;
    }
    h1Count++;
  });
</script>

<h1>Heading</h1>
<h2>Sub-heading</h2>
<h2>Sub-heading</h2>
<h1>Heading</h1>
<h2>Sub-heading</h2>
<h2>Sub-heading</h2>

转换前确保JS已执行，编号会直接嵌入标题内容，Cloud Convert会原样写入DOCX。

3. 调整CSS计数器写法适配渲染引擎

部分HTML转DOCX工具对CSS计数器的语法支持有限，拆分计数器声明可能解决问题：

body {
  font: smaller sans-serif;
  counter-reset: h1 0;
}
h1 {
  counter-reset: h2 0;
}
h1:before {
  counter-increment: h1;
  content: counter(h1) ". ";
}
h2:before {
  counter-increment: h2;
  content: counter(h1) "." counter(h2) ". ";
}

这种写法将计数器重置与增量操作分开，更容易被Cloud Convert的渲染引擎识别。

额外提示 #

• 检查Cloud Convert API的转换配置，确保启用了完整CSS解析（部分默认配置会忽略复杂CSS规则）；
• 先通过Cloud Convert网页版测试HTML转换，排除API参数配置问题。

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