如何在 Dash 中动态导出 Plotly 图形为 HTML 文件

在Dash应用开发场景中，经常需要将用户交互后生成的动态Plotly图形导出为独立的HTML文件，方便用户离线查看或者分享给没有访问应用权限的人员。实现这个功能需要结合Dash的回调机制和Plotly自带的HTML导出能力。

核心实现思路

整体实现分为三个部分，首先是获取当前页面渲染的Plotly图形对象，然后将其转换为HTML格式的字符串，最后通过Dash的下载组件将字符串作为文件返回给用户。整个流程依赖Dash的回调函数响应用户的导出操作，同时需要用到Plotly的to_html方法来完成图形到HTML的转换。

环境准备

首先需要确保已经安装了必要的依赖库，可以通过以下命令安装：

pip install dash plotly pandas

基础实现示例

下面是一个完整的简单示例，包含一个下拉框用于切换图形类型，一个导出按钮，点击按钮后会将当前展示的图形导出为HTML文件：

import dash
from dash import dcc, html, Input, Output, State
import plotly.express as px
import pandas as pd

# 初始化Dash应用
app = dash.Dash(__name__)

# 准备示例数据
df = pd.DataFrame({
    "月份": ["1月", "2月", "3月", "4月", "5月"],
    "销售额": [120, 150, 130, 180, 200],
    "利润": [30, 40, 35, 50, 60]
})

# 定义应用布局
app.layout = html.Div([
    html.H3("Plotly图形动态导出示例"),
    # 图形类型选择下拉框
    dcc.Dropdown(
        id="graph-type",
        options=[
            {"label": "销售额柱状图", "value": "bar"},
            {"label": "利润折线图", "value": "line"}
        ],
        value="bar",
        style={"width": "200px", "marginBottom": "20px"}
    ),
    # 图形展示区域
    dcc.Graph(id="display-graph"),
    # 导出按钮
    html.Button("导出为HTML文件", id="export-btn", n_clicks=0),
    # 下载组件，用于触发文件下载
    dcc.Download(id="download-html")
])

# 回调函数：根据选择的图形类型更新展示的图形
@app.callback(
    Output("display-graph", "figure"),
    Input("graph-type", "value")
)
def update_graph(graph_type):
    if graph_type == "bar":
        fig = px.bar(df, x="月份", y="销售额", title="月度销售额统计")
    else:
        fig = px.line(df, x="月份", y="利润", title="月度利润统计")
    return fig

# 回调函数：处理导出按钮点击，生成HTML文件并触发下载
@app.callback(
    Output("download-html", "data"),
    Input("export-btn", "n_clicks"),
    State("display-graph", "figure"),
    prevent_initial_call=True
)
def export_graph_to_html(n_clicks, current_figure):
    # 将图形对象转换为HTML字符串
    # include_plotlyjs设置为True可以保证离线打开时不需要额外引入Plotly库
    html_str = px.Figure(current_figure).to_html(include_plotlyjs=True, include_mathjax=False)
    # 返回下载数据，指定文件名为dynamic_plot.html
    return dict(content=html_str, filename="dynamic_plot.html")

if __name__ == "__main__":
    app.run_server(debug=True)

关键代码说明

图形对象转换

代码中使用了to_html方法来完成核心转换，这个方法有几个重要的参数需要注意：

• include_plotlyjs：设置为True时，会将Plotly的JS库嵌入到HTML中，这样导出的文件可以完全离线运行，不需要联网加载依赖；如果设置为False，导出的文件体积会更小，但是需要在有网络的环境下打开才能正常渲染图形。
• include_mathjax：如果图形中没有使用数学公式，设置为False可以减少文件体积。
• config：可以传入配置参数，控制导出后图形的交互行为，比如是否显示工具栏、是否允许缩放等。

文件下载配置

Dash的dcc.Download组件是实现文件下载的核心，回调函数中返回的数据需要是一个字典，包含content和filename两个字段，content是文件的内容字符串，filename是用户下载时看到的文件名。

进阶优化方案

自定义导出文件名

如果希望用户导出时可以自定义文件名，可以在页面中添加一个输入框，让用户输入文件名，然后在回调中使用这个输入值作为下载的文件名：

# 布局中添加文件名输入框
html.Div([
    html.Label("导出文件名："),
    dcc.Input(id="file-name-input", value="my_plot", type="text"),
    html.Span(".html")
], style={"marginBottom": "20px"}),

# 回调中修改返回的文件名
def export_graph_to_html(n_clicks, current_figure, file_name):
    html_str = px.Figure(current_figure).to_html(include_plotlyjs=True)
    # 拼接文件名，确保后缀是.html
    final_name = f"{file_name}.html" if not file_name.endswith(".html") else file_name
    return dict(content=html_str, filename=final_name)

# 回调输入添加文件名输入框的状态
@app.callback(
    Output("download-html", "data"),
    Input("export-btn", "n_clicks"),
    State("display-graph", "figure"),
    State("file-name-input", "value"),
    prevent_initial_call=True
)

保留图形交互配置

如果原图形有自定义的交互配置，比如隐藏了某些工具栏按钮，需要在转换时通过config参数传入，确保导出的HTML文件中的图形保持相同的交互设置：

# 定义图形配置，隐藏工具栏
graph_config = {
    "displayModeBar": False
}

# 更新图形时传入配置
def update_graph(graph_type):
    if graph_type == "bar":
        fig = px.bar(df, x="月份", y="销售额", title="月度销售额统计")
    else:
        fig = px.line(df, x="月份", y="利润", title="月度利润统计")
    fig.update_layout(config=graph_config)
    return fig

# 导出时传入相同的配置
def export_graph_to_html(n_clicks, current_figure):
    html_str = px.Figure(current_figure).to_html(include_plotlyjs=True, config=graph_config)
    return dict(content=html_str, filename="dynamic_plot.html")

常见问题解决

• 如果导出的HTML文件打开后图形无法渲染，首先检查include_plotlyjs参数是否设置为True，或者打开文件的设备是否有网络连接。
• 如果导出的文件中文显示乱码，可以在生成HTML字符串后，手动指定编码格式为UTF-8，不过Plotly的to_html方法默认已经使用UTF-8编码，一般很少出现这个问题。
• 如果图形包含自定义的前端交互逻辑，导出时需要确保相关的JS代码也被嵌入到HTML中，避免导出后功能失效。

DashPlotlyHTML_exportdynamic_exportweb_development修改时间：2026-06-29 12:39:43