Streamlit中Altair无法基于Pandas DataFrame渲染图表

AI 小北

2026-6-12

解决Altair渲染时将Pandas DataFrame识别为Narwhals DataFrame的问题

问题核心在于：尽管你通过copy()得到的native_data被识别为Pandas DataFrame，但Altair在渲染阶段解析图表数据时，实际拿到的是Narwhals DataFrame实例。这是因为Narwhals的DataFrame存在延迟求值或隐式包装特性，copy()仅做浅拷贝，并未完全剥离Narwhals的底层绑定，当Altair触发数据校验逻辑时，Narwhals会将数据转回自身类型。

解决方案

直接显式将Narwhals DataFrame转换为纯Pandas DataFrame，不要依赖copy()方法，可选两种方式：

方式1（推荐）：使用Narwhals内置的to_pandas()方法（适配多数Narwhals版本）
方式2：用Pandas构造函数强制转换

修改后的代码示例

import pandas as pd
import altair as alt
import streamlit as st
import traceback

# ... 你的其他业务代码 ...

try:
    # 替换原copy()为显式转换二选一
    native_data = data.to_pandas()  # 方式1：Narwhals原生转换
    # native_data = pd.DataFrame(data)  # 方式2：Pandas构造函数强制转换
    
    st.write(f"Debug: Native data type: {type(native_data)}")
    chart = alt.Chart(native_data).mark_bar().encode(
        x=alt.X(x_col, type='nominal'),
        y=alt.Y(y_col, type='quantitative')
    ).properties(
        title=self._label,
        width=400,
        height=300
    )
    
except Exception as chart_creation_error:
    st.write(f"Debug: Chart creation error: {chart_creation_error}")
    return "table_only"

try:
    container.altair_chart(chart, use_container_width=True)
    return "success"
    
except Exception as render_error:
    st.write(f"Debug: Render error traceback:")
    st.code(traceback.format_exc())
    raise render_error