Streamlit Dashboard App Templates 实战指南：官方数据看板模板与十大规范模式

Streamlit Dashboard App Templates 实战指南：官方数据看板模板与十大规范模式

【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit

本指南以 Streamlit 仓库内置的 Dashboard 模板集（lib/streamlit/.agents/skills/developing-with-streamlit/assets/templates/apps/README.md）为主线，系统讲解 6 个可直接运行的看板模板，以及它们背后沉淀的页面配置、时间范围过滤、@st.fragment(parallel=True)并行卡片、st.skeleton占位、@st.cache_data(ttl=...)数据缓存等一套可复用的"规范模式"。读完本文，你将能够开箱运行任何一个模板，并掌握用 Streamlit 构建高性能数据驱动看板的完整套路。

模板总览：两套模板，六种形态

该目录下的模板分为两类：一类是基于官方演示应用、开箱即用的公共演示模板；另一类是使用合成数据演示常见看板模式的"分析型"模板，只需把数据生成函数替换成真实数据源即可用于生产。

公共演示模板

分析型看板模板

快速开始：本地运行一个模板

模板目录中每个应用都是独立的 Python 项目，使用uv作为包管理器。运行命令如下（以 dashboard-metrics 为例）：

# 进入模板目录 cd lib/streamlit/.agents/skills/developing-with-streamlit/assets/templates/apps/dashboard-metrics # 依据 pyproject.toml 同步依赖 uv sync # 启动应用 uv run streamlit run streamlit_app.py

运行后浏览器会自动打开看板页面。由于模板使用合成数据生成函数，不需要任何外部服务即可完整体验所有交互特性；替换数据源后即可直接对接真实业务数据。

模板结构：统一的目录约定

每个模板都遵循相同的目录结构，便于复制与改造：

dashboard-{name}/ ├── streamlit_app.py # 主应用代码 └── pyproject.toml # 依赖与元数据

以 dashboard-metrics/pyproject.toml 为例，其依赖声明如下：

[project] name = "dashboard-metrics" version = "1.0.0" description = "A metrics dashboard template showing time series with sparklines and filtering" requires-python = ">=3.10" dependencies = [ "altair>=5.5.0", "numpy>=1.26.0", "pandas>=2.2.3", "streamlit", ]

规范模式一：页面配置

所有模板都要求把st.set_page_config作为第一个 Streamlit 调用，且固定使用layout="wide"和一个 Material 图标：

st.set_page_config( page_title="My Dashboard", page_icon=":material/monitoring:", layout="wide", )

从源码看，每个模板都严格遵守该约定，例如 dashboard-metrics/streamlit_app.py 使用page_icon=":material/monitoring:"，dashboard-compute/streamlit_app.py 使用:material/bolt:，dashboard-stock-peers/streamlit_app.py 使用:material/query_stats:。Material 图标（:material/xxx:语法）无需额外资源即可渲染，宽屏布局则给多列卡片和图表留足空间。

规范模式二：标准常量命名

模板统一使用以下常量名，保证跨模板可读性与一致性：

TIME_RANGES = ["1M", "6M", "1Y", "QTD", "YTD", "All"] CHART_HEIGHT = 300 # 标准图表高度（像素）

在 dashboard-metrics 中对应 TIME_RANGES 与 CHART_HEIGHT 的定义；dashboard-compute 使用CHART_HEIGHT = 350，并额外定义ACCOUNT_TYPES、INSTANCE_TYPES、REGIONS等维度常量。

规范模式三：时间范围过滤

所有支持时间过滤的看板模板都复用同一个filter_by_time_range函数，对"相对时间窗口"给出统一的语义：

