尧图网站开发 
plotly.py 的 graph_objects 低层接口完全指南Figure、Trace 与 Layout 的构建体系【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.pyplotly.graph_objects是 plotly.py 中面向 Figure 的底层编程接口它提供了构成图形对象的全部积木各类 trace如Scatter、Bar与Layout。本文将基于仓库 doc/apidoc/plotly.graph_objects.rst 的 API 参考骨架结合 plotly/graph_objs 的源码实现系统讲解 graph_objects 的类层次、六大 trace 分类体系、Figure 的构建方式与底层机制帮助你掌握以go.Figure为核心的声明式绘图范式。一、graph_objects 是什么Figure 的构建积木plotly.graph_objects通常以别名go导入是 plotly.py 中构造Figure的低层接口。文档开篇即给出其定位plotly.graph_objectscontains the building blocks of plotlyFigure: traces (Scatter,Bar, ...) andLayout也就是说一个完整的 Figure 由两类对象拼装而成trace轨迹具体的数据系列如散点Scatter、柱状Bar、热力图Heatmap每个 trace 描述一组数据如何被绘制Layout布局整张图的全局配置包括坐标轴、标题、图例、模板、页边距等。标准导入方式与原文档保持一致 import plotly.graph_objects as go导入后即可用go.Figure(...)创建图形并组合各类 trace 与 Layout 完成定制。如果你用过plotly.expresspx的高层接口可以把它理解为px负责把 DataFrame 快速翻译成 Figure而go则让你直接、精确地操控 Figure 的每一个属性。二、Figuregraph_objects 的核心类2.1 类的真实定义Figure类定义在仓库 plotly/graph_objs/_figure.py 中注意文件头部标注了--- THIS FILE IS AUTO-GENERATED ---——这是由 codegen 工具自动生成的手改会在下次代码生成时被覆盖from plotly.basedatatypes import BaseFigure class Figure(BaseFigure): def __init__( self, dataNone, layoutNone, framesNone, skip_invalidFalse, **kwargs ):从构造函数签名plotly/graph_objs/_figure.py可以看到 Figure 的四个核心入参参数类型说明datatrace 实例或 dict 列表可传[Scatter(...), Bar(...)]这类 trace 实例列表也可传{type: scatter, ...}形式的 dict——此时type键指定 trace 类型其余键传给对应 trace 构造函数layoutLayout实例或 dict图的全局布局dict 会交给Layout构造函数解析framesFrame实例或 dict 列表动画帧用于go.Frame构建动画skip_invalidbool是否跳过无效属性校验默认为 False遇到未知属性会抛错其中data中可用的 trace 类型全集也写在构造函数 docstring 中包括bar、box、candlestick、choropleth、contour、heatmap、histogram、indicator、mesh3d、ohlc、pie、sankey、scatter、scatter3d、scattergeo、scattermap、scatterpolar、splom、sunburst、surface、table、treemap、violin、volume、waterfall等四十余种。2.2 Figure 的常用方法API 文档模板 doc/apidoc/_templates/class_figure.rst 特别为Figure类单独列出了四个高频方法Figure.show()渲染并展示图形Figure.add_traces()向已有 Figure 追加 traceFigure.update_traces()批量更新 trace 属性Figure.update_layout()批量更新布局属性。这也构成了 graph_objects 编程的核心工作流创建 Figure → add_traces 添加数据 → update_layout 定制外观 → show 展示。2.3 最小可运行示例import plotly.graph_objects as go fig go.Figure( data[go.Scatter(x[1, 2, 3], y[4, 5, 6], modelinesmarkers)], layoutgo.Layout(titleA minimal graph_objects figure), ) fig.show()也可以先创建空 Figure再逐步添加fig go.Figure() fig.add_traces(go.Scatter(x[1, 2, 3], y[4, 5, 6], nameseries A)) fig.update_layout(titleUpdated title) fig.show()三、Layout全局布局与子图坐标系Layout类定义于 plotly/graph_objs/_layout.py。它有两个值得注意的源码细节1. 子图坐标系统一注册。Layout通过_subplotid_prop_names声明了一组可带数字编号的子图属性_subplotid_prop_names [ coloraxis, geo, legend, map, polar, scene, smith, ternary, xaxis, yaxis, ]并用正则^(\w)(\d)$匹配形如xaxis2、yaxis3、scene1这样的属性名见 plotly/graph_objs/_layout.py。这意味着你不需要专门注册子图只要给坐标轴/场景属性加上数字后缀Layout就能自动识别多坐标系例如双 y 轴场景中同时设置yaxis与yaxis2。2. 全部布局属性集中在_valid_props。从activeselection、annotations、autosize开始Layout拥有数百个可配置属性标题title、图例legend、模板template、页边距margin、配色轴coloraxis等且所有属性都经过 validator 校验非法赋值会得到明确的错误提示。import plotly.graph_objects as go fig go.Figure(go.Bar(x[A, B, C], y[1, 3, 2])) fig.update_layout( titledict(textBar chart, fontdict(size18)), xaxisdict(titleCategory), yaxisdict(titleValue), legenddict(orientationh, yanchorbottom, y1.02), templateplotly_white, ) fig.show()四、Trace 六大分类体系原文档核心骨架原文档 doc/apidoc/plotly.graph_objects.rst 将全部 trace 划分为六大类这是了解 graph_objects 能力地图的最佳索引。下面逐一展开并补充每个 trace 的典型用途与仓库中的对应源码文件全部位于 plotly/graph_objs 目录文件名以_开头的小写类名如_scatter.py。4.1 Simple Traces基础轨迹Trace源码文件典型用途Scatter_scatter.py散点 / 折线图最通用的 trace支持modelines/markers/text、fill、stackgroup等Scattergl_scattergl.py基于 WebGL 的高性能散点适合十万级以上的大数据点Bar_bar.py柱状图支持水平/垂直、堆叠Pie_pie.py饼图 / 环形图Heatmap_heatmap.py二维热力图Image_image.py在图中显示图像如卫星影像Contour_contour.py等高线图Table_table.py表格以最常用的Scatter为例其属性集合定义在 plotly/graph_objs/_scatter.py 的_valid_props中包括x/y、mode、line、marker、text、hovertext、hovertemplate、fill、opacity、visible、xaxis/yaxis指定挂在哪个坐标轴上等六十多个属性且每个属性都经过 plotly/validators/_validators.json 中注册的 validator 校验。import plotly.graph_objects as go fig go.Figure(go.Scatter( x[1, 2, 3, 4], y[10, 11, 12, 13], modelinesmarkerstext, text[a, b, c, d], linedict(colorfirebrick, width2), markerdict(size10, symbolcircle), )) fig.show()4.2 Distribution Traces分布轨迹Trace源码文件典型用途Box_box.py箱线图展示数据分布的四分位与离群点Violin_violin.py小提琴图箱线图 核密度估计Histogram_histogram.py一维直方图支持nbinsx与累积模式Histogram2d_histogram2d.py二维直方图矩形分箱Histogram2dContour_histogram2dcontour.py二维直方图的等高线版本import plotly.graph_objects as go fig go.Figure(go.Box( y[1, 2, 3, 4, 5, 8, 9, 10], boxmeanTrue, notchedFalse, )) fig.show()4.3 Finance Traces金融轨迹Trace源码文件典型用途Ohlc_ohlc.pyOHLC开高低收K 线Candlestick_candlestick.py蜡烛图金融行情标配Waterfall_waterfall.py瀑布图展示增量贡献与累计Funnel_funnel.py漏斗图常用于转化率分析Funnelarea_funnelarea.py漏斗面积图Indicator_indicator.py仪表盘 / 数值指示器import plotly.graph_objects as go fig go.Figure(go.Candlestick( x[2024-01-01, 2024-01-02, 2024-01-03, 2024-01-04], open[100, 102, 101, 105], high[104, 106, 105, 108], low[99, 101, 100, 104], close[102, 101, 105, 107], )) fig.show()4.4 3D Traces三维轨迹Trace源码文件典型用途Scatter3d_scatter3d.py三维散点 / 折线Surface_surface.py三维曲面图Mesh3d_mesh3d.py三维网格 / 三角剖分曲面Cone_cone.py锥体图常用于向量场可视化Streamtube_streamtube.py流管图可视化流体场Volume_volume.py三维体绘制Isosurface_isosurface.py等值面提取3D trace 通常配合Layout中的scene三维场景属性使用场景含xaxis/yaxis/zaxis、相机camera、灯光lighting等子配置import plotly.graph_objects as go import numpy as np x np.linspace(-5, 5, 50) y np.linspace(-5, 5, 50) X, Y np.meshgrid(x, y) Z np.sin(np.sqrt(X**2 Y**2)) fig go.Figure(go.Surface(xX, yY, zZ, colorscaleViridis)) fig.update_layout( scenedict( xaxisdict(titleX), yaxisdict(titleY), zaxisdict(titleZ), cameradict(eyedict(x1.5, y1.5, z1.5)), ) ) fig.show()4.5 Map Traces地图轨迹Trace源码文件典型用途Scattergeo_scattergeo.py地理坐标系geo上的散点 / 连线Choropleth_choropleth.py按地理区域着色的分级统计图Scattermap_scattermap.py基于 MapLibre 底图的散点Choroplethmap_choroplethmap.py基于 MapLibre 底图的分级着色Densitymap_densitymap.py基于 MapLibre 底图的密度热力地图类 trace 依赖Layout中的geo或map子配置来指定投影、中心点、缩放级别与底图样式对应 plotly/graph_objs/layout 目录下的geo、map模块。4.6 Specialized Traces专用轨迹Trace源码文件典型用途Scatterpolar_scatterpolar.py极坐标散点 / 折线Scatterpolargl_scatterpolargl.py极坐标 WebGL 高性能版本Barpolar_barpolar.py极坐标柱状玫瑰图Scatterternary_scatterternary.py三元相图散点Sunburst_sunburst.py旭日图径向层次树Treemap_treemap.py矩形树图Icicle_icicle.py冰柱图矩形层次树Sankey_sankey.py桑基图节点-流量图Parcats_parcats.py平行类别图Parcoords_parcoords.py平行坐标图Carpet_carpet.py地毯图自定义网格坐标系Scattercarpet_scattercarpet.py地毯坐标系上的散点Contourcarpet_contourcarpet.py地毯坐标系上的等高线import plotly.graph_objects as go fig go.Figure(go.Sankey( nodedict( label[Source A, Source B, Middle, Sink], color[blue, blue, orange, orange], ), linkdict( source[0, 1, 0, 2], target[2, 2, 3, 3], value[8, 3, 4, 7], ), )) fig.update_layout(title_textSankey example) fig.show()五、源码级机制graph_objects 是如何组织起来的5.1 自动生成的文件体系plotly/graph_objs下的所有 trace 类文件_scatter.py、_bar.py、_layout.py……与plotly/validators/_validators.json均由 codegen 目录下的代码生成器自动生成文件头部的AUTO-GENERATED注释即是证据见 plotly/graph_objs/_scatter.py。生成逻辑定义在 codegen/datatypes.py、codegen/validators.py 中它们依据 Plotly.js 的 schema 为每个 trace 生成类定义与属性 validator。这意味着属性集合的增删改由生成器统一控制保证 Python 接口与 Plotly.js 底层 schema 严格对齐每个属性都有对应的 validator赋值错误会在构造时被即时捕获。5.2 懒加载导入机制plotly/graph_objs/init.py 在 Python 3.7 下并不在导入时加载全部类而是通过 _plotly_utils/importers.py 中的relative_import辅助函数实现lazy importdef relative_import(parent_name, rel_modules(), rel_classes()): ... def __getattr__(import_name): # In Python 3.7, lazy import submodules if import_name in module_names: return importlib.import_module(rel_modules[import_name], parent_name) if import_name in class_names: ... # 按需加载具体类 ... return __all__, __getattr__, __dir__这样import plotly.graph_objects as go的开销极小只有当你真正访问go.Scatter、go.Bar等属性时对应子模块才会被加载。作为用户你无需关心这一机制——go.XXX的写法与直接导入完全一致。同样plotly/graph_objects/init.py 通过relative_import把graph_objs中的全部类Figure、Layout、Frame、Scatter、Bar等重新导出到plotly.graph_objects命名空间并额外暴露了FigureWidget在 plotly/graph_objs/_figurewidget.py 中定义用于 Jupyter 交互场景见 plotly/graph_objects/init.py。而 plotly/graph_objs/graph_objs.py 一行from plotly.graph_objs import *提供了旧式兼容导入入口。5.3 类层次BaseFigure 与 BaseTraceType所有 graph_objects 类都继承自 plotly/basedatatypes.py 中定义的基类Figure→BaseFigure提供add_traces、update_traces、update_layout、show、to_json、write_html等 Figure 级方法Scatter、Bar等 trace →BaseTraceType提供属性校验、to_plotly_json序列化、update等能力Layout→BaseLayoutType提供布局属性管理与子图 id 识别。这套继承体系保证了无论哪类 trace都遵循统一的属性校验—dict 序列化—传给 Plotly.js 渲染的数据通路这也是为什么你可以放心地用go.Figure(fig.to_dict())往返拷贝图形。六、API 文档是如何从源码生成的graph_objects 的 API 参考页本身也是由 Sphinx 从代码驱动的。原文档 doc/apidoc/plotly.graph_objects.rst 使用autosummary指令配合两个模板doc/apidoc/_templates/class_figure.rst专用于Figure类会额外列出show、add_traces、update_traces、update_layout四个方法并生成automethod/autoclass文档doc/apidoc/_templates/trace.rst用于Layout与各类 trace按类定义 小写模块的成员两部分展开例如Scatter会同时生成plotly.graph_objs.Scatter与plotly.graph_objs.scatter的成员文档。此外 doc/apidoc/basefigure.rst 单独记录了BaseFigure基类。也就是说你在文档站上看到的每一个属性说明都来自 plotly/graph_objs 中对应类文件的 docstring文档内容与源码是同步的。如果你想查阅某个 trace 的全部属性最权威的路径就是阅读其_valid_props与构造函数 docstring。七、graph_objects 与其他接口的关系在 plotly.py 中graph_objects 位于接口分层的底层其上方是更便捷的高层封装接口入口定位plotly.expressimport plotly.express as px高层接口一行代码从 DataFrame 生成 Figure代码位于 plotly/expressplotly.graph_objectsimport plotly.graph_objects as go低层接口精确控制 Figure 的每个 trace 与 layout 属性plotly.subplotsfrom plotly.subplots import make_subplots子图辅助工具位于 plotly/subplots.pyplotly.figure_factoryimport plotly.figure_factory as ff特定领域图表的工厂函数位于 plotly/figure_factory实践建议快速探索数据用px需要精细控制如自定义 hover 模板、多子图坐标系、金融 K 线、桑基图等时直接使用go。两者产出物都是go.Figure实例可以互相转换与混用——例如先fig px.scatter(df, xa, yb)再fig.update_layout(...)或fig.add_traces(go.Scatter(...))继续精修。八、小结graph_objects 使用要点记住六类 trace 地图SimpleScatter/Bar/Pie/Heatmap/Contour/Table…、DistributionBox/Violin/Histogram…、FinanceOhlc/Candlestick/Waterfall…、3DScatter3d/Surface/Mesh3d/Volume…、MapScattergeo/Choropleth/Scattermap…、SpecializedSunburst/Sankey/Parcoords/Carpet…按需查阅 doc/apidoc/plotly.graph_objects.rst 的分类索引构建流程固定go.Figure(data..., layout...)或逐步add_tracesupdate_layout最后show()属性全部可查可验每个类、属性都来自 plotly/graph_objs 的自动生成源码与 validator 配置编写时可以利用 IDE 的类型提示和运行时报错双重校验子图靠 id 后缀Layout通过xaxis2、scene1这类带数字的属性自动识别多坐标系见 plotly/graph_objs/_layout.py接口层级分明px便捷、go精确两者共享同一套 Figure 数据结构可按需组合使用。【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
plotly.py 的 graph_objects 低层接口完全指南Figure、Trace 与 Layout 的构建体系【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.pyplotly.graph_objects是 plotly.py 中面向 Figure 的底层编程接口它提供了构成图形对象的全部积木各类 trace如Scatter、Bar与Layout。本文将基于仓库 doc/apidoc/plotly.graph_objects.rst 的 API 参考骨架结合 plotly/graph_objs 的源码实现系统讲解 graph_objects 的类层次、六大 trace 分类体系、Figure 的构建方式与底层机制帮助你掌握以go.Figure为核心的声明式绘图范式。一、graph_objects 是什么Figure 的构建积木plotly.graph_objects通常以别名go导入是 plotly.py 中构造Figure的低层接口。文档开篇即给出其定位plotly.graph_objectscontains the building blocks of plotlyFigure: traces (Scatter,Bar, ...) andLayout也就是说一个完整的 Figure 由两类对象拼装而成trace轨迹具体的数据系列如散点Scatter、柱状Bar、热力图Heatmap每个 trace 描述一组数据如何被绘制Layout布局整张图的全局配置包括坐标轴、标题、图例、模板、页边距等。标准导入方式与原文档保持一致 import plotly.graph_objects as go导入后即可用go.Figure(...)创建图形并组合各类 trace 与 Layout 完成定制。如果你用过plotly.expresspx的高层接口可以把它理解为px负责把 DataFrame 快速翻译成 Figure而go则让你直接、精确地操控 Figure 的每一个属性。二、Figuregraph_objects 的核心类2.1 类的真实定义Figure类定义在仓库 plotly/graph_objs/_figure.py 中注意文件头部标注了--- THIS FILE IS AUTO-GENERATED ---——这是由 codegen 工具自动生成的手改会在下次代码生成时被覆盖from plotly.basedatatypes import BaseFigure class Figure(BaseFigure): def __init__( self, dataNone, layoutNone, framesNone, skip_invalidFalse, **kwargs ):从构造函数签名plotly/graph_objs/_figure.py可以看到 Figure 的四个核心入参参数类型说明datatrace 实例或 dict 列表可传[Scatter(...), Bar(...)]这类 trace 实例列表也可传{type: scatter, ...}形式的 dict——此时type键指定 trace 类型其余键传给对应 trace 构造函数layoutLayout实例或 dict图的全局布局dict 会交给Layout构造函数解析framesFrame实例或 dict 列表动画帧用于go.Frame构建动画skip_invalidbool是否跳过无效属性校验默认为 False遇到未知属性会抛错其中data中可用的 trace 类型全集也写在构造函数 docstring 中包括bar、box、candlestick、choropleth、contour、heatmap、histogram、indicator、mesh3d、ohlc、pie、sankey、scatter、scatter3d、scattergeo、scattermap、scatterpolar、splom、sunburst、surface、table、treemap、violin、volume、waterfall等四十余种。2.2 Figure 的常用方法API 文档模板 doc/apidoc/_templates/class_figure.rst 特别为Figure类单独列出了四个高频方法Figure.show()渲染并展示图形Figure.add_traces()向已有 Figure 追加 traceFigure.update_traces()批量更新 trace 属性Figure.update_layout()批量更新布局属性。这也构成了 graph_objects 编程的核心工作流创建 Figure → add_traces 添加数据 → update_layout 定制外观 → show 展示。2.3 最小可运行示例import plotly.graph_objects as go fig go.Figure( data[go.Scatter(x[1, 2, 3], y[4, 5, 6], modelinesmarkers)], layoutgo.Layout(titleA minimal graph_objects figure), ) fig.show()也可以先创建空 Figure再逐步添加fig go.Figure() fig.add_traces(go.Scatter(x[1, 2, 3], y[4, 5, 6], nameseries A)) fig.update_layout(titleUpdated title) fig.show()三、Layout全局布局与子图坐标系Layout类定义于 plotly/graph_objs/_layout.py。它有两个值得注意的源码细节1. 子图坐标系统一注册。Layout通过_subplotid_prop_names声明了一组可带数字编号的子图属性_subplotid_prop_names [ coloraxis, geo, legend, map, polar, scene, smith, ternary, xaxis, yaxis, ]并用正则^(\w)(\d)$匹配形如xaxis2、yaxis3、scene1这样的属性名见 plotly/graph_objs/_layout.py。这意味着你不需要专门注册子图只要给坐标轴/场景属性加上数字后缀Layout就能自动识别多坐标系例如双 y 轴场景中同时设置yaxis与yaxis2。2. 全部布局属性集中在_valid_props。从activeselection、annotations、autosize开始Layout拥有数百个可配置属性标题title、图例legend、模板template、页边距margin、配色轴coloraxis等且所有属性都经过 validator 校验非法赋值会得到明确的错误提示。import plotly.graph_objects as go fig go.Figure(go.Bar(x[A, B, C], y[1, 3, 2])) fig.update_layout( titledict(textBar chart, fontdict(size18)), xaxisdict(titleCategory), yaxisdict(titleValue), legenddict(orientationh, yanchorbottom, y1.02), templateplotly_white, ) fig.show()四、Trace 六大分类体系原文档核心骨架原文档 doc/apidoc/plotly.graph_objects.rst 将全部 trace 划分为六大类这是了解 graph_objects 能力地图的最佳索引。下面逐一展开并补充每个 trace 的典型用途与仓库中的对应源码文件全部位于 plotly/graph_objs 目录文件名以_开头的小写类名如_scatter.py。4.1 Simple Traces基础轨迹Trace源码文件典型用途Scatter_scatter.py散点 / 折线图最通用的 trace支持modelines/markers/text、fill、stackgroup等Scattergl_scattergl.py基于 WebGL 的高性能散点适合十万级以上的大数据点Bar_bar.py柱状图支持水平/垂直、堆叠Pie_pie.py饼图 / 环形图Heatmap_heatmap.py二维热力图Image_image.py在图中显示图像如卫星影像Contour_contour.py等高线图Table_table.py表格以最常用的Scatter为例其属性集合定义在 plotly/graph_objs/_scatter.py 的_valid_props中包括x/y、mode、line、marker、text、hovertext、hovertemplate、fill、opacity、visible、xaxis/yaxis指定挂在哪个坐标轴上等六十多个属性且每个属性都经过 plotly/validators/_validators.json 中注册的 validator 校验。import plotly.graph_objects as go fig go.Figure(go.Scatter( x[1, 2, 3, 4], y[10, 11, 12, 13], modelinesmarkerstext, text[a, b, c, d], linedict(colorfirebrick, width2), markerdict(size10, symbolcircle), )) fig.show()4.2 Distribution Traces分布轨迹Trace源码文件典型用途Box_box.py箱线图展示数据分布的四分位与离群点Violin_violin.py小提琴图箱线图 核密度估计Histogram_histogram.py一维直方图支持nbinsx与累积模式Histogram2d_histogram2d.py二维直方图矩形分箱Histogram2dContour_histogram2dcontour.py二维直方图的等高线版本import plotly.graph_objects as go fig go.Figure(go.Box( y[1, 2, 3, 4, 5, 8, 9, 10], boxmeanTrue, notchedFalse, )) fig.show()4.3 Finance Traces金融轨迹Trace源码文件典型用途Ohlc_ohlc.pyOHLC开高低收K 线Candlestick_candlestick.py蜡烛图金融行情标配Waterfall_waterfall.py瀑布图展示增量贡献与累计Funnel_funnel.py漏斗图常用于转化率分析Funnelarea_funnelarea.py漏斗面积图Indicator_indicator.py仪表盘 / 数值指示器import plotly.graph_objects as go fig go.Figure(go.Candlestick( x[2024-01-01, 2024-01-02, 2024-01-03, 2024-01-04], open[100, 102, 101, 105], high[104, 106, 105, 108], low[99, 101, 100, 104], close[102, 101, 105, 107], )) fig.show()4.4 3D Traces三维轨迹Trace源码文件典型用途Scatter3d_scatter3d.py三维散点 / 折线Surface_surface.py三维曲面图Mesh3d_mesh3d.py三维网格 / 三角剖分曲面Cone_cone.py锥体图常用于向量场可视化Streamtube_streamtube.py流管图可视化流体场Volume_volume.py三维体绘制Isosurface_isosurface.py等值面提取3D trace 通常配合Layout中的scene三维场景属性使用场景含xaxis/yaxis/zaxis、相机camera、灯光lighting等子配置import plotly.graph_objects as go import numpy as np x np.linspace(-5, 5, 50) y np.linspace(-5, 5, 50) X, Y np.meshgrid(x, y) Z np.sin(np.sqrt(X**2 Y**2)) fig go.Figure(go.Surface(xX, yY, zZ, colorscaleViridis)) fig.update_layout( scenedict( xaxisdict(titleX), yaxisdict(titleY), zaxisdict(titleZ), cameradict(eyedict(x1.5, y1.5, z1.5)), ) ) fig.show()4.5 Map Traces地图轨迹Trace源码文件典型用途Scattergeo_scattergeo.py地理坐标系geo上的散点 / 连线Choropleth_choropleth.py按地理区域着色的分级统计图Scattermap_scattermap.py基于 MapLibre 底图的散点Choroplethmap_choroplethmap.py基于 MapLibre 底图的分级着色Densitymap_densitymap.py基于 MapLibre 底图的密度热力地图类 trace 依赖Layout中的geo或map子配置来指定投影、中心点、缩放级别与底图样式对应 plotly/graph_objs/layout 目录下的geo、map模块。4.6 Specialized Traces专用轨迹Trace源码文件典型用途Scatterpolar_scatterpolar.py极坐标散点 / 折线Scatterpolargl_scatterpolargl.py极坐标 WebGL 高性能版本Barpolar_barpolar.py极坐标柱状玫瑰图Scatterternary_scatterternary.py三元相图散点Sunburst_sunburst.py旭日图径向层次树Treemap_treemap.py矩形树图Icicle_icicle.py冰柱图矩形层次树Sankey_sankey.py桑基图节点-流量图Parcats_parcats.py平行类别图Parcoords_parcoords.py平行坐标图Carpet_carpet.py地毯图自定义网格坐标系Scattercarpet_scattercarpet.py地毯坐标系上的散点Contourcarpet_contourcarpet.py地毯坐标系上的等高线import plotly.graph_objects as go fig go.Figure(go.Sankey( nodedict( label[Source A, Source B, Middle, Sink], color[blue, blue, orange, orange], ), linkdict( source[0, 1, 0, 2], target[2, 2, 3, 3], value[8, 3, 4, 7], ), )) fig.update_layout(title_textSankey example) fig.show()五、源码级机制graph_objects 是如何组织起来的5.1 自动生成的文件体系plotly/graph_objs下的所有 trace 类文件_scatter.py、_bar.py、_layout.py……与plotly/validators/_validators.json均由 codegen 目录下的代码生成器自动生成文件头部的AUTO-GENERATED注释即是证据见 plotly/graph_objs/_scatter.py。生成逻辑定义在 codegen/datatypes.py、codegen/validators.py 中它们依据 Plotly.js 的 schema 为每个 trace 生成类定义与属性 validator。这意味着属性集合的增删改由生成器统一控制保证 Python 接口与 Plotly.js 底层 schema 严格对齐每个属性都有对应的 validator赋值错误会在构造时被即时捕获。5.2 懒加载导入机制plotly/graph_objs/init.py 在 Python 3.7 下并不在导入时加载全部类而是通过 _plotly_utils/importers.py 中的relative_import辅助函数实现lazy importdef relative_import(parent_name, rel_modules(), rel_classes()): ... def __getattr__(import_name): # In Python 3.7, lazy import submodules if import_name in module_names: return importlib.import_module(rel_modules[import_name], parent_name) if import_name in class_names: ... # 按需加载具体类 ... return __all__, __getattr__, __dir__这样import plotly.graph_objects as go的开销极小只有当你真正访问go.Scatter、go.Bar等属性时对应子模块才会被加载。作为用户你无需关心这一机制——go.XXX的写法与直接导入完全一致。同样plotly/graph_objects/init.py 通过relative_import把graph_objs中的全部类Figure、Layout、Frame、Scatter、Bar等重新导出到plotly.graph_objects命名空间并额外暴露了FigureWidget在 plotly/graph_objs/_figurewidget.py 中定义用于 Jupyter 交互场景见 plotly/graph_objects/init.py。而 plotly/graph_objs/graph_objs.py 一行from plotly.graph_objs import *提供了旧式兼容导入入口。5.3 类层次BaseFigure 与 BaseTraceType所有 graph_objects 类都继承自 plotly/basedatatypes.py 中定义的基类Figure→BaseFigure提供add_traces、update_traces、update_layout、show、to_json、write_html等 Figure 级方法Scatter、Bar等 trace →BaseTraceType提供属性校验、to_plotly_json序列化、update等能力Layout→BaseLayoutType提供布局属性管理与子图 id 识别。这套继承体系保证了无论哪类 trace都遵循统一的属性校验—dict 序列化—传给 Plotly.js 渲染的数据通路这也是为什么你可以放心地用go.Figure(fig.to_dict())往返拷贝图形。六、API 文档是如何从源码生成的graph_objects 的 API 参考页本身也是由 Sphinx 从代码驱动的。原文档 doc/apidoc/plotly.graph_objects.rst 使用autosummary指令配合两个模板doc/apidoc/_templates/class_figure.rst专用于Figure类会额外列出show、add_traces、update_traces、update_layout四个方法并生成automethod/autoclass文档doc/apidoc/_templates/trace.rst用于Layout与各类 trace按类定义 小写模块的成员两部分展开例如Scatter会同时生成plotly.graph_objs.Scatter与plotly.graph_objs.scatter的成员文档。此外 doc/apidoc/basefigure.rst 单独记录了BaseFigure基类。也就是说你在文档站上看到的每一个属性说明都来自 plotly/graph_objs 中对应类文件的 docstring文档内容与源码是同步的。如果你想查阅某个 trace 的全部属性最权威的路径就是阅读其_valid_props与构造函数 docstring。七、graph_objects 与其他接口的关系在 plotly.py 中graph_objects 位于接口分层的底层其上方是更便捷的高层封装接口入口定位plotly.expressimport plotly.express as px高层接口一行代码从 DataFrame 生成 Figure代码位于 plotly/expressplotly.graph_objectsimport plotly.graph_objects as go低层接口精确控制 Figure 的每个 trace 与 layout 属性plotly.subplotsfrom plotly.subplots import make_subplots子图辅助工具位于 plotly/subplots.pyplotly.figure_factoryimport plotly.figure_factory as ff特定领域图表的工厂函数位于 plotly/figure_factory实践建议快速探索数据用px需要精细控制如自定义 hover 模板、多子图坐标系、金融 K 线、桑基图等时直接使用go。两者产出物都是go.Figure实例可以互相转换与混用——例如先fig px.scatter(df, xa, yb)再fig.update_layout(...)或fig.add_traces(go.Scatter(...))继续精修。八、小结graph_objects 使用要点记住六类 trace 地图SimpleScatter/Bar/Pie/Heatmap/Contour/Table…、DistributionBox/Violin/Histogram…、FinanceOhlc/Candlestick/Waterfall…、3DScatter3d/Surface/Mesh3d/Volume…、MapScattergeo/Choropleth/Scattermap…、SpecializedSunburst/Sankey/Parcoords/Carpet…按需查阅 doc/apidoc/plotly.graph_objects.rst 的分类索引构建流程固定go.Figure(data..., layout...)或逐步add_tracesupdate_layout最后show()属性全部可查可验每个类、属性都来自 plotly/graph_objs 的自动生成源码与 validator 配置编写时可以利用 IDE 的类型提示和运行时报错双重校验子图靠 id 后缀Layout通过xaxis2、scene1这类带数字的属性自动识别多坐标系见 plotly/graph_objs/_layout.py接口层级分明px便捷、go精确两者共享同一套 Figure 数据结构可按需组合使用。【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考