Plotly中add_trace与append_trace的区别及版本遗留性问询

首先直接给结论：append_trace确实是add_trace的遗留（Legacy）版本，在当前Plotly.py的使用场景中，两者在功能上几乎没有差异，但官方已更推荐使用add_trace。

具体细节分析： #

• 引用占比差异：从Plotly.py的GitHub仓库引用数据来看，add_trace在Markdown文档和Python代码中的引用量（88+21次）远高于append_trace（9+7次），且append_trace的引用大多集中在旧文档和figure_factory这类相对老旧的模块中，说明官方已经在逐步淘汰这个API。
• 子图场景验证：你提到的子图示例代码中，将append_trace替换为add_trace后没有明显差异，这是因为在当前版本中，append_trace本质上是add_trace的别名或者兼容实现，目的是为了兼容旧代码。比如你提供的示例：

原代码（使用append_trace）：

from plotly.subplots import make_subplots
import plotly.graph_objects as go
fig = make_subplots(rows=3, cols=1)
fig.append_trace(go.Scatter(
    x=[3, 4, 5],
    y=[1000, 1100, 1200],
), row=1, col=1)
fig.append_trace(go.Scatter(
    x=[2, 3, 4],
    y=[100, 110, 120],
), row=2, col=1)
fig.append_trace(go.Scatter(
    x=[0, 1, 2],
    y=[10, 11, 12]
), row=3, col=1)
fig.update_layout(height=600, width=600, title_text="Stacked Subplots")
fig.show()

替换为add_trace后的代码：

from plotly.subplots import make_subplots
import plotly.graph_objects as go
fig = make_subplots(rows=3, cols=1)
fig.add_trace(go.Scatter(
    x=[3, 4, 5],
    y=[1000, 1100, 1200],
), row=1, col=1)
fig.add_trace(go.Scatter(
    x=[2, 3, 4],
    y=[100, 110, 120],
), row=2, col=1)
fig.add_trace(go.Scatter(
    x=[0, 1, 2],
    y=[10, 11, 12]
), row=3, col=1)
fig.update_layout(height=600, width=600, title_text="Stacked Subplots")
fig.show()

运行后效果完全一致。

• 官方文档导向：在Plotly的子图官方文档中，add_trace的出现次数（52次）远超append_trace（仅4次），这也明确体现了官方的推荐方向——优先使用add_trace来添加轨迹。

总结建议： #

如果是编写新代码，建议直接使用add_trace；如果是维护旧代码，append_trace暂时也能正常工作，但长远来看最好逐步迁移到add_trace，避免后续版本中可能出现的兼容性问题。

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