如何在Shiny for Python中正确渲染Plotly 3D曲面图的日期轴？

问题描述 #

在Shiny for Python环境中使用Plotly绘制3D曲面图时，日期类型的X轴被渲染为浮点数；但相同代码直接通过fig.show()渲染时，X轴能正常显示日期。尝试显式设置轴类型为日期后，图表完全无法渲染，设置代码如下：

fig.update_layout(
    scene=dict(
        xaxis=dict(
            type="date",
            tickformat='%Y'
        )
    )
)

解决方案 #

1. 手动映射日期刻度（推荐） #

Plotly 3D场景的轴对type="date"的支持存在兼容性问题，在Shiny环境中更可靠的方式是：将日期转换为数值型时间戳，再手动绑定刻度值与日期文本，既保证曲面图的数值计算正常，又能显示正确的日期格式。示例代码：

import pandas as pd
import plotly.graph_objects as go
from shiny import App, render, ui

# 示例数据
df = pd.DataFrame({
    "date": pd.date_range(start="2020-01-01", periods=10),
    "y": range(10),
    "z": [i*j for i,j in zip(range(10), range(10))]
})

# 将日期转为Unix时间戳（秒级，适配Plotly数值计算）
df["date_num"] = df["date"].astype(int) // 10**9

# 创建3D曲面图
fig = go.Figure(data=[go.Surface(z=df["z"].values, x=df["date_num"].values, y=df["y"].values)])

# 手动设置X轴刻度：用时间戳对应数值作为刻度值，日期文本作为显示内容
fig.update_layout(
    scene=dict(
        xaxis=dict(
            tickvals=df["date_num"].values,
            ticktext=df["date"].dt.strftime("%Y-%m-%d").values,
            tickangle=45  # 旋转刻度避免重叠
        )
    )
)

2. 确保Shiny渲染逻辑正确 #

在Shiny的渲染函数中直接返回完整的Plotly图表对象，避免对日期数据做额外自动转换：

@render.plotly
def plot():
    # 上述创建fig的逻辑
    return fig

原理说明 #

3D曲面图依赖数值型轴数据构建曲面模型，在Shiny环境中，日期对象会被自动序列化为底层浮点数（日期的数值表示），导致轴显示为浮点数。手动映射刻度值与文本，既保留了数值型轴数据的计算能力，又覆盖了显示内容，同时避开了3D场景下type="date"的渲染冲突问题。

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