用途:Streamlit 每次交互都会自上而下重跑脚本,普通变量随之重置;st.session_state 用于在重跑之间持久保存数据,适合保存计数、用户选择、过滤器等状态,并处理组件状态与回调。
主要能力与用法:会话状态是类似字典的对象,支持属性与方括号写法。推荐初始化:st.session_state.setdefault("count", 0);也可用 if "count" not in st.session_state 判断后赋值。读取当前值、更新(如 st.session_state.count += 1 或 st.session_state["count"] = 5)、删除(del st.session_state.count)均可。访问未初始化键会抛出 KeyError,安全读取用 st.session_state.get("key", default)。
带 key 参数的组件会自动与会话状态同步:st.text_input("Name", key="user_name") 后,st.session_state.user_name 与返回值一致。回调在脚本重跑前执行,可用 on_change 或 on_click 配合 args、kwargs 立即改状态;在组件自身回调中应通过 st.session_state.key 读取其值。建议在应用顶部集中初始化所有状态。
多页面下组件不是跨页面有状态的,切换页面会重置其值;共享数据应使用会话状态变量(而非组件 key)。共享组件可放在入口文件中导航运行之前,例如在 st.sidebar 中写 st.session_state.theme = st.selectbox(...),再执行 nav = st.navigation(pages) 与 nav.run()。
常见错误:在导入模块中使用模块级可变对象(如 cache = {})会跨重跑乃至跨所有用户共享,应改用会话状态保存每用户数据;组件渲染后不能再给它赋值,否则抛 StreamlitAPIException;不要同时设置 value 参数和会话状态(如 value="Bob" 与 setdefault("name", "Alice") 并用),否则产生警告,只保留其一。
限制:会话状态按用户、按标签页隔离,每个浏览器标签页各自独立;属于临时数据,关闭标签页或服务器重启后丢失,不适合做持久化存储,永久数据需用数据库。