def filter_by_time_range(df: pd.DataFrame, x_col: str, time_range: str) -> pd.DataFrame: """Filter dataframe by time range.""" if time_range == "All" or df.empty: return df df = df.copy() df[x_col] = pd.to_datetime(df[x_col]) max_date = df[x_col].max() if time_range == "1M": min_date = max_date - timedelta(days=30) elif time_range == "6M": min_date = max_date - timedelta(days=180) elif time_range == "1Y": min_date = max_date - timedelta(days=365) elif time_range == "QTD": quarter_month = ((max_date.month - 1) // 3) * 3 + 1 min_date = pd.Timestamp(date(max_date.year, quarter_month, 1)) elif time_range == "YTD": min_date = pd.Timestamp(date(max_date.year, 1, 1)) else: return df filtered: pd.DataFrame = df[df[x_col] >= min_date] return filtered

该函数以数据自身的最大日期为基准计算起点：1M/6M/1Y分别向前推 30/180/365 天；QTD回到当前季度首日，YTD回到当年 1 月 1 日。它在 dashboard-metrics/streamlit_app.py 与 dashboard-compute/streamlit_app.py 中逐字复用，保证行为完全一致。

规范模式四：Popover 过滤器

紧凑型过滤控件使用st.popover收纳，让过滤器不占用主区域空间：

with st.popover("Filters", type="tertiary"): line_options = st.pills("Lines", ["Daily", "7-day MA"], selection_mode="multi") time_range = st.segmented_control("Time range", TIME_RANGES, default="All")

在 dashboard-metrics 的卡片实现中，popover 内还包含视图切换与多选 pills，所有 widget 使用f"{metric_name}_xxx"作为 key 前缀做状态隔离（见 metric_card 函数）。dashboard-compute 的 popover 则承载更多控件：维度多选、折线/柱状切换、百分比归一化开关与时间范围，全部以key_prefix隔离状态。

规范模式五：页面头部与重置按钮

看板头部统一由render_page_header渲染，标题与重置按钮水平排布：

def render_page_header(title: str): """Render page header with title and reset button.""" with st.container( horizontal=True, horizontal_alignment="distribute", vertical_alignment="center" ): st.markdown(title) if st.button(":material/restart_alt: Reset", type="tertiary"): st.session_state.clear() st.rerun()

点击重置按钮会清空全部会话状态并触发st.rerun()，把所有过滤器恢复到默认值，是看板应用最常见的"一键复原"交互。该函数在 dashboard-metrics 与 dashboard-compute 中保持一致。

规范模式六：用 @st.fragment 实现独立并行的卡片更新

这是分析型模板最核心的性能模式。每个卡片用@st.fragment包裹，使 widget 交互只重跑该卡片而非整个页面；当多个卡片各自有独立的、计算密集的数据加载时，加上parallel=True，让它们在整页重跑时并发执行。加载体用st.skeleton包裹，卡片在数据就绪前先显示占位符：

@st.fragment(parallel=True) def metric_card(metric_name: str): with st.container(border=True): st.markdown(f"**{metric_name}**") # 标题保持稳定，不随加载闪烁 with st.skeleton(height=300): data = load_metric(metric_name) # 缓存 + 并行加载 st.line_chart(data)

需要特别注意的约束：不要把st.dialog、st.switch_page以及对 fragment 之外创建的容器的写入，放进并行 fragment 里。这类操作应放在 widget 交互之后（此时 fragment 是串行重跑的）再执行，否则会与并行执行模型冲突。这一约束在 dashboard-metrics 的metric_card（源码位置）中有完整示范：标题、控件保持在 skeleton 之外，数据加载与图表渲染放在st.skeleton内部。

规范模式七：带缓存的数据加载

昂贵的数据加载必须缓存，并用ttl（必要时配合max_entries）约束，让缓存既保持新鲜又不会无限增长。直接运行在页面中的 loader 使用自定义 spinner 文案；只有当周围已有加载 UI（如st.skeleton）时才使用show_spinner=False：

@st.cache_data(ttl="1h", show_spinner="Loading metric data...") def load_metric_data() -> pd.DataFrame: """Load metric data. Replace with your actual data source.""" # 替换为真实数据源： # - API 调用 # - 数据库查询 # - 通过 st.connection 查询数据仓库 return generate_synthetic_data()

TTL 选型指南（README 明确给出的经验法则）：

• 实时数据→ttl="1m"
• 指标/报表→ttl="5m"–"15m"
• 参考数据→ttl="1h"或更长
• 静态数据→ 不设 TTL

对于参数化 loader，应使用max_entries限制缓存条目数量，保证按参数分键的缓存不失控。该模式在各模板中的落地：

• dashboard-metrics 的load_metric使用@st.cache_data(ttl="1h", show_spinner=False)，按指标名分别缓存，配合并行 fragment 并发加载（源码）；
• dashboard-feature-usage 的load_api_data使用自定义 spinner"Loading API usage data..."（源码）；
• dashboard-companies 的load_company_data同样带自定义 spinner（源码）；
• dashboard-stock-peers 的load_data使用ttl="6h"并捕获YFRateLimitError，在触发限流时主动load_data.clear()清掉坏缓存条目（源码）。

六个模板逐一解析

dashboard-metrics：KPI 卡片看板

核心指标看板，展示 4 个指标（Active users、Sessions、Revenue、Conversions）的两行卡片网格。每张卡片是一个并行 fragment，内部提供：

• 图表/表格视图切换（st.segmented_control，图标为:material/show_chart:/:material/table:）；
• popover 过滤器（Daily / 7-day MA 多选 + 时间范围）；
• 4 种图表渲染器：render_line_chart、render_area_chart、render_bar_chart（按周聚合提升可读性）、render_point_chart（散点 + 7 日均线虚线段）。

数据生成方面，generate_metric_data使用hashlib.sha256(metric_name)派生固定随机种子，保证同一指标每次生成的数据可复现，并模拟增长趋势、周末季节性与噪声（源码）。各指标的基准值与增长率集中配置在METRIC_CONFIG字典中，替换数据源时只需改这一个配置块。

dashboard-feature-usage：API 端点用量分析

按 API 分类（Users/Orders/Products/Analytics）探索端点用量，交互链完整：

• 分类用st.segmented_control选择；
• "Starter kits" 预设方案（Core CRUD、Search、Analytics、High Volume）通过st.pills一键批量选中端点（源码）；
• 时间聚合支持 Raw / 7-day / 28-day 滚动均值（ROLLING_OPTIONS）；
• "Normalize" 开关把请求数归一化为每日占比（normalize_data按日求和后相除）；
• "Latest numbers" 用st.metric展示每个端点最新值与 28 天增量；
• 左侧过滤器列 + 右侧图表列用st.columns([1, 2])布局。

该模板还示范了一个重要的性能技巧：折叠区条件渲染。"Raw data" 折叠区默认收起，借助on_change="rerun"读取raw_data_section.open状态，只有用户真正展开时才构建并下发 dataframe，避免每次重跑都计算并传输大数据帧（源码）。归一化开启时，还通过st.column_config.NumberColumn(format="percent")把请求列渲染成百分比。

dashboard-companies：公司排行榜与下钻

面向"客户采用度"分析的公司看板，核心是交互式 dataframe + 弹窗下钻：

• aggregate_companies按公司聚合出总 credits、活跃天数、日均值、sparkline 序列与增长分数（后半年减前半年的粗粒度趋势指标，见_calc_growth）；
• st.dataframe使用column_config精细配置每一列：LineChartColumn渲染 sparkline 趋势列，MultiselectColumn以彩色 chip 展示账户类型/区域/行业，NumberColumn定制数值格式（源码）；
• 排行榜支持on_select="rerun"+selection_mode="single-cell"，点击公司名列的单元格即触发@st.dialog弹窗，展示账户徽章（:blue-badge等）、三项指标与日用量/累计用量双图表（源码）。

顶部过滤器区提供排序模式（Top spenders / Top shrinkers / Top gainers）、时间窗口（All time / 28 天 / 7 天）与账户类型多选 pills。

dashboard-compute：资源消耗监控

计算资源（credits）监控看板，把"按维度拆分"抽象成可复用的dimension_metricfragment：传入 loader、维度列、选项列表与key_prefix，即可生成一张自带图表/表格切换、popover 过滤、折线/柱状切换、百分比归一化与时间范围过滤的卡片（源码）。

三个维度（账户类型、实例类型、区域）各有一个独立的@st.cache_data(ttl="1h")loader，按维度 key 缓存 2 年的日粒度数据；柱状图支持stack="normalize"的百分比堆叠模式。布局为两行：第一行两张卡片，第二行区域维度占满整行。

dashboard-seattle-weather：官方演示数据看板

基于 Altair 经典案例数据集vega_datasets.data("seattle_weather")的天气探索应用，加载函数用@st.cache_data(show_spinner="Loading weather data...")缓存。特性包括：

• 2015 vs 2014 六组st.metric（最高/最低温度、降水、风速），带年度差值的delta；
• 最常见的天气用 Material 图标 + 大写文案展示；
• st.pills多选年份实现"Compare different years"，不同年份按颜色分组叠加；
• Altair 图表矩阵：温度区间条形图（Y/Y2编码）、天气分布环形图（mark_arc）、月度降水柱状图、按月堆叠的天气占比，以及用st.line_chart的多年风速折线；
• 所有图表区块用st.container(border=True, height="stretch")等高管线布局。

完整实现见 dashboard-seattle-weather/streamlit_app.py。

dashboard-stock-peers：股票同侪分析

股票对比看板，内置约 100 个美股代码，默认选中 AAPL/MSFT/GOOGL/NVDA/AMZN/TSLA/META。亮点特性：

• st.multiselect绑定bind="query-params"，股票选择自动同步到 URL 查询参数（?stocks=AAPL&stocks=MSFT），看板可直接分享，无需手写st.query_params管道（源码）；
• accept_new_options=True允许输入自定义代码；
• 时间跨度从 1 个月到 20 年，用st.pills选择；
• 归一化处理：以每只股票首个非空值为基准（data.div(data.bfill().iloc[0])），规避新上市股票首行为 NaN 的问题（源码）；
• "Best/Worst stock" 用归一化末值比较，输出涨跌幅 delta；
• 每只股票单独生成"个股 vs 同侪均值"（剔除自身）折线与差值面积图，红色与灰色区分。

依赖要求

所有模板要求Python >= 3.10，公共依赖如下：

• streamlit
• altair>=5.5.0
• pandas>=2.2.3
• numpy>=1.26.0（大多数模板）

此外，dashboard-seattle-weather额外依赖vega_datasets（演示数据），dashboard-stock-peers额外依赖yfinance>=0.2.55（行情数据）。各模板的完整依赖声明位于对应目录的pyproject.toml中。

结语：把模板当"规范样本"使用

这 6 个模板不仅是可运行的应用，更是一份可复制的"看板工程规范"：统一使用layout="wide"与 Material 图标、共享同一份filter_by_time_range语义、用@st.fragment(parallel=True)+st.skeleton把卡片性能做到极致、用@st.cache_data(ttl=...)让缓存新鲜且有界、用st.popover收纳过滤器、用st.dialog与交互式 dataframe 实现下钻。无论你是要快速交付一个内部指标看板，还是为团队沉淀一套看板开发约定，都可以直接以这些模板为起点——复制目录、替换generate_*_data()为真实数据源、按需调整METRIC_CONFIG之类的配置块，即可完成从演示到生产的跃迁。

【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit