Streamlit系列写到第九篇我越来越觉得有个现象很典型不少人把精力都花在st.plotly_chart、st.dataframe这些显眼组件上对st.text_input、st.number_input这类最基础的输入组件反而抱着不就是个输入框嘛的态度。真开始做项目十个里面有八个会卡在同一个问题上——用户输入的数据和我预期的不一样。这个不一样可能体现在类型上字符串、整数、日期对象、体现在状态上输入完一点按钮就被重置、体现在范围上用户填了个超出业务允许的值甚至体现在报错上前端明明显示正常后端却冒出一句Failed to deserialize the JSON body。这些坑我基本都踩过一遍有些还反复踩。这篇就把 Streamlit 的 input 类 widgets 一次性讲透从文本、数字、日期到颜色、文件上传再深入到背后的 rerun 机制和状态管理适合正在做 Streamlit 应用、尤其是想把原型做成真正可用工具的人。1. 输入类Widgets的定位为什么说这是Streamlit表单的灵魂1.1 从只读报表到交互应用输入组件补上了最后一块短板如果只用st.line_chart、st.bar_chart和st.dataframe你确实能做一个很漂亮的看板但它本质上是只读的。用户想看三月份华东区的销售数据你只能再写死一个页面或者让数据团队手动改配置。输入类组件的价值就是让你用最少代码把这种静态看板变成可操作的业务工具。比如一个销售数据筛选器核心逻辑其实就是三行import streamlit as st import pandas as pd df pd.read_csv(sales.csv) region st.text_input(输入区域) if region: df df[df[区域] region] st.dataframe(df)用户输入一个区域名整个页面就跟着变。没有表单提交没有 JavaScript 事件监听没有请求转发。这背后是 Streamlit 的脚本执行模型在帮你兜底但前提是你得理解输入组件到底返回了什么、什么时候触发重新计算。1.2 Streamlit的input组件和HTML里那个input标签不是一回事很多做过前端的人第一次用st.text_input会下意识找怎么监听事件怎么获取值然后发现完全不用。普通网页里input只是个 UI 标签想拿到值得用document.querySelector配合事件回调自己管理状态Streamlit 里的st.text_input是一个 Python 函数它直接把当前输入框的值作为返回值交给你。换句话说Streamlit 把输入这件事抽象成了 Python 变量赋值。用户每次输入前端组件状态变化会通过 WebSocket 同步到后端脚本重新执行时这个函数就返回最新的值。这个概念极度简化了开发但也带来一个副作用你很容易忘记我在 Python 里拿到的已经是解析后的对象从而对类型和边界不敏感。1.3 理解每次交互都是全脚本重跑后面所有坑都好办了Streamlit 最反直觉、也最核心的机制是 rerun用户改了任何一个输入组件整个 Python 脚本会从第一行重新执行一遍。这不是只更新某个组件而是从头跑。我之前在群里看到有人写这样的代码st.text_input(用户名, value默认值)用户把输入框改成张三然后点了旁边的按钮触发 rerun结果输入框立刻又变回默认值。原因很简单每次 rerun 都会重新执行st.text_input(用户名, value默认值)value被重新赋值为默认值用户输入的内容被覆盖了。想通这一点后面所有关于value、key、session_state的用法都能串起来。2. text_input与text_area文本输入组件的正确打开方式2.1 基础用法与返回值一个最简单的搜索框文本输入是使用频率最高的输入类型没有之一。最基础的写法import streamlit as st keyword st.text_input(搜索关键词, placeholder输入城市名) if keyword: st.write(f你搜索的是{keyword})有一个细节我建议新手记下来st.text_input的返回值永远是字符串没输入时返回空字符串。所以if keyword这个判断天然能跳过空输入不需要额外判空。这里返回类型要特别注意如果你觉得好像是 Optional[str]那就错了它不会返回None除非你显式在session_state里塞了None。placeholder参数是输入框的灰色提示文字它不属于实际值所以不会污染你的业务逻辑。这是我在实际项目中比较推荐的做法尽量避免把提示信息和真实输入混在一起。2.2 value参数的真实含义为什么你的输入框总是被重置这是文本输入组件里最容易踩的坑而且踩的人特别多。很多人想给输入框一个默认值于是这样写st.text_input(项目名称, value未命名项目)用户把未命名项目改成客户A项目然后点击按钮提交页面 rerun输入框又被重置成未命名项目。用户体验相当糟糕。原因就是 1.3 节说的每次 rerun 都重新执行这一行value未命名项目这个常量被再次写进组件。正确的做法有三种不传value让 Streamlit 自己维护输入状态st.text_input(项目名称)传key通过session_state读写st.text_input(项目名称, keyproject_name) if st.button(保存): st.session_state[project_name] 已保存 st.session_state[project_name]如果确实需要动态默认值应该从session_state里读而不是写死default_name st.session_state.get(project_name, 未命名项目) st.text_input(项目名称, valuedefault_name)我的建议是能用key就用key。这不仅是给输入框起个名字更是给 Streamlit 一个状态锚点让组件状态在 rerun 之间稳定保留。2.3 密码框、最大长度、placeholder等实用参数st.text_input的参数不算多但每个都有实际场景我把常用的整理成了表格参数作用使用建议typepassword输入内容显示为圆点登录页、密钥录入max_chars20限制最大字符数超出无法继续输入手机号、优惠码placeholder灰色提示文字引导用户输入格式help鼠标悬停时的提示信息解释字段含义autocomplete控制浏览器自动填充邮箱、用户名等label_visibilitycollapsed隐藏顶部标签界面更紧凑举个例子要收集一个登录账号account st.text_input( 登录账号, max_chars30, placeholder手机号或邮箱, help仅支持手机号或邮箱, typedefault, )autocomplete这个参数容易被人忽略。如果你做的是登录表单建议显式传autocompleteusernameStreamlit 2.x 之后对自动填充的支持更完善能避免浏览器瞎填导致数据不对。2.4 用户一输入就触发动作on_change回调的玩法Streamlit 的on_change回调是我用得越来越多的东西。默认情况下输入值变化会触发 rerun你在脚本下方用返回变量做判断也能实现响应变化但有些动作你希望它发生在一个明确的时间点而不是每次 rerun 都顺带跑一遍。官网有个经典例子是记录修改次数def on_text_change(): st.session_state[change_count] st.session_state.get(change_count, 0) 1 text st.text_input(输入内容, keytext, on_changeon_text_change) st.write(修改次数, st.session_state.get(change_count, 0))注意点回调函数里不能直接使用st.write等输出函数否则会打乱渲染流程它适合做状态更新、日志记录、数据预计算。回调本质上还是在 rerun 流程中执行的只不过是因为该组件变化而触发而不是脚本执行到那里才触发。st.text_area的用法和text_input基本一致区别在于多行和高度控制bio st.text_area( 个人简介, height150, placeholder介绍一下你自己, max_chars500, )文本类组件本身没有格式校验能力比如只允许数字和字母这种限制留给后面第 3 章和第 7 章讲具体实现。3. number_input数值输入的精度、范围与类型解析3.1 min/max/step参数是怎么限制用户输入的数值输入用st.number_input最常见的场景是年龄、价格、数量age st.number_input( 年龄, min_value0, max_value120, value18, step1, )min_value和max_value是硬边界step是点击上下箭头时每次增加/减少的量。有一个容易被忽略的行为如果你直接输入一个超出边界的数字Streamlit 前端会提示你重新输入而不是自动截断。所以我在实际项目里不会把min_value/max_value当作唯一的校验手段后面入库前还会再判断一次。step参数还有个小细节如果你不传value组件默认取min_value如果不传min_value默认值是0这时候valuemin字符串表示取最小值。很多人在初始化时写成value0反而覆盖了 min 的语义。3.2 int和float的返回逻辑什么时候会翻车st.number_input的返回值不是固定类型它的规则是当min_value、max_value、value、step这四个参数全是整数时返回int只要有一个涉及小数返回值就变成float。这个逻辑有点像 C# 里的int.TryParse——能按整数解析就给你整数附带小数位就给你浮点数。问题出在下面这种写法price st.number_input(价格, min_value0.0, value1.0, step0.1)你拿着price去做range(price)或者作为列表索引立刻报TypeError。所以拿数值之前先确认你是要整数还是小数price st.number_input(价格, min_value0.0, value1.0, step0.1) if isinstance(price, float): # 走浮点逻辑 pass如果需要整数但组件配置里不小心混入了小数可以在业务侧int(price)转换但要先判断能不能转防止用户输入了1.9之后被粗暴截断成1。3.3 浮点数显示与format参数的组合很多人以为format参数能改变数值本身其实它只控制显示格式。看个例子score st.number_input(评分, min_value0.0, max_value5.0, value4.5, step0.1, format%.2f)界面会显示4.50但 Python 拿到的score依然是浮点数4.5。格式化显示的意义在于避免用户看到一长串浮点尾巴比如4.5000000001。这里要提醒一个经典浮点数问题如果step0.1用户连续点击很多次累积的浮点误差可能会让值变成4.299999999999。我在项目里处理价格、评分这类数字时会在后端加上round(value, 2)或者直接转成Decimal再计算不要在浮点上直接做金额加减。3.4 没有直接过滤器时如何实现只允许数字和字母st.number_input只能输入数字但实际业务里经常有优惠码/编号只允许数字和字母这种需求而st.text_input没有pattern参数怎么处理方案是on_change回调 正则 session_state纠正。当用户输入非法字符时我们直接把他输入框里的内容改回合法值并给一个提示import re import streamlit as st def validate_code(): val st.session_state.get(code, ) if val and not re.fullmatch(r[A-Za-z0-9]*, val): st.session_state[code] re.sub(r[^A-Za-z0-9], , val) st.warning(编码只能包含数字和字母已自动清理非法字符) code st.text_input(优惠码, keycode, on_changevalidate_code)这段代码的核心是st.session_state[code] re.sub(...)它能在一次 rerun 中直接修改组件的当前状态把非法字符去掉。这个技巧也适用于其他格式校验比如手机号、邮箱的前置清洗。4. date_input与time_input日期时间组件的类型与边界问题4.1 返回值是date/time而不是datetime这个区别很关键日期类组件有两个st.date_input和st.time_input。先说最容易出错的地方——它们的返回值类型。import datetime import streamlit as st d st.date_input(选择日期) t st.time_input(选择时间) st.write(type(d)) # class datetime.date st.write(type(t)) # class datetime.time注意d是datetime.date不是datetime.datetime。如果你拿d和datetime.datetime.now()比较大小会直接报错因为两者不是同一种类型。我见过很多新手卡在这里。解决办法是用datetime.datetime.combine把日期和时间拼起来dt datetime.datetime.combine(d, t) st.write(dt)或者反过来从datetime里取.date()。这个类型转换在做数据入库、时间范围筛选时尤其重要SQL 和 pandas 对 date 和 datetime 的处理有细微差别提前统一能省很多事。4.2 单选与范围选择value参数传元组的特殊行为st.date_input有一个隐藏能力当value传入一个包含两个日期的元组/列表时组件会自动变成日期范围选择器返回值为一个元组里面是两个日期。date_range st.date_input( 选择统计区间, value(datetime.date(2024, 1, 1), datetime.date(2024, 12, 31)), ) if isinstance(date_range, tuple): start_date, end_date date_range st.write(f开始{start_date}结束{end_date})这里建议用isinstance(date_range, tuple)判断而不是直接解包。因为如果用户只选了一个日期返回值就只是一个date对象直接start_date, end_date date_range会报 cannot unpack non-iterable date object。尤其有些浏览器交互下用户可能先选一个日期导致返回单值这种边界要兜住。另外日期范围选择器在用户清空某个日期时返回值可能变成空元组或空列表处理时先判断长度再解包更稳妥。4.3 min/max_value限制与strftime格式化输出st.date_input支持min_value和max_value这个在实际业务里非常实用。比如限制只能选过去一年内的日期today datetime.date.today() d st.date_input( 查询日期, min_valuetoday - datetime.timedelta(days365), max_valuetoday, )它的意义不止是界面友好更重要的是防止用户选出一个完全脱离业务范围的日期从而减少后面数据查询时的异常分支。st.time_input的value参数可以直接传now它会自动取当前时间作为默认值t st.time_input(提醒时间, valuenow, stepdatetime.timedelta(minutes15))step控制下拉列表和箭头调节的粒度传timedelta对象。注意它同样不是硬校验用户还是可以手动输入任意时间所以业务侧要自己判断。日期时间在输出到前端展示或存数据库时我一般统一成字符串date_str d.strftime(%Y-%m-%d) time_str t.strftime(%H:%M)如果你做的是跨时区应用还有一个隐藏风险Streamlit 服务器进程跑在 UTC 时区而用户浏览器可能在东八区。st.time_input返回的是本地时间如果你的业务时间锚定在服务器时间两者可能会有偏差。我建议全程用datetime.timezone显式管理不要依赖系统默认时区。5. color_picker与file_uploader容易被低估的两个组件5.1 color_pickerHEX颜色串在前端图表中的流转st.color_picker的返回值是 HEX 格式的字符串比如#FF4B4B。它本身很简单但特别实用因为你可以直接把颜色值喂给绘图库和 CSS 样式。import plotly.express as px import streamlit as st color st.color_picker(选择主题色, value#FF4B4B) fig px.bar(x[A, B, C], y[1, 2, 3], color_discrete_sequence[color]) st.plotly_chart(fig)一个常见需求是用户选颜色整张卡片的边框跟着变。可以用st.markdown内联 CSS 实现st.markdown( f div styleborder: 3px solid {color}; padding: 16px; border-radius: 8px; h4你的主题色是 {color}/h4 /div , unsafe_allow_htmlTrue, )注意一点st.color_picker返回值永远是合法的#RRGGBB格式不需要额外做格式校验但如果你要把它存进数据库建议统一成小写避免不同客户端产生的#ff4b4b和#FF4B4B被判为不同值。5.2 file_uploader的读取细节BytesIO、seek与编码st.file_uploader返回的是一个UploadedFile对象本质上是BytesIO的子类。很多第一次用的人会困惑拿到的到底是什么其实你完全可以把它当内存文件对象用。uploaded st.file_uploader(上传TXT文件, type[txt]) if uploaded: content uploaded.getvalue().decode(utf-8, errorsignore) st.write(content[:1000])getvalue()是BytesIO里最不容易出错的方法一次性能拿到所有字节。相比之下read()有个经典坑读完一次后文件指针移到末尾再read()就是b。如果你后续还想读必须执行uploaded.seek(0)重置指针。文本编码也是一个高频坑。用户上传的 CSV 经常是 Excel 导出的 GBK 编码直接用utf-8解码会乱码。我习惯这样兜底raw uploaded.getvalue() for encoding in [utf-8, gbk, latin-1]: try: content raw.decode(encoding) break except UnicodeDecodeError: continue5.3 多文件上传、类型限制和大文件内存管理设置accept_multiple_filesTrue后返回值变成列表。这个很好理解但要注意判断空列表files st.file_uploader(批量上传, type[csv], accept_multiple_filesTrue) for f in files: st.write(f.name, f.size)type参数限制的是文件扩展名但它本质上是前端提示不能作为安全边界。一个用户完全可以上传一个内容为可执行脚本但命名为.txt的文件所以你后端处理时还需要自己检查文件内容或大小。Streamlit 的file_uploader没有内置max_size参数大文件上传会直接读进内存。对于几十 MB 的日志文件还好如果是几百 MB 的 CSV 就要小心内存占用。我处理大文件时会先判断uploaded.size超过阈值就用uploaded.read(1024*1024)分块读取或者把内容先落盘到临时文件再后续处理。注意uploaded.size是文件字节数单位是整数字节不是字符串。6. 输入背后的数据链路rerun、序列化与状态保持6.1 一次按键触发的完整链路浏览器到Python再到浏览器Streamlit 的架构有点像游戏引擎里的 Input System输入事件不是直接修改 UI而是统一进入状态系统下一帧也就是下一次 rerun统一起作用。整个链路是用户按键/点击 → 浏览器端组件状态变化 → 通过 WebSocket 把状态变化序列化后发给 Python 进程 → Streamlit 服务器识别出某个组件值变了 → 重新执行脚本 → 生成新的前端渲染指令 → 通过 WebSocket 返回浏览器 → 页面更新。这个机制的好处是你不需要写事件驱动代码坏处是你写的每个 Python 变量在每次 rerun 后都可能被重新赋值。理解这条链路后你就能解释很多诡异现象为什么输入框内容会被重置因为脚本执行到那一步时给它赋了新值为什么组件参数一改用户输入就丢了因为组件 ID 变了Streamlit 把新组件当成另一个组件旧状态自然不存在。6.2 JSON反序列化报错Failed to deserialize这类问题怎么排查这是 Streamlit 社区里频繁出现的一类报错常见版本有Failed to deserialize the JSON body into the target type: input: missing fieldMalformed inputUnexpected end of JSON input这些报错本质上是前端 JavaScript 与后端 Python 之间的协议数据不一致。也就是前端发送给后端的 JSON body 里缺少后端期望的字段或者字段格式不对。最常见的原因不是你的业务代码而是浏览器缓存了旧版 Streamlit 前端资源而后端已经升级到新版本两者版本不匹配。排查顺序我建议按这个来硬刷新页面Windows 下按CtrlShiftRMac 下按CmdShiftR让浏览器重新拉取静态资源。如果还在报错开一个隐私窗口或换一个浏览器测试排除缓存和扩展插件干扰。确认前端访问的端口是否对应正确的后端进程。经常有人旧进程没关新进程起不来路由到了旧端口。查看后端进程日志确认是否正常启动没有 import 错误。如果页面本身是 Flask/FastAPI 挂载的 Streamlit检查反向代理的缓存策略静态资源要不要加no-cache。我自己的经验是90% 的这类报错靠一步硬刷新就能解决。剩下 10% 是浏览器插件比如某些翻译插件、脚本插件改动了页面 DOM导致组件数据缺失。如果换隐私窗口后正常基本就是插件问题。6.3 用key做状态锚点避免组件状态丢失Streamlit 会给每个组件自动生成一个 widget ID生成依据是组件类型和参数。这带来一个隐藏问题如果你在代码里把组件的label或help等参数改了widget ID 跟着变组件状态可能被重置用户之前输入的内容就没了。解决办法是显式传递key参数给组件一个稳定标识st.text_input(项目名称, keyproject_name)之后你就可以在session_state里直接读写这个 keyif st.button(清空): st.session_state[project_name] 还有一个和key相关的经典报错DuplicateWidgetID意思是两个同类型组件用了同一个 key。Streamlit 会直接抛异常这是好事——它帮你避免了状态相互覆盖。排查方法就是搜索整个项目里这个 key 出现了几次。6.4 前端校验和后端校验要配合不能只靠max_charsmax_chars、max_value、min_value、typepassword这些参数都只是前端的体验和引导不能当作安全边界。为什么因为这些限制都在浏览器端执行用户完全可以绕过浏览器直接构造请求发送给后端或者用自动化工具伪造 WebSocket 消息。真正的校验必须发生在 Python 侧。一个简单有效的写法是收集所有校验错误统一在最后展示errors [] if not name.strip(): errors.append(姓名不能为空) if len(name) 30: errors.append(姓名长度不能超过30) if age 18: errors.append(未满18岁不能注册) if errors: for err in errors: st.error(err) else: # 继续业务逻辑 pass这也是我喜欢st.form的原因表单里的组件在点击提交按钮之前不会触发整体 rerun用户可以把所有字段填完再一次性提交后端拿到完整数据后统一校验。前端的即时约束负责提前拦截明显错误后端校验负责兜住所有边界两者配合才稳。如果你写的是自定义组件使用st.components.v1时也会遇到类似问题前端组件通过setComponentValue把 JSON 数据发给后端字段拼错一个就报missing field。写这类组件时建议先定义好一份 TypeScript 接口和后端 Python 数据类一一对应从源头避免字段名漂移。7. 实战一个带输入校验的个人资料卡应用7.1 需求拆解需要哪些输入组件理论讲了这么多最后用一个完整例子把 input 类组件串起来。需求是做一个个人资料卡生成器用户录入姓名、年龄、邮箱、生日、个人简介上传头像选一个主题色点击按钮后生成一张卡片展示。组件选型其实非常简单字段组件关键参数姓名st.text_input必填长度限制年龄st.number_input18-100整数邮箱st.text_input正则校验生日st.date_input限定历史日期个人简介st.text_area最大500字头像st.file_uploader仅图片主题色st.color_picker默认红色7.2 校验逻辑放在哪一层on_change回调 vs 提交按钮我选择用st.form包裹所有输入组件而不是让每个组件都有自己的on_change回调。原因是这个场景需要整体提交用户可能在填一半的时候年龄还没填姓名还是空的如果每个字段一变就 rerun提示错误会很烦人。用st.form后表单内组件的每次变化不会触发系统级 rerun只有点击st.form_submit_button才会统一提交并触发脚本执行。这非常适合填写 → 校验 → 展示的流程。注意两组限制st.form_submit_button必须放在st.form内部一个表单里只能有一个st.form_submit_button。如果你需要保存和取消两个按钮用st.columns布局做两个st.form_submit_button分别判断 label 即可。7.3 完整代码与运行效果import datetime import re import streamlit as st st.set_page_config(page_title个人资料卡生成器, page_icon:material/badge:) st.title(个人资料卡生成器) with st.form(profile_form): col1, col2 st.columns(2) with col1: name st.text_input(姓名, placeholder请输入姓名, max_chars20) age st.number_input(年龄, min_value1, max_value120, value18, step1) email st.text_input(Email, placeholderexamplexx.com) with col2: birthday st.date_input( 生日, min_valuedatetime.date(1900, 1, 1), max_valuedatetime.date.today(), ) accent st.color_picker(主题色, value#FF4B4B) avatar st.file_uploader(上传头像, type[png, jpg, jpeg]) bio st.text_area(个人简介, height120, max_chars500, placeholder介绍一下自己) submitted st.form_submit_button(生成资料卡) if submitted: errors [] if not name.strip(): errors.append(姓名不能为空) if not re.fullmatch(r[^\s][^\s]\.[^\s], email.strip()): errors.append(邮箱格式不正确) if age 18: errors.append(未满18岁暂不支持注册) if avatar is not None and avatar.size 5 * 1024 * 1024: errors.append(头像文件不能超过5MB) if errors: for err in errors: st.error(err) else: col_a, col_b st.columns([1, 2]) with col_a: if avatar: st.image(avatar, width160, captionname) else: st.markdown( div stylewidth:160px;height:160px;border-radius:50%; fbackground:{accent};display:flex;align-items:center; justify-content:center;color:#fff;font-size:48px; f{name[0] if name else ?}/div, unsafe_allow_htmlTrue, ) with col_b: st.markdown( f div styleborder-left: 6px solid {accent}; padding: 12px 16px; background: #f8f9fa; border-radius: 8px; h3{name}/h3 pstrong年龄/strong{age} 岁/p pstrong邮箱/strong{email}/p pstrong生日/strong{birthday.strftime(%Y-%m-%d)}/p pstrong简介/strong{bio or 暂无简介}/p /div , unsafe_allow_htmlTrue, )几点说明头像文件用avatar.size 5 * 1024 * 1024做 5MB 大小限制因为file_uploader没有内置大小限制。st.date_input的返回值是datetime.date通过strftime(%Y-%m-%d)转成字符串展示。如果用户没上传头像我生成了一个首字母圆形占位背景用用户选的主题色。校验错误统一展示不打断输入流程用户可以一次改完再次提交。实际运行你会发现st.form的体验跟普通表单非常像点输入框、改内容、页面不闪动直到点生成资料卡才整体 rerun。最后再分享一个实用技巧输入类组件多了以后我习惯把所有值统一收集到一个字典里而不是在脚本各处散落变量def get_form_data(): return { name: st.session_state.get(name, ), age: st.session_state.get(age, 18), email: st.session_state.get(email, ), birthday: st.session_state.get(birthday, datetime.date.today()), }这样在做后续逻辑、数据入库、单元测试时都能少踩很多这个变量到底从哪来的坑。Streamlit 的 input widgets 单独看每个都简单但它们组合起来后真正的难点其实是状态管理、类型转换和校验边界。把这几个点想明白一个能交付给业务方的工具型应用基本就成型了。