本文详解如何使用 `go.scatter3d` 的 `marker` 参数（而非独立的 `color` 或 `markers` 参数）精确控制新增 3d 数据点的颜色、形状、大小等视觉属性，并纠正常见参数误用。
在 Plotly 中，向已有的 3D 图形（如由 plotly.express.scatter_3d 创建的图表）添加新数据轨迹时，必须使用 go.Scatter3d 类，并通过其 嵌套的 marker 字典统一配置视觉样式——这是关键前提。直接传入 color='black' 或 markers='s' 会报错，因为 Scatter3d 不接受这些顶层参数；正确做法是将所有标记属性封装在 marker=dict(...) 中。
以下是完整、可运行的示例代码：
import plotly.express as px
import plotly.graph_objects as go
import pandas as pd
# 示例数据
df = pd.DataFrame({'x': [1, 2, 3], 'y': [0, 1, 2], 'z': [1, 1, 1]})
df2 = pd.DataFrame({'x': [4, 5], 'y': [3, 4], 'z': [2, 2]})
# 创建基础 3D 散点图
fig = px.scatter_3d(df, x='x', y='y', z='z', title="3D Scatter with Custom Markers")
# 添加第二组数据：自定义黑色方块标记
fig.add_trace(
go.Scatter3d(
x=df2["x"],
y=df2["y"],
z=df2["z"],
mode='markers',
marker=dict(
color='black', # 支持颜色名、HEX、RGB、RGBA 或数值数组（用于映射）
symbol='square', # 常用值：'circle', 'square', 'diamond', 'cross', 'x', 'triangle-up' 等
size=8, # 可选：统一大小（像素）
line=dict(width=1, color='white') # 可选：标记边框
)
)
)
fig.show()⚠️ 注意事项：
- symbol 参数不支持简写（如 's'），必须使用完整字符串（如 'square'）；
- 若需为每个点指定不同颜色，可传入列表或 NumPy 数组（如 color=[0.2, 0.5, 0.9]），并配合 colorscale 和 cmin/cmax 实现色标映射；
- go.scatter3d（小写）不是合法类名，Plotly 中唯一正确的类是 go.Scatter3d（首字母大写）；
- mode='markers' 是必需的，否则即使设置了 marker 也不会渲染点；
- 所有 marker 子属性均支持响应式更新（例如在回调中动态修改）。
掌握 marker=dict(...) 这一统一入口，即可灵活组合颜色、形状、大小、透明度（opacity）、边框等，实现高度定制化的 3D 可视化效果。
