尧图网站建设 
Streamlitst.text_input实时更新live模式完全指南参数设计、行为语义与源码实现【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit本文基于 Streamlit 仓库中的产品规格文档 specs/2026-08-03-text-input-live-update/product-spec.md 编写并结合当前仓库中该功能已落地的后端实现lib/streamlit/elements/widgets/text_widgets.py、protobuf 定义proto/streamlit/proto/TextInput.proto与前端组件frontend/lib/src/components/widgets/TextInput/TextInput.tsx进行交叉印证。st.text_input的live参数为 Streamlit 应用带来了边输入边更新的能力用户打字停顿片刻后自动触发重跑无需按下回车或离开输入框。本文是这份规格文档的完整解读涵盖参数设计动机、bool | str值语义、与st.form/on_change/validate/bindquery-params等既有功能的交互边界、11 个关键边界情况以及对应的仓库源码实现细节。读完本文你将能正确选择liveTrue、live300ms与live0ms规避高频重跑、IME 组合输入、焦点丢失等陷阱并用st.fragment写出高性能的实时搜索界面。一、为什么需要live问题背景与使用场景传统上st.text_input只在以下三种时刻触发重跑用户按下Enter、离开输入框blur、或点击typesearch输入框的清除按钮。这意味着用户输入过程中页面完全静止必须额外操作才能看到结果与 Google 搜索框、IDE 自动补全等即时响应体验存在明显差距对应 GitHub Issue #4553该 issue 编号来自规格文档记录。规格文档归纳了三个典型诉求实时搜索 / 自动补全用户输入时即时过滤结果无需按 Enter 或 Tab。规格中的期望行为是query st.text_input(Search products, typesearch, liveTrue) filtered [p for p in products if query.lower() in p.lower()] st.write(filtered)实时校验边输入边给出反馈例如用户名已被占用密码强度不足不必等到提交表单才提示。实时格式化预览边输入边渲染 Markdown、LaTeX 或代码高亮效果。既有的三种变通方案及其局限变通方案局限性streamlit-keyup第三方组件需要额外安装和信任第三方依赖非 Streamlit 内置不会自动跟随原生 widget 的主题与样式自研 Custom Component开发与维护成本高按 Enter 再搜索交互体验差不符合搜索类界面的直觉规格文档特别指出第三方组件 blackary/streamlit-keyup 以 200 Star 证明了这一需求的强度其 API 为value st_keyup(Search)每次按键更新与value st_keyup(Search, debounce500)500ms 防抖。这正是live参数要内建到原生 widget 中的能力。为什么默认延迟是 250ms规格文档给出了一个数据依据大规模打字研究Dhakal et al., CHI 2018168,960 名参与者的平均击键间隔为 238.7ms快速打字者约 120ms慢速者超过 480ms。若延迟低于 200ms更可能在普通打字过程中就触发而 300ms 则会在 WebSocket 往返、Python 重跑和渲染开始前引入明显停顿。搜索结果延迟研究Teevan et al., HCIR 2013显示 100ms 的额外延迟就会产生行为层面的影响。因此250ms 是兼顾感知响应速度与重跑频率的通用折中值但并非普适最优廉价的 fragment 级过滤可以用live200ms昂贵或远程计算一般建议 300–500ms。二、API 设计live参数的签名与取值规格提出的 API 在st.text_input的 keyword-only 参数区新增livedef text_input( self, label: str, value: str | SupportsStr | None , ..., *, live: str | bool False, # New parameter ..., ) - str | None:该参数已在当前仓库完整落地实际签名位于 lib/streamlit/elements/widgets/text_widgets.pylive: str | bool False在validate之后、width之前并配套了_parse_text_input_live解析函数与完整的 docstring 说明text_widgets.py。取值语义表live取值行为False默认维持现状blur、Enter 或清除typesearch输入时提交True在最后一次被接受的用户输入变更后静默 250ms 即提交时长字符串如300ms、0.5s、1s与True相同但使用指定的停顿时间格式与st.cache_data的ttl一致零长度时长0ms、0s、0每次被接受的用户输入变更都立即提交无停顿。警告慎用对昂贵逻辑可能造成过多重跑裸int/float如300、0.3抛出StreamlitAPIException—— 与ttl/run_every不同裸数字不被接受那些 API 把数字视为秒而streamlit-keyup用户会把300读作毫秒。请使用True、时长字符串300ms或0mstimedeltav1 抛出StreamlitAPIException延迟支持见备选方案负数字符串如-1s抛出StreamlitAPIException—— 由于time_to_seconds/pd.Timedelta能成功解析负数实现必须显式拒绝而不能依赖ttl的校验无法解析的字符串如soon抛出StreamlitAPIExceptionStreamlitBadTimeStringError与ttl走同一条不可解析字符串路径超过 1 分钟的时长如2m、61s抛出StreamlitAPIExceptionStreamlitValueOutOfRangeError—— 实时防抖上限为 1 分钟防止60m、2h这类笔误排定数天的停顿live0ms与liveFalse在概念上是零意味着关闭的对立面但不会踩到 Python 的0 False陷阱——两者的取值类型分别是字符串和布尔值时长字符串让单位显式化。源码中的解析实现规格的行为表在仓库中对应 text_widgets.py 的_parse_text_input_live函数几个实现细节值得注意常量_DEFAULT_LIVE_DEBOUNCE_MS 250与_MAX_LIVE_DEBOUNCE_MS 60_0001 分钟上限注释说明若不加上限uint32 字段理论上可允许约 49 天的防抖先处理False返回None让 proto 字段保持未设置与True返回 250再因为bool是int的子类显式拦截int/float/timedelta并抛出带详细提示的StreamlitInvalidParameterTypeError对正数但亚毫秒的时长如0.0001s若四舍五入后为 0会被强制提升为 1ms避免静默退化为最昂贵的每次变更都提交模式用seconds 0而非debounce_ms 0判断负数避免亚毫秒级负数被舍入成 0 而漏检。什么会启动计时器被接受的用户主动输入变更打字、粘贴、剪切、拖放、自动填充、语音/辅助输入会启动计时器程序化更新脚本驱动的value、session-state 写入不会启动。typesearch的清除操作是立即提交路径见边界情况 7不启动计时器。三、重跑语义作用域、频率与 UI 状态重跑作用域不发明新目标live不引入新的重跑目标。实时提交沿用 widget 已有的作用域整个应用或包裹它的st.fragment/st.dialog。规格文档明确建议把实时搜索 UI 放进 fragment是避免打字时重跑应用其余部分的推荐方式。当前仓库 docstring 中的官方示例正是这种模式text_widgets.pyimport streamlit as st products [ {Product: Apple, Category: Fruit, Price: 1.20}, {Product: Banana, Category: Fruit, Price: 0.50}, {Product: Cherry, Category: Fruit, Price: 2.50}, {Product: Date, Category: Dried fruit, Price: 3.00}, ] st.fragment def product_search(): query st.text_input(Search products, typesearch, liveTrue) matches [p for p in products if query.lower() in p[Product].lower()] st.dataframe(matches, hide_indexTrue) product_search()重跑频率对一次交互一次重跑原则的有意豁免规格文档指出实时更新有意放宽 API 原则 34每次交互触发一次重跑—— 单次打字会话可能触发多次重跑。这一例外之所以可接受是因为它正是该功能的存在目的且对于True和正数时长重跑速率受延迟上界约束而零长度和极短延迟会移除或近乎移除该上界。即便 250ms 默认值对慢速或辅助输入头部指针、开关访问、屏幕键盘也可能在词中触发。因此性能警告适用于实时模式的普遍情况对零延迟和自定义短延迟措辞更强默认值False则完全保留一次交互一次重跑的行为。Running 状态与过期元素实时触发的重跑与任何 widget 触发的重跑一样使用相同的 Running 状态和过期元素stale element处理方式。抑制实时提交的闪烁不在范围内——希望页面更安静的作者应把实时输入及其结果放进 fragment。焦点与光标保持用户仍在编辑时实时重跑不得抢走焦点或跳动光标/选区——前提是同一个已启用的 widget 以相同身份继续渲染。若应用代码在重跑期间移除、更换 key、禁用或替换该 widget仍可能打断编辑。过期的重跑响应绝不能覆盖更新的脏编辑实时提交会清除dirty标记因此实现必须防止未提交的击键被在途的旧 run 覆盖。前端源码中确实有对应的防覆盖逻辑例如 TextInput.tsx 中的droppedIncomingWhileDirtyRef机制会在有脏编辑被丢弃后强制重新同步。输入提示文案当live不为False且 widget 在表单外时隐藏Press Enter to apply提示值已在停顿后提交max_chars的字符计数提示仍显示。在表单内live是 no-op因此Press Enter to submit form不变。四、边界情况live与既有功能的交互规格文档详细枚举了 11 个边界情况这是本功能最值得细读的部分。1. 与on_change回调的交互当live不为False且on_change为可调用对象时回调在对应脚本或 fragment 运行的开始时、正文之前以更新后的 widget 状态执行与现在的 widget 回调相同。挂起的实时重跑请求可能合并到最新的 widget 状态因此不保证每次实时更新都恰好调用一次回调。用户应把实时回调视为可能高频保存数据库、调用 API而非每个打字会话一次。2. 与on_changeignore的交互on_changeignore优先于live。每个被接受的停顿仍会把值暂存stage进 widget 状态但抑制重跑与回调即现有的setStringValue(..., triggerRerun: false)路径包括 blur、Enter 和搜索清除时。该值在下一次由其他 widget 触发的重跑中可用——它不能只停留在TextInput的 React 本地状态中。若同时设置了bindquery-params这个暂存提交会在每次停顿时更新 URL历史替换同边界情况 10而不重跑。3. 与st.form的交互表单内live无效—— 表单 widget 只在表单提交时提交值绝不在打字时提交。这是一个确定性、有文档说明的 no-op不记录警告与st.form一贯覆盖其中所有 widget 的交互即重跑行为一致。规格文档特别说明这有意不按表单内on_change回调那样处理后者抛StreamlitInvalidFormCallbackError——回调是显式用户代码静默省略会造成意外失败而live只是重跑时机标志静默抑制正是表单延迟所有 widget 交互重跑的既有方式若对其报错或告警反而与既定表单行为不一致。4. 与max_chars的交互两者独立工作。max_chars在前端由输入变更处理器useOnInputChange强制执行——当新值长度超过max_chars时在 widget 被标记为 dirty 之前就 early-return。后端TextInputSerde.deserialize见 text_widgets.py也会防御性地截断。实时更新计时器基于同一个变更处理器运行因此它只会看到限长内的值无需额外的客户端校验来把关。不要依赖原生 HTML 的maxlength属性——TextInput不会把它传给 input 元素InputInstructions上的maxLength只是字符计数显示。5. 密码输入live可用于typepassword无需特殊处理。值仍走现有 widget 路径只是比 blur/Enter 时发送得更频繁。6. 极快打字对于liveTrue或正数时长字符串计时器在每次被接受的变更时重置因此只有用户停顿后的最终值触发重跑。零长度时长没有停顿窗口所以每次被接受的变更都会触发重跑见行为表及性能警告。7. 挂起更新期间的 blur / Enter / 搜索清除如果用户停止打字后、计时器触发前发生 blur、按 Enter 或点击typesearch的清除按钮挂起的更新应立即冲刷提交 重跑而不是等待剩余延迟。blur、Enter 和搜索清除本就是st.text_input的既有提交路径三者必须冲刷计时器——否则搜索清除实时搜索的头号场景在显式清除后还要干等停顿。唯一例外是on_changeignore见边界情况 2它仍暂存值但抑制重跑。在st.form内该冲刷逻辑完全不适用因为live在那里无效边界情况 3计时器根本不会启动无事可冲刷。8. IME / 组合输入对通过多次击键构建字符的输入法如中日韩文字、通过死键输入的带重音字符计时器不得在中间组合状态触发。前端应在组合期间挂起计时器只在compositionend事件时重新启动它从而避免实时更新冲刷出残缺/乱码的中间值——只有完整的字符才触发重跑。9. 与validate的交互客户端validate正则或(regex, message)元组已随st.text_input发布它把关的是提交——值只有在 blur/Enter/搜索清除/表单提交时校验通过后才发送到后端并触发重跑。live只改变何时尝试提交因此二者干净组合每次打字停顿都成为一次额外的提交尝试校验方式与 blur/Enter 提交完全相同。值匹配则提交 重跑不匹配则输入框显示错误状态、不重跑——用户继续输入直到值合法。空字符串仍绕过校验所以空实时值正常提交。规格还提示未来若发布服务端可调用式validate尚未发布它将继承与on_change相同的频率告诫——校验器应廉价/幂等用户再次输入时应取消在途校验。10. 与bindquery-params的交互bindquery-params已发布将 widget 的已提交值同步进 URL。因为live把提交从 blur/Enter 移到打字停顿绑定的 widget 的查询参数会在每次停顿时更新而非仅在离开输入框时。为避免用每个中间值污染浏览器历史这些实时 URL 更新应使用历史替换类似history.replaceState即查询参数绑定已用于 widget 更新的机制而不是每次停顿时 push 新历史条目——这样返回按钮不会逐步回退用户输入的每个部分查询。因此分享/刷新后的 URL 反映的是最后一次实时提交时的值。11. Widget 身份identitylive省略与False共享同一个 ID。非默认延迟是未加 key widget 身份的一部分因此切换实时模式会重挂载 widget。加 key 的 widget 在live变化时保持 IDlive不在key_as_main_identity中。始终传入身份相关 kwargs关闭时也要传None不需要与旧版 Streamlit 的哈希匹配。仓库实现印证了这一点_text_input中计算 element_id 时使用了归一化后的毫秒数livelive_debounce_mstext_widgets.py注释明确说明这样True与250ms共享 ID而key_as_main_identity{max_chars, validate}只允许这两个参数改变加 key widget 的 ID。五、推荐用法liveTrue是最简单的选择适合大多数实时搜索/校验场景。搜索字段优先typesearch搭配liveTrue。注意typesearch本身不会开启实时更新需显式 opt-in——它与此前发布的搜索chrome图标、清除控件对应 issue #10744正交本规格负责的是实时提交时机。live200ms适合廉价的 fragment 级过滤300–500ms适合昂贵或远程计算。时长字符串让单位显式化。任何非False的live都会提高重跑频率。零长度和极短延迟可能使昂贵计算的应用ML 推理、大数据加载过载服务器。建议始终在实时 UI 外加 fragment。六、规格中的完整示例示例 1默认延迟的实时搜索import streamlit as st st.title(Product Search) # liveTrue 使用合理的默认停顿250ms。 # typesearch 是可选外观它本身不会开启实时更新。 query st.text_input(Search products, typesearch, liveTrue) if query: products [Apple, Banana, Cherry, Date, Elderberry] matches [p for p in products if query.lower() in p.lower()] st.write(fFound {len(matches)} results:) for match in matches: st.write(f- {match}) else: st.write(Start typing to search...)示例 2自定义延迟的即时校验import streamlit as st import re # live 接受与 ttl 相同格式的时长字符串。 email st.text_input(Email address, live500ms) if email: if re.match(r^[\w\.-][\w\.-]\.\w$, email): st.success(Valid email format) else: st.error(Please enter a valid email address)七、参数命名的备选方案为什么是live规格文档记录了完整的命名决策过程这对理解 Streamlit 的 API 设计原则很有价值。核心决策是使用live作为参数名取值形态为bool | strTrue 以默认停顿开启时长字符串 自定义时机0ms 每次被接受的输入事件都提交。v1 有意不接受裸整数、浮点数和timedelta。现有 API 的命名先例可分为几组语义名优先于机制名run_every、clear_on_submit、enter_to_submit、accept_new_options交互行为用复合名clear_on_submit、enter_to_submit、accept_multiple_files区别于disabled、border、parallel、lazy这类简短的属性标志单参数同时承担开关 配置show_spinner: bool | str、expanded: bool | int、accept_file: bool | Literal[...]时长值格式ttl、run_every、toast(duration...)中裸数字一律是秒而非毫秒模式枚举submit_mode、filter_mode、selection_mode。候选排名与评估排名名称评估1live简短有力、社区提议issue #4899 / PR #4920liveTrue读起来自然与parallel、lazy等简短行为标志一脉相承live300ms读起来也顺畅。唯一缺点脱离上下文略显含糊live 什么由 widget 语境和 docstring 补足。最终选择。2live_update无歧义符合clear_on_submit/enter_to_submit交互行为模式IDE 自动补全中一目了然——最强的备选。略冗长live_update500ms略显冗余。3update_while_typing自文档化最强、不可能误读与accept_multiple_files一脉相承。缺点冗长、时长读起来别扭typing对粘贴/语音/IME 输入略不准确。4auto_update清晰update对应 Streamlit 的重跑即更新模型又避开了让auto_submit失败的 submit 语义冲突。缺点auto_*不是 Streamlit 既定前缀且隐约唤起定时刷新run_every模糊了按定时器与随输入的界限。5update_delay/typing_delay纯时长形态str \| timedelta \| None None类型模型最干净与ttl/run_every最一致。缺点失去了True一行式入口且None表示关闭不如False直观。live与live_update是唯一接近的较量。规格的结论是live胜在简洁、与时长搭配读感更好live300msvslive_update500ms、有直接社区先例并与既有的简短行为标志parallel、lazy风格一致若评审方更看重显式性live_update作为后备。被排除的名称keyupDOM 行话且对粘贴/语音/IME 不准确、auto_submit与st.form和st.chat_input的submit_mode中 submit 的终端语义冲突、on_inputStreamlit 中on_*意为回调、update_on适合有限枚举不适合携带时长、realtime过度承诺——250ms 防抖的服务端重跑并非真实时。取值形态决策run_every、ttl、toast(duration...)都把裸数字视为秒因此live300表示毫秒会不一致且300ms比300或0.3可读性更好。拒绝正数裸数字是有意为之不只是0 False的问题——写live300的streamlit-keyup用户会得到一个指向True或300ms的StreamlitAPIException。timedelta被推迟后续加入是向后兼容的v1 保持bool | str以维持liveTrue的入门体验。八、超出范围的工作未来方向规格文档明确列出的未来工作项有助于理解当前边界st.text_area支持以完全相同的行为把live扩展到st.text_area。注意 text_area 中 Enter 插入换行不同于 text_input 中提交因此实时更新将成为打字时的主要重跑触发器。其他 widget本规格不定义跨 widget 的live词汇表。st.slider/st.number_input等若需交互中提交需要各自的规格。timedelta取值未来接受datetime.timedelta对齐ttl/run_every。节流模式限速如打字时最多每 500ms 一次而非live的防抖等待停顿行为。如需可增加throttle参数。取消/中止模式新输入到达时取消在途计算的机制。用户现在可以用st.session_state标志自行实现。静默运行 / 过期 UI为实时触发的重跑特判运行指示器或过期元素透明度。向辅助技术播报实时结果应用或 Streamlit 是否应在实时更新区域包裹aria-live。实现不得在每个停顿时重新播报整个页面。九、当前仓库中的落地实现速览规格所描述的功能在仓库中已完整实现以下是各层的落地位置便于读者深入Python 后端lib/streamlit/elements/widgets/text_widgets.py 中的_parse_text_input_live默认 250ms、上限 1 分钟、拒绝裸数字与负数、_text_input的参数透传与live_debounce_ms归一化入 ID、TextInputSerde.deserialize的max_chars防御性截断。protobuf 协议proto/streamlit/proto/TextInput.proto 的optional uint32 live_debounce_ms 19字段注释明确未设置 关闭0 每次被接受的变更提交正数 毫秒防抖True映射到 250。前端组件frontend/lib/src/components/widgets/TextInput/TextInput.tsx 中isLive/liveEnabled判断0是开启且立即提交不能被当作关闭、useDebouncedCallback驱动的scheduleLiveCommit、IMEcompositionend挂起、脏编辑保护与droppedIncomingWhileDirtyRef强制重同步等逻辑并有配套单元测试 TextInput.test.tsx。测试覆盖lib/tests/streamlit/elements/text_input_test.py 中约 40 处与live/live_debounce相关的断言覆盖了解析、校验与 ID 行为lib/tests/streamlit/typing/text_input_types.py 覆盖live的类型标注。规格文档的 checklist 确认该功能在 SiS、Streamlit Cloud 等环境均可用Python protobuf 前端协同实时提交沿用 widget 现有重跑作用域无破坏性 API 变更新增可选参数省略与False共享 ID加 key 的 widget 在live变化时保持稳定无新依赖沿用现有 text_input 埋点无安全/法律影响需要更新 text_input 的 docstring仓库中已包含完整的live文档与示例。结语live参数把即时响应从第三方组件的变通方案变成了st.text_input的原生能力同时通过防抖、作用域复用、IME 处理与 1 分钟上限等设计把高频重跑的风险约束在可控范围内。理解它的取值语义True/ 时长字符串 /0ms、与st.form、on_change、validate、bindquery-params的交互规则以及在 fragment 中使用的最佳实践是写出流畅且高性能实时界面的关键。规格文档product-spec.md是这一设计的完整原始记录值得结合上述源码位置一起阅读。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Streamlit `st.text_input` 实时更新（live）模式完全指南：参数设计、行为语义与源码实现
Streamlitst.text_input实时更新live模式完全指南参数设计、行为语义与源码实现【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit本文基于 Streamlit 仓库中的产品规格文档 specs/2026-08-03-text-input-live-update/product-spec.md 编写并结合当前仓库中该功能已落地的后端实现lib/streamlit/elements/widgets/text_widgets.py、protobuf 定义proto/streamlit/proto/TextInput.proto与前端组件frontend/lib/src/components/widgets/TextInput/TextInput.tsx进行交叉印证。st.text_input的live参数为 Streamlit 应用带来了边输入边更新的能力用户打字停顿片刻后自动触发重跑无需按下回车或离开输入框。本文是这份规格文档的完整解读涵盖参数设计动机、bool | str值语义、与st.form/on_change/validate/bindquery-params等既有功能的交互边界、11 个关键边界情况以及对应的仓库源码实现细节。读完本文你将能正确选择liveTrue、live300ms与live0ms规避高频重跑、IME 组合输入、焦点丢失等陷阱并用st.fragment写出高性能的实时搜索界面。一、为什么需要live问题背景与使用场景传统上st.text_input只在以下三种时刻触发重跑用户按下Enter、离开输入框blur、或点击typesearch输入框的清除按钮。这意味着用户输入过程中页面完全静止必须额外操作才能看到结果与 Google 搜索框、IDE 自动补全等即时响应体验存在明显差距对应 GitHub Issue #4553该 issue 编号来自规格文档记录。规格文档归纳了三个典型诉求实时搜索 / 自动补全用户输入时即时过滤结果无需按 Enter 或 Tab。规格中的期望行为是query st.text_input(Search products, typesearch, liveTrue) filtered [p for p in products if query.lower() in p.lower()] st.write(filtered)实时校验边输入边给出反馈例如用户名已被占用密码强度不足不必等到提交表单才提示。实时格式化预览边输入边渲染 Markdown、LaTeX 或代码高亮效果。既有的三种变通方案及其局限变通方案局限性streamlit-keyup第三方组件需要额外安装和信任第三方依赖非 Streamlit 内置不会自动跟随原生 widget 的主题与样式自研 Custom Component开发与维护成本高按 Enter 再搜索交互体验差不符合搜索类界面的直觉规格文档特别指出第三方组件 blackary/streamlit-keyup 以 200 Star 证明了这一需求的强度其 API 为value st_keyup(Search)每次按键更新与value st_keyup(Search, debounce500)500ms 防抖。这正是live参数要内建到原生 widget 中的能力。为什么默认延迟是 250ms规格文档给出了一个数据依据大规模打字研究Dhakal et al., CHI 2018168,960 名参与者的平均击键间隔为 238.7ms快速打字者约 120ms慢速者超过 480ms。若延迟低于 200ms更可能在普通打字过程中就触发而 300ms 则会在 WebSocket 往返、Python 重跑和渲染开始前引入明显停顿。搜索结果延迟研究Teevan et al., HCIR 2013显示 100ms 的额外延迟就会产生行为层面的影响。因此250ms 是兼顾感知响应速度与重跑频率的通用折中值但并非普适最优廉价的 fragment 级过滤可以用live200ms昂贵或远程计算一般建议 300–500ms。二、API 设计live参数的签名与取值规格提出的 API 在st.text_input的 keyword-only 参数区新增livedef text_input( self, label: str, value: str | SupportsStr | None , ..., *, live: str | bool False, # New parameter ..., ) - str | None:该参数已在当前仓库完整落地实际签名位于 lib/streamlit/elements/widgets/text_widgets.pylive: str | bool False在validate之后、width之前并配套了_parse_text_input_live解析函数与完整的 docstring 说明text_widgets.py。取值语义表live取值行为False默认维持现状blur、Enter 或清除typesearch输入时提交True在最后一次被接受的用户输入变更后静默 250ms 即提交时长字符串如300ms、0.5s、1s与True相同但使用指定的停顿时间格式与st.cache_data的ttl一致零长度时长0ms、0s、0每次被接受的用户输入变更都立即提交无停顿。警告慎用对昂贵逻辑可能造成过多重跑裸int/float如300、0.3抛出StreamlitAPIException—— 与ttl/run_every不同裸数字不被接受那些 API 把数字视为秒而streamlit-keyup用户会把300读作毫秒。请使用True、时长字符串300ms或0mstimedeltav1 抛出StreamlitAPIException延迟支持见备选方案负数字符串如-1s抛出StreamlitAPIException—— 由于time_to_seconds/pd.Timedelta能成功解析负数实现必须显式拒绝而不能依赖ttl的校验无法解析的字符串如soon抛出StreamlitAPIExceptionStreamlitBadTimeStringError与ttl走同一条不可解析字符串路径超过 1 分钟的时长如2m、61s抛出StreamlitAPIExceptionStreamlitValueOutOfRangeError—— 实时防抖上限为 1 分钟防止60m、2h这类笔误排定数天的停顿live0ms与liveFalse在概念上是零意味着关闭的对立面但不会踩到 Python 的0 False陷阱——两者的取值类型分别是字符串和布尔值时长字符串让单位显式化。源码中的解析实现规格的行为表在仓库中对应 text_widgets.py 的_parse_text_input_live函数几个实现细节值得注意常量_DEFAULT_LIVE_DEBOUNCE_MS 250与_MAX_LIVE_DEBOUNCE_MS 60_0001 分钟上限注释说明若不加上限uint32 字段理论上可允许约 49 天的防抖先处理False返回None让 proto 字段保持未设置与True返回 250再因为bool是int的子类显式拦截int/float/timedelta并抛出带详细提示的StreamlitInvalidParameterTypeError对正数但亚毫秒的时长如0.0001s若四舍五入后为 0会被强制提升为 1ms避免静默退化为最昂贵的每次变更都提交模式用seconds 0而非debounce_ms 0判断负数避免亚毫秒级负数被舍入成 0 而漏检。什么会启动计时器被接受的用户主动输入变更打字、粘贴、剪切、拖放、自动填充、语音/辅助输入会启动计时器程序化更新脚本驱动的value、session-state 写入不会启动。typesearch的清除操作是立即提交路径见边界情况 7不启动计时器。三、重跑语义作用域、频率与 UI 状态重跑作用域不发明新目标live不引入新的重跑目标。实时提交沿用 widget 已有的作用域整个应用或包裹它的st.fragment/st.dialog。规格文档明确建议把实时搜索 UI 放进 fragment是避免打字时重跑应用其余部分的推荐方式。当前仓库 docstring 中的官方示例正是这种模式text_widgets.pyimport streamlit as st products [ {Product: Apple, Category: Fruit, Price: 1.20}, {Product: Banana, Category: Fruit, Price: 0.50}, {Product: Cherry, Category: Fruit, Price: 2.50}, {Product: Date, Category: Dried fruit, Price: 3.00}, ] st.fragment def product_search(): query st.text_input(Search products, typesearch, liveTrue) matches [p for p in products if query.lower() in p[Product].lower()] st.dataframe(matches, hide_indexTrue) product_search()重跑频率对一次交互一次重跑原则的有意豁免规格文档指出实时更新有意放宽 API 原则 34每次交互触发一次重跑—— 单次打字会话可能触发多次重跑。这一例外之所以可接受是因为它正是该功能的存在目的且对于True和正数时长重跑速率受延迟上界约束而零长度和极短延迟会移除或近乎移除该上界。即便 250ms 默认值对慢速或辅助输入头部指针、开关访问、屏幕键盘也可能在词中触发。因此性能警告适用于实时模式的普遍情况对零延迟和自定义短延迟措辞更强默认值False则完全保留一次交互一次重跑的行为。Running 状态与过期元素实时触发的重跑与任何 widget 触发的重跑一样使用相同的 Running 状态和过期元素stale element处理方式。抑制实时提交的闪烁不在范围内——希望页面更安静的作者应把实时输入及其结果放进 fragment。焦点与光标保持用户仍在编辑时实时重跑不得抢走焦点或跳动光标/选区——前提是同一个已启用的 widget 以相同身份继续渲染。若应用代码在重跑期间移除、更换 key、禁用或替换该 widget仍可能打断编辑。过期的重跑响应绝不能覆盖更新的脏编辑实时提交会清除dirty标记因此实现必须防止未提交的击键被在途的旧 run 覆盖。前端源码中确实有对应的防覆盖逻辑例如 TextInput.tsx 中的droppedIncomingWhileDirtyRef机制会在有脏编辑被丢弃后强制重新同步。输入提示文案当live不为False且 widget 在表单外时隐藏Press Enter to apply提示值已在停顿后提交max_chars的字符计数提示仍显示。在表单内live是 no-op因此Press Enter to submit form不变。四、边界情况live与既有功能的交互规格文档详细枚举了 11 个边界情况这是本功能最值得细读的部分。1. 与on_change回调的交互当live不为False且on_change为可调用对象时回调在对应脚本或 fragment 运行的开始时、正文之前以更新后的 widget 状态执行与现在的 widget 回调相同。挂起的实时重跑请求可能合并到最新的 widget 状态因此不保证每次实时更新都恰好调用一次回调。用户应把实时回调视为可能高频保存数据库、调用 API而非每个打字会话一次。2. 与on_changeignore的交互on_changeignore优先于live。每个被接受的停顿仍会把值暂存stage进 widget 状态但抑制重跑与回调即现有的setStringValue(..., triggerRerun: false)路径包括 blur、Enter 和搜索清除时。该值在下一次由其他 widget 触发的重跑中可用——它不能只停留在TextInput的 React 本地状态中。若同时设置了bindquery-params这个暂存提交会在每次停顿时更新 URL历史替换同边界情况 10而不重跑。3. 与st.form的交互表单内live无效—— 表单 widget 只在表单提交时提交值绝不在打字时提交。这是一个确定性、有文档说明的 no-op不记录警告与st.form一贯覆盖其中所有 widget 的交互即重跑行为一致。规格文档特别说明这有意不按表单内on_change回调那样处理后者抛StreamlitInvalidFormCallbackError——回调是显式用户代码静默省略会造成意外失败而live只是重跑时机标志静默抑制正是表单延迟所有 widget 交互重跑的既有方式若对其报错或告警反而与既定表单行为不一致。4. 与max_chars的交互两者独立工作。max_chars在前端由输入变更处理器useOnInputChange强制执行——当新值长度超过max_chars时在 widget 被标记为 dirty 之前就 early-return。后端TextInputSerde.deserialize见 text_widgets.py也会防御性地截断。实时更新计时器基于同一个变更处理器运行因此它只会看到限长内的值无需额外的客户端校验来把关。不要依赖原生 HTML 的maxlength属性——TextInput不会把它传给 input 元素InputInstructions上的maxLength只是字符计数显示。5. 密码输入live可用于typepassword无需特殊处理。值仍走现有 widget 路径只是比 blur/Enter 时发送得更频繁。6. 极快打字对于liveTrue或正数时长字符串计时器在每次被接受的变更时重置因此只有用户停顿后的最终值触发重跑。零长度时长没有停顿窗口所以每次被接受的变更都会触发重跑见行为表及性能警告。7. 挂起更新期间的 blur / Enter / 搜索清除如果用户停止打字后、计时器触发前发生 blur、按 Enter 或点击typesearch的清除按钮挂起的更新应立即冲刷提交 重跑而不是等待剩余延迟。blur、Enter 和搜索清除本就是st.text_input的既有提交路径三者必须冲刷计时器——否则搜索清除实时搜索的头号场景在显式清除后还要干等停顿。唯一例外是on_changeignore见边界情况 2它仍暂存值但抑制重跑。在st.form内该冲刷逻辑完全不适用因为live在那里无效边界情况 3计时器根本不会启动无事可冲刷。8. IME / 组合输入对通过多次击键构建字符的输入法如中日韩文字、通过死键输入的带重音字符计时器不得在中间组合状态触发。前端应在组合期间挂起计时器只在compositionend事件时重新启动它从而避免实时更新冲刷出残缺/乱码的中间值——只有完整的字符才触发重跑。9. 与validate的交互客户端validate正则或(regex, message)元组已随st.text_input发布它把关的是提交——值只有在 blur/Enter/搜索清除/表单提交时校验通过后才发送到后端并触发重跑。live只改变何时尝试提交因此二者干净组合每次打字停顿都成为一次额外的提交尝试校验方式与 blur/Enter 提交完全相同。值匹配则提交 重跑不匹配则输入框显示错误状态、不重跑——用户继续输入直到值合法。空字符串仍绕过校验所以空实时值正常提交。规格还提示未来若发布服务端可调用式validate尚未发布它将继承与on_change相同的频率告诫——校验器应廉价/幂等用户再次输入时应取消在途校验。10. 与bindquery-params的交互bindquery-params已发布将 widget 的已提交值同步进 URL。因为live把提交从 blur/Enter 移到打字停顿绑定的 widget 的查询参数会在每次停顿时更新而非仅在离开输入框时。为避免用每个中间值污染浏览器历史这些实时 URL 更新应使用历史替换类似history.replaceState即查询参数绑定已用于 widget 更新的机制而不是每次停顿时 push 新历史条目——这样返回按钮不会逐步回退用户输入的每个部分查询。因此分享/刷新后的 URL 反映的是最后一次实时提交时的值。11. Widget 身份identitylive省略与False共享同一个 ID。非默认延迟是未加 key widget 身份的一部分因此切换实时模式会重挂载 widget。加 key 的 widget 在live变化时保持 IDlive不在key_as_main_identity中。始终传入身份相关 kwargs关闭时也要传None不需要与旧版 Streamlit 的哈希匹配。仓库实现印证了这一点_text_input中计算 element_id 时使用了归一化后的毫秒数livelive_debounce_mstext_widgets.py注释明确说明这样True与250ms共享 ID而key_as_main_identity{max_chars, validate}只允许这两个参数改变加 key widget 的 ID。五、推荐用法liveTrue是最简单的选择适合大多数实时搜索/校验场景。搜索字段优先typesearch搭配liveTrue。注意typesearch本身不会开启实时更新需显式 opt-in——它与此前发布的搜索chrome图标、清除控件对应 issue #10744正交本规格负责的是实时提交时机。live200ms适合廉价的 fragment 级过滤300–500ms适合昂贵或远程计算。时长字符串让单位显式化。任何非False的live都会提高重跑频率。零长度和极短延迟可能使昂贵计算的应用ML 推理、大数据加载过载服务器。建议始终在实时 UI 外加 fragment。六、规格中的完整示例示例 1默认延迟的实时搜索import streamlit as st st.title(Product Search) # liveTrue 使用合理的默认停顿250ms。 # typesearch 是可选外观它本身不会开启实时更新。 query st.text_input(Search products, typesearch, liveTrue) if query: products [Apple, Banana, Cherry, Date, Elderberry] matches [p for p in products if query.lower() in p.lower()] st.write(fFound {len(matches)} results:) for match in matches: st.write(f- {match}) else: st.write(Start typing to search...)示例 2自定义延迟的即时校验import streamlit as st import re # live 接受与 ttl 相同格式的时长字符串。 email st.text_input(Email address, live500ms) if email: if re.match(r^[\w\.-][\w\.-]\.\w$, email): st.success(Valid email format) else: st.error(Please enter a valid email address)七、参数命名的备选方案为什么是live规格文档记录了完整的命名决策过程这对理解 Streamlit 的 API 设计原则很有价值。核心决策是使用live作为参数名取值形态为bool | strTrue 以默认停顿开启时长字符串 自定义时机0ms 每次被接受的输入事件都提交。v1 有意不接受裸整数、浮点数和timedelta。现有 API 的命名先例可分为几组语义名优先于机制名run_every、clear_on_submit、enter_to_submit、accept_new_options交互行为用复合名clear_on_submit、enter_to_submit、accept_multiple_files区别于disabled、border、parallel、lazy这类简短的属性标志单参数同时承担开关 配置show_spinner: bool | str、expanded: bool | int、accept_file: bool | Literal[...]时长值格式ttl、run_every、toast(duration...)中裸数字一律是秒而非毫秒模式枚举submit_mode、filter_mode、selection_mode。候选排名与评估排名名称评估1live简短有力、社区提议issue #4899 / PR #4920liveTrue读起来自然与parallel、lazy等简短行为标志一脉相承live300ms读起来也顺畅。唯一缺点脱离上下文略显含糊live 什么由 widget 语境和 docstring 补足。最终选择。2live_update无歧义符合clear_on_submit/enter_to_submit交互行为模式IDE 自动补全中一目了然——最强的备选。略冗长live_update500ms略显冗余。3update_while_typing自文档化最强、不可能误读与accept_multiple_files一脉相承。缺点冗长、时长读起来别扭typing对粘贴/语音/IME 输入略不准确。4auto_update清晰update对应 Streamlit 的重跑即更新模型又避开了让auto_submit失败的 submit 语义冲突。缺点auto_*不是 Streamlit 既定前缀且隐约唤起定时刷新run_every模糊了按定时器与随输入的界限。5update_delay/typing_delay纯时长形态str \| timedelta \| None None类型模型最干净与ttl/run_every最一致。缺点失去了True一行式入口且None表示关闭不如False直观。live与live_update是唯一接近的较量。规格的结论是live胜在简洁、与时长搭配读感更好live300msvslive_update500ms、有直接社区先例并与既有的简短行为标志parallel、lazy风格一致若评审方更看重显式性live_update作为后备。被排除的名称keyupDOM 行话且对粘贴/语音/IME 不准确、auto_submit与st.form和st.chat_input的submit_mode中 submit 的终端语义冲突、on_inputStreamlit 中on_*意为回调、update_on适合有限枚举不适合携带时长、realtime过度承诺——250ms 防抖的服务端重跑并非真实时。取值形态决策run_every、ttl、toast(duration...)都把裸数字视为秒因此live300表示毫秒会不一致且300ms比300或0.3可读性更好。拒绝正数裸数字是有意为之不只是0 False的问题——写live300的streamlit-keyup用户会得到一个指向True或300ms的StreamlitAPIException。timedelta被推迟后续加入是向后兼容的v1 保持bool | str以维持liveTrue的入门体验。八、超出范围的工作未来方向规格文档明确列出的未来工作项有助于理解当前边界st.text_area支持以完全相同的行为把live扩展到st.text_area。注意 text_area 中 Enter 插入换行不同于 text_input 中提交因此实时更新将成为打字时的主要重跑触发器。其他 widget本规格不定义跨 widget 的live词汇表。st.slider/st.number_input等若需交互中提交需要各自的规格。timedelta取值未来接受datetime.timedelta对齐ttl/run_every。节流模式限速如打字时最多每 500ms 一次而非live的防抖等待停顿行为。如需可增加throttle参数。取消/中止模式新输入到达时取消在途计算的机制。用户现在可以用st.session_state标志自行实现。静默运行 / 过期 UI为实时触发的重跑特判运行指示器或过期元素透明度。向辅助技术播报实时结果应用或 Streamlit 是否应在实时更新区域包裹aria-live。实现不得在每个停顿时重新播报整个页面。九、当前仓库中的落地实现速览规格所描述的功能在仓库中已完整实现以下是各层的落地位置便于读者深入Python 后端lib/streamlit/elements/widgets/text_widgets.py 中的_parse_text_input_live默认 250ms、上限 1 分钟、拒绝裸数字与负数、_text_input的参数透传与live_debounce_ms归一化入 ID、TextInputSerde.deserialize的max_chars防御性截断。protobuf 协议proto/streamlit/proto/TextInput.proto 的optional uint32 live_debounce_ms 19字段注释明确未设置 关闭0 每次被接受的变更提交正数 毫秒防抖True映射到 250。前端组件frontend/lib/src/components/widgets/TextInput/TextInput.tsx 中isLive/liveEnabled判断0是开启且立即提交不能被当作关闭、useDebouncedCallback驱动的scheduleLiveCommit、IMEcompositionend挂起、脏编辑保护与droppedIncomingWhileDirtyRef强制重同步等逻辑并有配套单元测试 TextInput.test.tsx。测试覆盖lib/tests/streamlit/elements/text_input_test.py 中约 40 处与live/live_debounce相关的断言覆盖了解析、校验与 ID 行为lib/tests/streamlit/typing/text_input_types.py 覆盖live的类型标注。规格文档的 checklist 确认该功能在 SiS、Streamlit Cloud 等环境均可用Python protobuf 前端协同实时提交沿用 widget 现有重跑作用域无破坏性 API 变更新增可选参数省略与False共享 ID加 key 的 widget 在live变化时保持稳定无新依赖沿用现有 text_input 埋点无安全/法律影响需要更新 text_input 的 docstring仓库中已包含完整的live文档与示例。结语live参数把即时响应从第三方组件的变通方案变成了st.text_input的原生能力同时通过防抖、作用域复用、IME 处理与 1 分钟上限等设计把高频重跑的风险约束在可控范围内。理解它的取值语义True/ 时长字符串 /0ms、与st.form、on_change、validate、bindquery-params的交互规则以及在 fragment 中使用的最佳实践是写出流畅且高性能实时界面的关键。规格文档product-spec.md是这一设计的完整原始记录值得结合上述源码位置一起阅读。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考