Plotly图表添加Jupyter Notebook内部跳转链接失效问题求解

该问题由Plotly的渲染沙箱机制与nbconvert导出的iframe隔离逻辑共同导致：

• Plotly生成的图表默认包裹在独立iframe或SVG命名空间内，annotation中写入的相对锚点链接#Section_1，会被浏览器解析为当前iframe上下文内的锚点，而非整个HTML页面的锚点，导出后找不到对应id自然无法触发跳转
• Jupyter环境内每个Plotly输出都是独立的iframe沙箱，点击相对链接时浏览器会默认在新标签打开当前页地址拼接锚点的路径，就会出现新开标签页加载副本后才跳转的现象
• 外部链接为绝对地址，不受沙箱内相对路径解析规则影响，因此可以正常工作

方案1：修复Plotly注释内的锚点跳转 #

保留原有Plotly按钮的实现逻辑，仅需修改链接属性+增加一行导出时的替换逻辑即可解决问题：

1. 修改Plotly注释中的<a>标签，添加target="_top"属性强制链接在顶层页面打开（跳出iframe沙箱），href中预留文件名占位符：

import plotly.graph_objects as go
import numpy as np

x = np.arange(10)

fig = go.Figure(data=go.Scatter(x=x, y=x**2))
fig.add_annotation(
    x=6, y=10,
    text="<a target='_top' href='./{{PAGE_FILENAME}}#Section_1'>Go to Section 1</a>",
    showarrow=False,
    yshift=10,
    font=dict(size=16) # 可自行调整字号实现大按钮效果
)
fig.show()

2. 调整nbconvert导出代码，在生成HTML内容后将占位符替换为实际导出的文件名，确保链接指向正确的页面锚点：

import plotly.offline as pyo
import plotly.io as pio

pyo.init_notebook_mode(connected=False)
pio.renderers.default = "notebook"

from nbconvert import HTMLExporter
from nbconvert.writers import FilesWriter


nb_name = 'My notebook'

exporter = HTMLExporter(exclude_input=True, exclude_output_prompt=True)
(body, resources) = exporter.from_filename(f'{nb_name}.ipynb')

# 替换占位符为实际HTML文件名，锚点即可正常跳转
body = body.replace("{{PAGE_FILENAME}}", f"{nb_name}.html")

write_file = FilesWriter()
write_file.write(
    output=body,
    resources=resources,
    notebook_name=nb_name
)

修改完成后，Notebook内预览、导出独立HTML两种场景下，点击Plotly内的链接都可以直接在当前页跳转到对应章节，不会出现新开标签、无响应的问题。

方案2：原生HTML导航栏（推荐，灵活度更高） #

如果要实现示意的大尺寸可点击按钮效果，不需要依赖Plotly的文本渲染，直接通过IPython渲染原生HTML导航即可，样式可完全自定义，不存在沙箱兼容问题，和原有锚点逻辑100%兼容：

from IPython.display import HTML

# 可自行修改样式参数调整按钮外观、增减导航项
nav_html = """
<style>
.nav-btn {
    display: inline-block;
    padding: 18px 32px;
    margin: 0 12px;
    background: #2563eb;
    color: white !important;
    text-decoration: none;
    border-radius: 8px;
    font-size: 18px;
    font-weight: 500;
    transition: background 0.2s;
}
.nav-btn:hover {
    background: #1d4ed8;
}
.nav-container {
    text-align: center;
    padding: 20px 0;
}
</style>
<div class="nav-container">
    <a href="#Section_1" class="nav-btn">Section 1</a>
    <a href="#Section_2" class="nav-btn">Section 2</a>
    <a href="#Section_3" class="nav-btn">Section 3</a>
</div>
"""

# 在Notebook中直接渲染导航栏
HTML(nav_html)

该方案的优势：

• 无需修改导出逻辑，原生HTML链接直接在当前页跳转，无沙箱隔离问题
• 可自由调整按钮大小、颜色、圆角、悬停动效，视觉效果远好于Plotly内的纯文本链接
• 天然支持响应式，不同屏幕尺寸下显示效果稳定
• 原有锚点定义代码完全不需要改动，直接复用即可

• 锚点id不要包含特殊字符、空格，使用下划线、字母、数字的组合即可避免解析异常
• 如需实现返回顶部按钮，直接将href设为#top即可，无需额外定义锚点，浏览器原生支持该跳转
• 不要将跳转链接放在Plotly的hover提示文本中，该区域的链接会被Plotly强制加上安全限制属性，无法正常触发跳转

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