文章目录
- 一、服务端（SERVER）分组
-
- [1. `st.cache_data`：函数数据缓存装饰器](#1.
st.cache_data：函数数据缓存装饰器) - [2. `st.cache_resource`：全局资源缓存装饰器](#2.
st.cache_resource：全局资源缓存装饰器) - [3. `st.session_state`：会话状态存储对象](#3.
st.session_state：会话状态存储对象)
- [1. `st.cache_data`：函数数据缓存装饰器](#1.
- 二、浏览器端（BROWSER）分组
一、服务端（SERVER）分组
1. st.cache_data：函数数据缓存装饰器
功能说明
用于缓存计算结果数据 （DataFrame、接口返回数据、统计结果、模型推理输出等）的装饰器。
缓存数据会做拷贝隔离，每个会话读取独立副本；适合频繁查询、重复计算、不占用全局连接的数据。
核心参数
| 参数 | 说明 |
|---|---|
ttl |
缓存过期时长，单位秒/时间字符串，None永久有效 |
max_entries |
缓存最大存储条目数，超限自动淘汰最旧缓存 |
show_spinner |
缓存未命中时展示加载动画，可自定义提示文字 |
persist |
设置为disk可将缓存持久化到本地磁盘，重启应用不丢失 |
hash_funcs |
自定义类型哈希函数，用于无法自动哈希的自定义对象 |
常用内置方法
func.clear()：清空该函数指定参数的缓存 / 全部缓存st.cache_data.clear()：全局清空所有cache_data缓存
代码示例
python
import streamlit as st
# 缓存接口查询数据，持久化到磁盘，有效期1天
@st.cache_data(ttl="1d", persist="disk")
def load_online_data(url):
# 模拟接口请求
import pandas as pd
return pd.DataFrame({"value": [1,2,3]})
df = load_online_data("https://demo.api.com/data")2. st.cache_resource：全局资源缓存装饰器
功能说明
用于缓存全局共享资源（数据库连接、AI大模型、GPU推理实例、文件句柄等），资源对象全应用、多会话共享，不会生成数据拷贝，节省内存。
注意：缓存资源需要线程安全，多用户并发访问不会冲突。
核心参数
大部分参数与st.cache_data通用，独有：
validate：资源校验函数，每次读取缓存时执行，返回False则自动重新创建资源
常用内置方法
func.clear()：清空当前函数缓存st.cache_resource.clear()：全局清空所有资源缓存
代码示例
python
import streamlit as st
from transformers import pipeline
# 全局缓存NLP大模型，所有用户共用一个模型实例
@st.cache_resource
def load_sentiment_model():
model = pipeline("sentiment-analysis")
return model
model = load_sentiment_model()
result = model("我爱Streamlit")
st.write(result)cache_data 和 cache_resource 核心区别
| 特性 | st.cache_data |
st.cache_resource |
|---|---|---|
| 缓存内容 | 计算数据、表格、文本结果 | 模型、数据库连接、硬件资源 |
| 内存隔离 | 每个会话生成独立数据拷贝 | 全应用单例共享，无拷贝 |
| 使用场景 | 接口查询、数据清洗、统计计算 | 加载大模型、创建数据库连接 |
3. st.session_state：会话状态存储对象
功能说明
字典式会话存储，单独隔离每个浏览器标签页/用户会话，页面重运行、多页面跳转时数据不会丢失；用来存储控件值、临时变量、登录信息、计算中间结果。
基础操作语法
- 初始化（防止重复创建）
python
if "username" not in st.session_state:
st.session_state.username = ""- 读写取值（两种写法等效）
python
# 点语法
st.session_state.username = "小明"
# 字典下标语法
st.session_state["username"] = "小明"
# 读取
st.write(st.session_state.username)- 删除键值
python
# 删除单个key
del st.session_state.username
# 清空全部会话数据
for key in st.session_state.keys():
del st.session_state[key]关键特性
- 控件自动绑定 ：设置了
key参数的组件，值会自动同步到session_state
python
st.text_input("输入姓名", key="name")
st.write(st.session_state.name) # 自动读取输入框内容- 配合回调函数 ：按钮、输入框的
on_click/on_change回调可以修改会话状态 - 多页面互通 ：同一个会话下所有页面共享
session_state数据
限制
- 不建议直接修改已渲染控件对应的
key值，会抛出异常；初始化需在控件渲染前完成 - 部分特殊对象（未序列化的lambda、数据库游标）默认无法存储，可开启强制序列化配置
二、浏览器端（BROWSER）分组
1. st.context：浏览器上下文信息对象
功能说明
只读对象，用于读取当前用户浏览器请求的上下文信息，仅可读取、无法修改，适合鉴权、环境识别场景。
核心属性
st.context.cookies- 只读字典，获取浏览器发送的全部Cookie；
- 取值示例：
st.context.cookies["_ga"]。
st.context.headers- 只读请求头字典，键名大小写不敏感；
- 普通取值仅获取重复Header的最后一个值；
headers.get_all("key")：获取同一个键的全部Header值列表。
代码示例
python
import streamlit as st
# 读取全部Cookie
st.write("当前Cookie：", st.context.cookies)
# 读取指定Cookie
ga_cookie = st.context.cookies.get("_ga", "无")
st.write("GA Cookie值：", ga_cookie)
# 读取Host请求头
host = st.context.headers["host"]
st.write("访问域名：", host)
# 获取全部Accept编码头
all_accept = st.context.headers.get_all("accept-encoding")
st.write("全部编码头：", all_accept)2. st.query_params：URL查询参数管理对象
功能说明
字典式读写对象，用于读取、修改浏览器地址栏URL上的?key=value查询参数；修改后浏览器地址会自动同步更新，支持多页面传参、页面分享链接。
基础读写语法
python
import streamlit as st
# 读取参数（下标/属性两种写法）
id_val = st.query_params["id"]
name_val = st.query_params.name
# 修改参数，URL自动刷新
st.query_params.id = "1001"
st.query_params.name = "测试用户"处理重复Key（同一个参数出现多次 ?a=1&a=2）
- 直接取值只会拿到最后一个值；
.get_all(key)获取该键所有值组成列表；- 赋值列表可生成重复参数：
st.query_params.a = ["1", "2", "3"]
python
# 获取全部同名参数
all_a = st.query_params.get_all("a")
st.write(all_a)内置常用方法
-
.clear()：清空URL全部查询参数pythonst.query_params.clear() -
.from_dict(dict)：批量覆盖所有查询参数pythonst.query_params.from_dict({"page": "dashboard", "type": "data"}) -
.to_dict()：将当前参数转为标准字典返回
典型使用场景
- 页面间跳转传递ID、筛选条件；
- 生成带参数分享链接，打开页面自动读取参数加载对应数据；
- 保存筛选器状态到URL，刷新页面不会丢失筛选条件。