MathJax 3.2.1如何配置实现初始加载时排除指定容器的公式渲染

问题根因 #

原生lazyAlwaysTypeset配置仅支持白名单逻辑，即只能指定「必须在初始加载时完成渲染」的容器，原生不支持黑名单排除规则。直接为该配置传入带:not修饰符的CSS选择器会失效，核心原因是MathJax的渲染遍历逻辑是命中祖先节点就会向下遍历所有子节点：只要排除容器的外层父元素命中了选择器，MathJax就会递归遍历父元素下所有节点，哪怕子节点属于排除范围，也会被强制触发初始渲染。

可行实现方案 #

采用「初始渲染范围拦截+交互触发补渲染」的组合逻辑，绕开父节点穿透问题，具体实现步骤如下：

• 配置MathJax启动参数，关闭默认全页面初始渲染逻辑

  window.MathJax = {
    loader: { load: ['ui/lazy'] },
    lazy: {
      lazyAlwaysTypeset: null, // 清空默认强制渲染列表
    },
    startup: {
      elements: null, // 禁用默认启动时全页面元素匹配
      typeset: false // 关闭启动后自动渲染，改为手动控制渲染范围
    }
  };
  

• 在MathJax加载完成的回调中，手动触发非排除区域的初始渲染
  针对存在大量未展开<details>元素的场景，初始渲染时直接跳过所有未展开折叠块内部的公式：

  window.MathJax.startup.promise.then(() => {
    // 选中所有不在未展开details内的公式节点做初始渲染
    const initialRenderNodes = document.querySelectorAll(
      'body *:not(details:not([open]) *) script[type^="math/tex"], body *:not(details:not([open]) *) .MathJax_Process'
    );
    window.MathJax.typeset(initialRenderNodes);
  });
  

• 绑定折叠块展开事件，触发对应区域的延迟渲染
  通过事件委托监听所有<details>元素的切换动作，仅当元素展开时才渲染内部公式，渲染完成后打标记避免重复执行：

  document.addEventListener('toggle', (e) => {
    const el = e.target;
    if (el.tagName !== 'DETAILS' || !el.open || el.dataset.mathRendered) return;
    window.MathJax.typeset([el]).then(() => {
      el.dataset.mathRendered = 'true';
    });
  }, true);
  

适配说明 #

如果需要排除的容器不是未展开的<details>元素，只需要将代码中details:not([open])对应的CSS选择器替换为目标排除容器的选择器即可。该方案不会破坏MathJax原生的懒加载逻辑，初始渲染完成后，滚动到视口范围内的未渲染公式会按原有懒加载规则正常解析渲染。

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