Plotly 的 write_html() 方法不返回 HTML 字符串，而是直接写入文件并返回 None；正确获取内联 字符串的方式是使用 to_html(full_html=False)，配合 include_plotlyjs=False 可显著减小输出体积。
plotly 的 `write_html()` 方法不返回 html 字符串，而是直接写入文件并返回 `none`；正确获取内联 `
` 字符串的方式是使用 `to_html(full_html=false)`，配合 `include_plotlyjs=false` 可显著减小输出体积。
在 Web 集成或模板渲染场景中（如 Flask、Dash、Jinja2 或静态站点生成器），常需将 Plotly 图形以纯 HTML 字符串形式嵌入页面，而非生成独立 HTML 文件。此时关键在于区分两个易混淆的 API：
- ✅ fig.to_html(...)：返回字符串，支持 full_html=False 生成仅含 的轻量级 HTML 片段，适合内嵌；
- ❌ fig.write_html(...)：写入文件并返回 None，无论是否设置 full_html=False，均不返回内容——这是官方文档长期存在的表述歧义（见 Issue #3599）。
正确用法示例
import plotly.express as px # 创建示例图表 fig = px.scatter(px.data.iris(), x="sepal_width", y="sepal_length", color="species") # ✅ 获取仅含 <div> 的 HTML 字符串（默认包含完整 Plotly.js，约 3.5MB） div_string = fig.to_html(full_html=False) # ✅ 推荐：排除内联 Plotly.js，仅保留序列化数据（约 8KB） div_string_minimal = fig.to_html(full_html=False, include_plotlyjs=False) print(len(div_string_minimal)) # 输出类似：7942<h3>注意事项与最佳实践</h3> <ul> <li> <strong>include_plotlyjs=False 是必需优化项</strong>：默认情况下 to_html() 会将整个 Plotly.js 库（约 3.5 MB）打包进字符串，极大增加传输开销。务必显式设为 False，并在页面 中单独引入 CDN 脚本：<pre class="brush:php;toolbar:false;"><script src="https://cdn.plot.ly/plotly-2.24.1.min.js"></script>
- 确保前端环境已加载 Plotly.js：当 include_plotlyjs=False 时，HTML 字符串仅含 data-* 属性和初始化脚本，依赖全局 Plotly 对象。
- 避免误用 write_html：该方法设计用于持久化存储，其返回值恒为 None，不可用于字符串捕获。
通过 to_html(full_html=False, include_plotlyjs=False)，你可获得标准、可复用的 HTML
字符串，无缝集成至任意 Python Web 框架或静态内容系统。
