4、数据展示组件：st.dataframe、st.table、st.metric、st.json 的实战应用

在数据科学 Web 应用的开发中，数据展示是连接分析结果与业务决策的核心桥梁。Streamlit 提供了四类各具特色的数据展示组件：st.dataframe 用于交互式探索大型数据集，st.table 用于静态精确呈现，st.metric 用于突出关键业务指标，st.json 用于结构化调试与 API 对接。本章将深入剖析每个组件的适用场景、核心参数、性能边界及组合策略，帮助你在实际项目中做出正确的选型与设计。

4.1 核心原理：四种组件的设计哲学与底层机制

理解这四种组件的本质差异，是正确选型的前提。st.dataframe 基于 PyArrow 与 Glide Data Grid 技术，采用虚拟滚动机制，只渲染当前视口内的行，因此能够流畅处理数十万行数据。它默认支持列排序、列宽拖拽、单元格选择，并自动根据数据类型渲染条形图（数值列）或迷你图（时间序列）。其核心价值在于探索性分析——用户需要滚动、排序、筛选来发现数据中的模式。

st.table 则完全不同，它是一个静态 HTML 表格，一次性将全部数据渲染到 DOM 中。这意味着它不具备任何交互能力，但换来的是精确的布局控制和极低的渲染开销（对于小数据）。当数据量超过 500 行时，st.table 的渲染时间会显著上升，因为浏览器需要构建大量 DOM 节点。它的设计哲学是确定性呈现——所见即所得，适合用于报告、打印或需要精确对齐的场景。

st.metric 是一个轻量级指标卡片组件，专门用于展示单个数值及其变化量。它接受 value（当前值）、delta（与基准值的差异）和 delta_color（涨跌颜色）三个核心参数。其底层实现是简单的 HTML/CSS 卡片，但 Streamlit 内置了智能的颜色逻辑：正 delta 默认绿色，负 delta 默认红色，且支持 inverse 模式（用于成本、错误率等越低越好的指标）。

st.json 是一个 JSON 格式化查看器，它递归地将 Python 字典、列表或 JSON 字符串渲染为可折叠的树形结构。它使用语法高亮区分键、字符串、数字和布尔值，并支持展开/折叠嵌套层级。其核心价值在于结构化调试——当你的 API 返回复杂嵌套数据时，st.json 能让你快速定位到特定字段，而无需在控制台打印大量文本。

4.2 操作流程与关键参数：从入门到进阶

掌握每个组件的核心参数，是构建高效数据应用的基础。以下逐一拆解各组件的高频用法与易忽略的细节。

4.2.1 st.dataframe 的进阶用法

基础调用只需传入 DataFrame 即可，但实际项目中往往需要定制显示效果。关键参数包括：width 和 height 控制组件尺寸；use_container_width 让表格自适应容器宽度；hide_index 隐藏行索引；column_config 是 Streamlit 1.23+ 版本引入的强力配置接口，可以定义每列的显示类型（进度条、图片、链接、日期等）。

import pandas as pd
import streamlit as st

df = pd.DataFrame({
    "产品": ["A", "B", "C"],
    "销量": [1200, 850, 2100],
    "增长率": [0.15, -0.08, 0.32],
    "上市日期": pd.to_datetime(["2024-01-15", "2024-03-22", "2024-06-01"])
})

st.dataframe(
    df,
    width=700,
    height=300,
    hide_index=True,
    column_config={
        "销量": st.column_config.NumberColumn("月销量", format="%d 件"),
        "增长率": st.column_config.ProgressColumn("增长", min_value=-0.5, max_value=0.5, format="%.1f%%"),
        "上市日期": st.column_config.DateColumn("上市时间")
    }
)

这段代码展示了如何将增长率列渲染为进度条，销量格式化为带单位的数字，日期列显示为日期格式。这种配置让数据呈现更直观，减少了用户的理解成本。

4.2.2 st.table 与 st.metric 的精确控制

st.table 的参数相对简单，主要是 data 和 width。但有一个重要技巧：当需要展示 DataFrame 的样式（如背景色、字体颜色）时，可以使用 df.style.applymap() 生成 Styler 对象，再传给 st.table。这比 st.dataframe 的 column_config 更灵活，适合复杂条件格式。

# 使用 Styler 实现条件高亮
styled_df = df.style.applymap(
    lambda v: "color: red" if v < 0 else "color: green",
    subset=["增长率"]
)
st.table(styled_df)

st.metric 的进阶用法在于 delta 的灵活计算。除了直接传入数值，还可以传入带箭头的字符串（如 "▲ 12%"），或者使用 delta_color="off" 关闭颜色变化。在仪表盘布局中，常配合 st.columns 将多个 metric 并排展示，形成 KPI 卡片组。

col1, col2, col3 = st.columns(3)
col1.metric("总营收", "¥1,284,500", "+12.3%", delta_color="normal")
col2.metric("客户流失率", "3.2%", "-0.8%", delta_color="inverse")  # 越低越好
col3.metric("服务器响应", "142ms", "+18ms", delta_color="inverse")

4.2.3 st.json 的实用技巧

st.json 接受 Python 对象或 JSON 字符串。当处理大型 JSON 时，建议先使用 json.dumps(obj, indent=2) 格式化，但 st.json 本身已内置格式化。一个实用技巧是结合 st.expander 将 JSON 查看器折叠起来，避免占用过多页面空间。此外，st.json 支持 expanded 参数控制默认展开层级（默认展开所有层级，深嵌套时建议设为 False 或指定层级）。

