Plotly 的 write_html() 方法不返回 HTML 字符串，而是直接写入文件并返回 None；正确获取内联 <div> 字符串的方式是使用 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 字符串而非独立文件。但许多开发者会误用 fig.write_html(..., full_html=False)，期望它返回字符串——实际上该方法仅执行 I/O 写入操作，始终返回 None。这是文档表述易引发误解之处（官方 GitHub 已确认为文档错误，见 Issue #3599）。
✅ 正确做法：使用 plotly.io.to_html()（或 fig.to_html()），它是专为生成 HTML 字符串设计的函数：
import plotly.express as px # 示例图表 fig = px.scatter(x=[1, 2, 3], y=[4, 5, 6], title="Sample Scatter") # ✅ 获取仅含 <div> 的 HTML 字符串（不含完整 HTML 结构） div_html = fig.to_html(full_html=False, include_plotlyjs=True) print(len(div_html)) # 约 3.5 MB（含完整 Plotly.js） # ✅ 推荐：排除内联 JS，大幅减小体积（约 8 KB），需确保页面已加载 Plotly.js div_embeddable = fig.to_html(full_html=False, include_plotlyjs=False) print(len(div_embeddable)) # 约 8,000 字符
⚠️ 注意事项：
- include_plotlyjs=False 时，前端页面必须提前引入 Plotly.js（例如通过 <script src="https://cdn.plot.ly/plotly-2.24.1.min.js"></script>），否则图表无法渲染；
- 若需完全自包含（离线可用），可保留 include_plotlyjs=True，但务必评估其对传输性能与缓存的影响；
- to_html() 支持更多定制参数，如 default_height, default_width, post_script（用于注入初始化脚本）等，适用于复杂集成场景。
总结：write_html() 是「写入文件」接口，to_html() 才是「生成字符串」接口。牢记这一分工，即可高效、可靠地将 Plotly 图表导出为可嵌入的 HTML 片段。
立即学习“前端免费学习笔记（深入）”；
