如何在Sphinx标签页中嵌入Plotly图表并解决切换标签后的交互/显示异常问题

这个问题的核心原因是：非激活标签页的内容在初始渲染时处于隐藏状态（通常是display: none），Plotly无法正确获取容器的真实尺寸和渲染上下文，导致图表初始化异常；而刷新时标签页处于激活状态，容器可见，因此渲染正常。下面提供几种可行的解决方案，按实现复杂度从低到高排序：

方法一：修改标签页隐藏方式（最简单的快速修复） #

Sphinx标签组件默认会把非激活标签的内容设为display: none，这会让Plotly无法计算容器尺寸。我们可以改用其他隐藏方式，让容器保持真实尺寸：

1. 在你的Sphinx项目_static目录下创建custom-tabs.css文件，添加以下CSS：

/* 适配sphinx-design的tab组件 */
.tab-content > .tab-pane:not(.active) {
  display: block;
  position: absolute;
  left: -9999px;
  top: auto;
  height: 0;
  overflow: hidden;
}

/* 适配sphinx-tabs的tab组件 */
.sphinx-tabs-tab-content > .sphinx-tabs-tab-pane:not(.active) {
  display: block;
  position: absolute;
  left: -9999px;
  top: auto;
  height: 0;
  overflow: hidden;
}

2. 在项目根目录的conf.py中引入这个自定义CSS：

html_css_files = [
    'custom-tabs.css',
]

这种方式不需要修改任何JS或Plotly代码，仅通过CSS让非激活标签的容器保持尺寸计算，从根源上避免Plotly初始化异常。

方法二：监听标签切换事件，触发Plotly重渲染 #

如果方法一无效，可以通过JS监听标签切换事件，强制让激活标签内的Plotly图表重新计算布局：

步骤1：在Sphinx模板中添加全局监听脚本 #

在项目_templates目录下创建/修改layout.html，添加自定义JS：

{% extends "!layout.html" %}

{% block extrahead %}
{{ super() }}
<script>
document.addEventListener('DOMContentLoaded', function() {
  // 监听sphinx-design的标签切换事件（基于Bootstrap Tab事件）
  const tabTriggers = document.querySelectorAll('[data-bs-toggle="tab"]');
  tabTriggers.forEach(trigger => {
    trigger.addEventListener('shown.bs.tab', function(e) {
      // 获取当前激活的标签面板
      const activePane = document.getElementById(e.target.getAttribute('aria-controls'));
      // 找到面板内的所有iframe
      const iframes = activePane.querySelectorAll('iframe');
      
      iframes.forEach(iframe => {
        // 向iframe发送消息，通知内部Plotly重绘
        iframe.contentWindow.postMessage({ action: 'relayout' }, '*');
      });
    });
  });
});
</script>
{% endblock %}

步骤2：在Plotly HTML中添加消息监听 #

打开你的Plotly生成的HTML文件，在末尾添加以下JS：

window.addEventListener('message', function(event) {
  if (event.data?.action === 'relayout') {
    // 重绘当前页面所有Plotly图表
    Object.values(Plotly.plots).forEach(plot => {
      Plotly.relayout(plot, { width: '100%', height: '100%' });
      // 也可以尝试调用plot.resize()
    });
  }
});

方法三：延迟加载非初始标签的图表 #

只在标签被首次激活时才加载对应图表，确保图表在容器可见时初始化：

1. 修改你的RST文件，将非初始标签的iframe设为空src：

.. tab-set::
  .. tab-item:: Level SA
    .. raw:: html
      <div style="text-align: center;">
        <iframe src="_static/charts/chart_sa.html" style="border: none; width: 100%; height: 450px"></iframe>
      </div>
  .. tab-item:: MoM SA
    .. raw:: html
      <div style="text-align: center;">
        <iframe id="mom-sa-iframe" src="" style="border: none; width: 100%; height: 450px"></iframe>
      </div>

2. 在layout.html中添加加载触发逻辑：

document.addEventListener('DOMContentLoaded', function() {
  const momTab = document.querySelector('[aria-controls="mom-sa"]');
  momTab.addEventListener('shown.bs.tab', function() {
    const iframe = document.getElementById('mom-sa-iframe');
    if (!iframe.src) {
      iframe.src = '_static/charts/chart_mom.html';
    }
  });
});

额外注意事项 #

1. 尽量使用相对路径作为iframe的src（比如_static/charts/chart.html），避免绝对路径导致的加载问题。
2. 确保你的Plotly是最新版本，旧版本对隐藏容器的渲染兼容性更差。
3. 给iframe设置width: 100%而非固定像素，让图表自适应标签容器尺寸，减少溢出和重叠概率。

内容来源于stack exchange