api_response = {
    "status": "success",
    "data": {
        "users": [{"id": 1, "name": "Alice", "tags": ["admin", "editor"]}],
        "meta": {"total": 1, "page": 1}
    }
}
with st.expander("查看 API 原始响应", expanded=False):
    st.json(api_response, expanded=2)  # 只展开前两层

4.3 实战案例：构建一个销售数据监控看板

为了综合运用四种组件，我们设计一个销售监控看板的完整案例。假设你是一家电商公司的数据分析师，需要为运营团队构建一个实时监控页面，展示核心 KPI、订单明细、异常订单 JSON 日志。

场景约束与目标：运营团队需要在一屏内快速掌握当日销售概况，并能下钻查看异常订单详情。数据源为模拟的 10,000 行订单数据（包含订单号、金额、状态、异常原因等字段）。初始现象是运营反馈“数据太多，找不到重点”，因此看板需要分层展示：顶层用 metric 展示 KPI，中层用 dataframe 展示可筛选的订单明细，底层用 json 展示异常订单的完整上下文。

关键输入数据：模拟生成 10,000 条订单记录，其中约 2% 为异常订单（状态为“失败”或“退款中”）。核心指标包括：总销售额、订单成功率、平均客单价。

import pandas as pd
import numpy as np
import streamlit as st

# 模拟数据生成
np.random.seed(42)
n = 10000
orders = pd.DataFrame({
    "订单号": [f"ORD-{i:05d}" for i in range(n)],
    "金额": np.random.uniform(50, 500, n).round(2),
    "状态": np.random.choice(["成功", "成功", "成功", "失败", "退款中"], n, p=[0.7, 0.15, 0.13, 0.01, 0.01]),
    "异常原因": np.where(np.random.rand(n) < 0.02, "支付超时", np.where(np.random.rand(n) < 0.01, "库存不足", ""))
})

# 计算 KPI
total_sales = orders["金额"].sum()
success_rate = (orders["状态"] == "成功").mean()
avg_order = orders["金额"].mean()

# 布局：三列 KPI
c1, c2, c3 = st.columns(3)
c1.metric("总销售额", f"¥{total_sales:,.0f}", "+5.2%")
c2.metric("订单成功率", f"{success_rate:.1%}", "-0.3%", delta_color="inverse")
c3.metric("平均客单价", f"¥{avg_order:.2f}", "+1.8%")

# 异常订单筛选
abnormal = orders[orders["状态"] != "成功"]
st.subheader(f"异常订单明细（{len(abnormal)} 条）")
st.dataframe(
    abnormal[["订单号", "金额", "状态", "异常原因"]],
    use_container_width=True,
    hide_index=True,
    column_config={
        "金额": st.column_config.NumberColumn(format="¥%.2f"),
        "状态": st.column_config.TextColumn("订单状态"),
    }
)

# 查看第一条异常订单的完整 JSON 日志
if not abnormal.empty:
    sample = abnormal.iloc[0]
    log_data = {
        "order_id": sample["订单号"],
        "amount": sample["金额"],
        "status": sample["状态"],
        "error_reason": sample["异常原因"],
        "retry_count": 3,
        "timeline": ["2024-06-01 10:23:15 创建", "2024-06-01 10:23:18 支付请求", "2024-06-01 10:23:45 超时"]
    }
    with st.expander("查看异常订单完整日志", expanded=False):
        st.json(log_data)

分析判断过程：在构建过程中，我们发现 st.dataframe 渲染 10,000 行数据时依然流畅，但 st.table 在相同数据量下会导致页面卡顿约 3 秒。因此，明细表选用 st.dataframe 并配合 use_container_width 自适应屏幕。对于异常订单的 JSON 日志，使用 st.expander 折叠，避免默认展开占用过多垂直空间。

结果对比与复盘：看板交付后，运营团队反馈“一眼就能看到核心指标，点击异常订单能快速定位问题”。相比之前使用 Excel 报表，信息获取时间从平均 5 分钟缩短到 30 秒。但我们也发现一个风险：当异常订单超过 500 条时，dataframe 的滚动性能开始下降，后续优化方案是增加日期筛选器，让用户先缩小范围再查看明细。

4.4 常见误区与性能调优总结

在实际项目中，开发者常陷入以下误区，导致应用性能下降或用户体验受损。

• 误区一：用 st.table 展示大数据集。st.table 一次性渲染所有 DOM 节点，当数据超过 1,000 行时，页面会明显卡顿。正确做法是：数据量 > 500 行时优先使用 st.dataframe，并利用其内置的虚拟滚动能力。
• 误区二：忽略 column_config 的威力。很多开发者只使用默认的表格显示，导致长文本被截断、数字格式不统一。通过 column_config 可以轻松实现进度条、图片、链接、日期格式化等高级展示，大幅提升可读性。
• 误区三：在 st.metric 中塞入过多信息。metric 组件只适合展示单一数值和 delta，不要试图在其中加入图表或长文本。如果需要更多上下文，可以在 metric 下方用 st.caption 补充说明。
• 误区四：st.json 嵌套过深导致性能问题。当 JSON 层级超过 5 层且包含大量数组时，st.json 的渲染时间会显著增加。建议在传入前对数据进行裁剪，或使用 expanded=False 默认折叠。

最后，需要强调的是，四种组件并非互斥，而是可以灵活组合。一个成熟的数据应用通常采用“metric 总览 + dataframe 明细 + json 调试”的三层结构，既满足决策者的快速浏览需求，也兼顾分析师的深入探索需求。掌握每种组件的边界与最佳实践，才能构建出专业、高效、用户友好的数据科学 Web 应用。