Streamlit 选择控件选型与实战指南：从 segmented_control 到 multiselect 的正确打开方式

Streamlit 选择控件选型与实战指南从 segmented_control 到 multiselect 的正确打开方式【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit选择控件是数据应用交互的核心但用哪个常常被直觉带偏曾经的st.radio(horizontalTrue)如今已被更现代的st.segmented_control取代而小选项集也不该被塞进下拉框。本文以 Streamlit 仓库中的开发者技能文档selection-widgets.md为主线梳理st.segmented_control、st.pills、st.selectbox、st.multiselect、st.toggle、st.checkbox与st.form的选型规则与实战写法并结合仓库源码解释wrap、accept_new_options、border等关键参数的底层行为。读完本文你将能针对任意场景快速选出最合适的控件并写出符合当前 Streamlit 最佳实践、可复制的代码。何时用哪种控件两条简单的决策规则Streamlit 的控件生态已经演进——很多旧写法如今已是反模式anti-pattern。判断标准其实只有两条需要所有选项同时可见25 个选项用st.segmented_control单选或st.pills多选选项很多、需要隐藏在下拉框中用st.selectbox单选或st.multiselect多选。控件适用场景st.segmented_control2–5 个选项、单选、全部可见st.pills2–5 个选项、多选、全部可见st.selectbox大量选项、单选、下拉框st.multiselect大量选项、多选、下拉框底层实现上st.pills与st.segmented_control都位于 button_group.py 的ButtonGroupMixin中共享同一套ButtonGroup原型与SelectionMode Literal[single, multi]类型只是渲染样式不同——这正是它们 API 高度一致都支持selection_mode、default、format_func、wrap等参数的原因。仓库测试 button_group_test.py 对二者统一做了 widget 序列化、稳定 ID、wrap行为等验证。Segmented control选项可见的单选控件当选项较少且需要单选时st.segmented_control是横向st.radio的现代替代品# 反模式横向 radio 已不推荐 status st.radio(Status, [Draft, Published], horizontalTrue) # 推荐分段控件外观更干净现代 status st.segmented_control(Status, [Draft, Published])分段控件把选项并排放在一条分段条里选中态通过整段高亮表达视觉上比横向单选按钮更紧凑、更现代。需要说明的是本文并不否定st.radio本身——在垂直布局下st.radio(..., horizontalFalse)默认即垂直依然是很好的选择尤其适合选项较多、需要纵向排布的场景。segmented_control的参数与pills完全一致同源于ButtonGroupMixin包括selection_mode、default、required、format_func、key、help、on_change、disabled、label_visibility、width、wrap等默认selection_modesingle。Pills选项可见的多选控件当只有少量标签需要多选时st.pills比st.multiselect更直观selected st.pills( Tags, [Python, SQL, dbt, Streamlit], selection_modemulti )pills 以胶囊形式平铺所有选项点击即切换选中用户无需打开下拉框就能看清全部可选内容。它还能配合label_visibilitycollapsed模拟示例点击类的小部件——不显示标签、只展示几个可点击的示例项st.pills( Examples, [Show me sales data, Top customers], label_visibilitycollapsed )这种写法很适合在页面顶部提供一键示例入口用户点一下某个示例应用即可根据选中的示例值渲染对应的展示内容。对于小选项集pills 在视觉表现与操作便捷度上都优于st.multiselect。Selectbox大量选项的单选下拉框当候选数量很多几十甚至上百个国家、城市、SKU时平铺所有选项既不现实也不美观此时应使用下拉框country st.selectbox( Select a country, [USA, UK, Canada, Germany, France, ...] )下拉框把选项折叠进一个可搜索的输入区域长列表的滚动与检索成本远低于 radio/pills。这正是文档强调的Dropdowns scale better than radio/pills for long lists——即下拉框在长列表上比 radio/pills 更具可扩展性。Multiselect大量选项的多选下拉框多选且选项较多时st.multiselect是唯一合理的选择countries st.multiselect( Select countries, [USA, UK, Canada, Germany, France, ...] )从源码 multiselect.py 可以看到st.multiselect还支持max_selections限制最多可选数量、placeholder、filter_modefuzzy模糊匹配 /contains包含 /prefix前缀 /None关闭过滤、select_all是否显示全选等增强参数。特别是filter_mode默认即为模糊匹配选项再多也能靠打字快速定位。让选项保持在单行wrap参数st.pills、st.segmented_control和st.multiselect都接受wrap参数控制选中项/选项是否换行。默认值None的行为取决于控件所处的布局直接放在水平容器中或直接放进某一列st.columns时默认保持单行放不下则横向滚动嵌套在表单form、expander、垂直st.container等布局容器中时默认允许换行传wrapFalse始终强制单行传wrapTrue始终允许换行。# 直接放在列中默认保持单行 col1, col2 st.columns(2) with col1: tags st.pills(Tags, [Python, SQL, dbt], selection_modemulti) # 嵌套在表单中默认会换行除非显式关闭 with st.form(filters): tags st.pills( Tags, [Python, SQL, dbt], selection_modemulti, wrapFalse ) st.form_submit_button(Apply)源码层面有一个值得注意的实现细节在 button_group.py 的_build_proto中wrap被明确标注为layout-only仅影响布局并有意排除在元素 ID 计算之外——也就是说切换wrap值不会导致控件状态被重置。这保证了你在不同布局间调整换行策略时用户已选中的值不会丢失。Toggle 与 Checkbox一个管设置一个管表单st.toggle与st.checkbox都是布尔控件但语义场景不同st.toggle用于触发应用变化的设置项如深色模式、显示高级选项等即时生效的开关st.checkbox用于表单内的确认项如同意条款配合提交按钮统一生效。# 推荐应用设置用 Toggle dark_mode st.toggle(Dark mode) show_advanced st.toggle(Show advanced options) # 推荐表单确认用 Checkbox with st.form(signup): agree st.checkbox(I agree to the terms) st.form_submit_button(Sign up)从 checkbox.py 的实现看st.toggle与st.checkbox共享同一底层状态管理机制但st.toggle额外支持on_change的rerun/ignore/ 回调函数三种响应模式且同样支持width、wrap、bindquery-params等新参数——它更贴近即时交互型设置的定位而 checkbox 更多承担传统表单字段角色。表单边框短表单去边框长表单留边框st.form默认带边框。对于内联的短表单一行输入 一个按钮去掉边框能让页面更清爽对于字段较多、需要视觉分组的表单则应保留边框以明确这些控件属于同一提交单元。# 内联短表单去掉边框更干净 with st.form(keyadd_item, borderFalse): with st.container(horizontalTrue, vertical_alignmentbottom): st.text_input(New item, label_visibilitycollapsed, placeholderAdd item) st.form_submit_button(Add, icon:material/add:) # 长表单保留边框强化视觉分组 with st.form(signup): st.text_input(Name) st.text_input(Email) st.selectbox(Role, [Admin, User]) st.form_submit_button(Submit)注意 form.py 中st.form的完整签名form(key, clear_on_submitFalse, *, enter_to_submitTrue, borderTrue, widthstretch, heightcontent)。其中border默认True源码 docstring 特别提醒——去掉边框可能会让用户困惑因为表单内控件要点击提交按钮才生效只有在已有其他边框如 expander或表单本身很小如只有一个输入框加一个按钮时才建议borderFalse。此外表单内只能有一个提交按钮st.form_submit_button且st.button、st.download_button不能放进表单。允许用户自定义选项accept_new_optionsst.selectbox与st.multiselect支持accept_new_optionsTrue让用户在预设选项之外自行输入新值# 股票代码多选预设 自定义输入 tickers st.multiselect( Stock tickers, options[AAPL, MSFT, GOOGL, NVDA], default[AAPL], accept_new_optionsTrue, placeholderChoose stocks or type your own, ) # 国家单选同样支持 country st.selectbox( Country, options[USA, UK, Canada], accept_new_optionsTrue, placeholderSelect or type a country, )从 multiselect.py 的实现细节看accept_new_options有几点值得注意用户新增的条目会以字符串形式出现在返回值中但不会被追加进下拉菜单的options列表匹配采用大小写不敏感逻辑如果用户输入的内容与某个已有选项大小写不敏感地相同则直接命中已有选项不会新增重复项max_selections限制仍然生效自定义项同样计入数量上限placeholder会根据配置自动变化accept_new_optionsTrue且有选项时显示 Choose or add options无选项时显示 Add optionsfilter_modeNone关闭输入过滤与accept_new_optionsTrue互不兼容。对于预设 自由输入混合需求的场景标签、股票代码、地名等这是比纯st.text_input更完整的交互方案。结语一份选型速查综合本文选择控件的决策路径可以浓缩为单选 少量选项≤5 且需全部可见→st.segmented_control垂直排布需求大时保留st.radio多选 少量选项≤5 且需全部可见→st.pills单选 大量选项→st.selectbox多选 大量选项→st.multiselect布尔开关应用级即时设置用st.toggle表单内确认项用st.checkbox需要用户输入预设之外的选项→st.selectbox/st.multiselect加accept_new_optionsTrue布局细节用wrap控制选项是否换行注意嵌套容器会改变默认行为短内联表单用borderFalse去边框。想深入了解实现细节可以继续阅读仓库中的源码与测试button_group.pypills / segmented_control、multiselect.py、selectbox.py、checkbox.pytoggle、form.py以及对应行为验证 button_group_test.py。本文的选型建议同样收录在仓库的 Agent 技能文档 selection-widgets.md 中供开发时随时查阅。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考