Streamlit CCv2 状态同步实战掌握 JS ↔ Python 受控组件循环State Sync Patterns【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit本指南以 Streamlit 官方开发指南中的 CCv2Custom Component v2状态同步参考文档为主体系统讲解 JavaScript 与 Python 之间双向状态同步的规范模式、default参数的正确用法、两种水合hydration策略的取舍以及 Session State 时序陷阱。读完本文你将能够从零实现一个状态不丢失、光标不跳变、可与 Python 侧逻辑联动的受控组件并学会用仓库源码与 e2e 用例验证自己的实现。心智模型理解 CCv2 的双向状态同步在动手写代码之前先建立一个正确的心智模型。CCv2 组件的前后端通信有且只有两个方向且不存在内建的“双向绑定two-way binding”——两个方向都必须由你自己显式实现前端状态发射JS → Python组件 JS 显式调用setStateValue(key, value)或setTriggerValue(key, value)把用户交互结果送回 Python。前端状态水合Python → JS组件 JS 读取component.dataPython 通过挂载命令传入的数据据此更新 DOM。这个模型在仓库源码中有非常直观的体现。前端加载组件 JS 并注入 API 的入口位于 useHandleJsContent.tsStreamlit 每次渲染都会以如下参数调用你的export default函数module.default({ name: componentName, // 注册时的组件名 data, // Python 传来的 data水合方向 key: componentId, // 前端实例 key parentElement, // 挂载容器ShadowRoot 或 HTMLElement setStateValue, // 状态发射 API setTriggerValue, // 触发器发射 API })从源码可以看出data是每次渲染都重新注入的新对象见依赖数组中包含data的 effect因此你的 JS 函数在每次 rerun 后都会被重新执行——这正是“每次渲染都对账reconcile”同步模式的底层基础。这两个方向的参数类型定义可参见 types.tssetStateValue用于跨 rerun 持久的状态键setTriggerValue用于单次 rerun 即消费的一次性事件。规范模式受控文本输入组件下面这套“受控文本输入controlled text input”模式是 CCv2 状态同步的规范范例其结构取材于 Streamlit 官方仓库自带的 e2e 示例见 e2e_playwright/bidi_components/basics.py。JavaScript 侧从data水合用setStateValue发射关键准则是只有当data中的值与输入框当前值不同时才写入input.value否则你会和用户的输入光标“打架”——每次 rerun 都无条件赋值会把光标强制弹回末尾造成打字体验异常。export default function (component) { const { parentElement, data, setStateValue } component const label parentElement.querySelector(label) const input parentElement.querySelector(input) if (!label || !input) return label.innerText data.label const nextValue data.value ?? if (input.value ! nextValue) { input.value nextValue } input.onkeydown e { if (e.key Enter) { setStateValue(value, e.target.value) } } }要点拆解水合侧data.value ?? 处理 Python 尚未传值的情况if (input.value ! nextValue)的条件赋值保护用户正在编辑时输入框的 DOM 状态不被覆盖这是“不打架”的关键。发射侧setStateValue(value, e.target.value)会把{ value: ... }这个扁平状态映射写回 Python。从 useHandleJsContent.ts 的源码可以看到setStateValue会读取当前状态、浅合并新键然后通过widgetMgr.setJsonValue以fromUser: true的标记提交到运行时触发一次重跑并持久化到 Session State。parentElement的查询范围当isolate_stylesTrue默认时 HTML 挂在 Shadow DOM 中parentElement是ShadowRootquerySelector在影子根内查找若设为False则直接操作主 DOM 树。Python 侧通过data把状态喂回前端Python 包装函数负责“读状态 → 算值 → 下发”每次脚本运行都执行这个闭环import streamlit as st _COMPONENT st.components.v2.component( interactive_text_input, html label fortxtEnter text:/label input idtxt typetext / , jsJS, # 上面的内联 JS 字符串 ) def interactive_text_input(*, label: str, initial_value: str, key: str): # 1) 从 Session State 读取当前组件状态如果存在 component_state st.session_state.get(key, {}) # 2) 计算 UI 想要显示的值 value component_state.get(value, initial_value) # 3) 通过 data 下发到前端 return _COMPONENT( keykey, data{label: label, value: value}, ) KEY my_text_input if st.button(Make it say Hello World): st.session_state.setdefault(KEY, {})[value] Hello World interactive_text_input(labelEnter something, initial_valueInitial Text, keyKEY)这段代码体现了三个关键机制均可在源码中找到对应实现组件注册与挂载分离st.components.v2.component(...)只负责注册返回可挂载的 callable实际挂载在调用_COMPONENT(...)时发生。注册逻辑见 components/v2/init.pyjs参数既可以是内联 JS 字符串也可以是已安装组件asset_dir下的路径/glob。状态读取st.session_state.get(key, {})读取的是该组件实例以key标识的扁平状态映射。组件挂载时Python 通过 main.py 中的register_widget注册状态 widget反序列化器BidiComponentSerde会把前端回传的 JSON 解析为字典见 serialization.py。跨 rerun 的双向环按钮处理器先改写 Session State → 重跑时包装函数读到新值 → 通过data下发 → JS 水合更新 DOM。这个环每跑一次脚本就闭合一次。值得注意的是脚本中只有on_key_change形式才会被识别为事件回调_bidi_component在 main.py 中只接受on_前缀且_change后缀的 kwarg。上面的例子故意不注册回调因为包装函数用st.session_state手动管理状态如果你希望状态键始终出现在返回值中则应在挂载时传入对应的on_value_change回调。default...何时使用以及为什么它可能失败default{...}是可选的。它的用途是当某个已挂载实例的状态键在 Session State 中缺失时由 Streamlit 代为初始化。使用规则default只作用于状态键state keys不作用于触发器trigger keys。触发器本质是一次性事件不存在“默认值”语义。default中的每个键在挂载时都必须有对应的on_key_change回调参数否则 Streamlit 直接抛异常。规范写法result _COMPONENT( keykey, data{value: value}, default{value: value}, on_value_changelambda: None, # 使用 default[value] 时必须提供 )为什么default需要配套回调源码给出了确凿答案在 _bidi_component 中挂载时会遍历default的每个键并校验其是否存在于已解析的回调映射中不匹配即抛出BidiComponentInvalidDefaultKeyError。这是因为“允许的状态键集合”正是由回调集合定义的——allowed_state_keys决定哪些键能进入用户可见的 Session State见 main.py。default实际生效的位置在序列化层BidiComponentSerde.deserialize在把前端值解析为字典后会对default中尚不存在的键补上默认值见 serialization.py。理解这一点有助于你判断该用哪种模式需要Python 每次运行都驱动 UI 值例如响应按钮、回调、外部状态→ 用受控模式不依赖default每轮从data下发需要首次挂载时给缺失状态一个初始值→ 用default同时记得补回调。Python → JS 水合初始一次性 vs 真正同步社区中常见两种水合写法理解它们的差别是避免“Python 改了但界面不更新”的关键。初始一次性水合initial-onlyJS 只在首次挂载时读取data.initialX之后不再响应。适合做初始化但不会反映 Python 后续的修改// 用 hasMounted 做守卫的话Python 的后续修改将无法传播到界面 if (typeof data?.initialText ! undefined !hasMountedForKey) { input.value String(data.initialText) } hasMounted[key] true仓库自带的 e2e 示例 basics.py 中的_STATEFUL_JS正是这种模式的真实样板它用模块级let hasMounted {}按 key 记录是否已挂载仅在首次时把data.initialRange/data.initialText写入控件之后只靠setStateValue向上发射——因为该示例的 Python 侧并不打算在运行中改写值所以这是合理的初始化用法。真正同步受控true syncJS 每次渲染都用data对账且仅在值变化时才写入 DOMconst nextValue data.value ?? if (input.value ! nextValue) input.value nextValue当 Python 需要在运行中更新 UI 时必须采用受控模式。原因在于useHandleJsContent的 effect 依赖数组包含data见 useHandleJsContent.ts只要 Python 传入的data引用/内容变化组件 JS 就会重新执行受控写法保证每次重跑后 DOM 与 Python 数据一致而 initial-only 写法会因守卫而跳过更新。Session State 时序不要在挂载后修改Streamlit 可能抛错如果你在同一个运行中、组件实例化之后才修改st.session_state.key.field。这是因为组件挂载时register_widget已经把该 key 的 widget 注册进当前运行的 Session State 管理流程见 main.py挂载后外部直接修改其内部字段会破坏 widget 值与注册状态的一致性约束。安全模式有两种在挂载之前修改状态把st.session_state[key][...] ...放在组件挂载调用上方的逻辑里例如放在更早执行的按钮处理器中——这正是本文示例代码的做法按钮处理器在interactive_text_input(...)之前执行先写状态、后挂载。分两轮运行先设置状态并触发 rerun在下一轮运行中再挂载组件。故障排查清单把上面的知识点浓缩成一份可直接对照的排查清单光标跳变 / 打字感觉卡顿检查 JS 是否只在input.value与data值不同时才赋值。无条件写入是光标冲突的头号原因。Python 更新没反映到界面确认每轮运行都通过data下发最新值若想实现真正同步避免使用 initial-only 水合守卫hasMounted。default抛异常确保default中的每个键都有对应的on_key_change回调参数回调集合定义了允许的状态键集合BidiComponentInvalidDefaultKeyError即由此触发。Session State 修改报错把st.session_state[key][...] ...移到脚本中更靠前的位置组件挂载之前或重构为两轮运行流程先设状态再 rerun。补充State 与 Trigger 的边界来自源码的事实为了让你在实际组件设计中少踩坑这里补充文档未展开、但源码明确规定的两个边界setTriggerValue在表单内被忽略。useHandleJsContent.ts 明确实现当组件渲染在st.form内时setTriggerValue直接 no-op 并打警告日志——因为 Streamlit 执行模型不允许表单内触发器应改用setStateValue配合表单提交按钮。触发器按事件聚合。Python 侧每个触发器事件都会生成内部聚合器 ID$$STREAMLIT_INTERNAL_KEY_{base}__{event}形态见 main.py前端回传的 payload 列表经 serialization.py 的deserialize_trigger_list归一化为列表后再按事件名映射到回调并暴露在ComponentResult中main.py。触发器键会被内部前缀隐藏不会暴露在面向用户的st.session_state中。如果组件在打包、主题或疑难杂症上还有问题可以继续阅读同目录下的 ccv2-packaged-components.md、ccv2-troubleshooting.md 与 session-state.md并在 e2e_playwright/bidi_components/basics.py 中查看可运行的完整端到端示例。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Streamlit CCv2 状态同步实战：掌握 JS ↔ Python 受控组件循环（State Sync Patterns）
Streamlit CCv2 状态同步实战掌握 JS ↔ Python 受控组件循环State Sync Patterns【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit本指南以 Streamlit 官方开发指南中的 CCv2Custom Component v2状态同步参考文档为主体系统讲解 JavaScript 与 Python 之间双向状态同步的规范模式、default参数的正确用法、两种水合hydration策略的取舍以及 Session State 时序陷阱。读完本文你将能够从零实现一个状态不丢失、光标不跳变、可与 Python 侧逻辑联动的受控组件并学会用仓库源码与 e2e 用例验证自己的实现。心智模型理解 CCv2 的双向状态同步在动手写代码之前先建立一个正确的心智模型。CCv2 组件的前后端通信有且只有两个方向且不存在内建的“双向绑定two-way binding”——两个方向都必须由你自己显式实现前端状态发射JS → Python组件 JS 显式调用setStateValue(key, value)或setTriggerValue(key, value)把用户交互结果送回 Python。前端状态水合Python → JS组件 JS 读取component.dataPython 通过挂载命令传入的数据据此更新 DOM。这个模型在仓库源码中有非常直观的体现。前端加载组件 JS 并注入 API 的入口位于 useHandleJsContent.tsStreamlit 每次渲染都会以如下参数调用你的export default函数module.default({ name: componentName, // 注册时的组件名 data, // Python 传来的 data水合方向 key: componentId, // 前端实例 key parentElement, // 挂载容器ShadowRoot 或 HTMLElement setStateValue, // 状态发射 API setTriggerValue, // 触发器发射 API })从源码可以看出data是每次渲染都重新注入的新对象见依赖数组中包含data的 effect因此你的 JS 函数在每次 rerun 后都会被重新执行——这正是“每次渲染都对账reconcile”同步模式的底层基础。这两个方向的参数类型定义可参见 types.tssetStateValue用于跨 rerun 持久的状态键setTriggerValue用于单次 rerun 即消费的一次性事件。规范模式受控文本输入组件下面这套“受控文本输入controlled text input”模式是 CCv2 状态同步的规范范例其结构取材于 Streamlit 官方仓库自带的 e2e 示例见 e2e_playwright/bidi_components/basics.py。JavaScript 侧从data水合用setStateValue发射关键准则是只有当data中的值与输入框当前值不同时才写入input.value否则你会和用户的输入光标“打架”——每次 rerun 都无条件赋值会把光标强制弹回末尾造成打字体验异常。export default function (component) { const { parentElement, data, setStateValue } component const label parentElement.querySelector(label) const input parentElement.querySelector(input) if (!label || !input) return label.innerText data.label const nextValue data.value ?? if (input.value ! nextValue) { input.value nextValue } input.onkeydown e { if (e.key Enter) { setStateValue(value, e.target.value) } } }要点拆解水合侧data.value ?? 处理 Python 尚未传值的情况if (input.value ! nextValue)的条件赋值保护用户正在编辑时输入框的 DOM 状态不被覆盖这是“不打架”的关键。发射侧setStateValue(value, e.target.value)会把{ value: ... }这个扁平状态映射写回 Python。从 useHandleJsContent.ts 的源码可以看到setStateValue会读取当前状态、浅合并新键然后通过widgetMgr.setJsonValue以fromUser: true的标记提交到运行时触发一次重跑并持久化到 Session State。parentElement的查询范围当isolate_stylesTrue默认时 HTML 挂在 Shadow DOM 中parentElement是ShadowRootquerySelector在影子根内查找若设为False则直接操作主 DOM 树。Python 侧通过data把状态喂回前端Python 包装函数负责“读状态 → 算值 → 下发”每次脚本运行都执行这个闭环import streamlit as st _COMPONENT st.components.v2.component( interactive_text_input, html label fortxtEnter text:/label input idtxt typetext / , jsJS, # 上面的内联 JS 字符串 ) def interactive_text_input(*, label: str, initial_value: str, key: str): # 1) 从 Session State 读取当前组件状态如果存在 component_state st.session_state.get(key, {}) # 2) 计算 UI 想要显示的值 value component_state.get(value, initial_value) # 3) 通过 data 下发到前端 return _COMPONENT( keykey, data{label: label, value: value}, ) KEY my_text_input if st.button(Make it say Hello World): st.session_state.setdefault(KEY, {})[value] Hello World interactive_text_input(labelEnter something, initial_valueInitial Text, keyKEY)这段代码体现了三个关键机制均可在源码中找到对应实现组件注册与挂载分离st.components.v2.component(...)只负责注册返回可挂载的 callable实际挂载在调用_COMPONENT(...)时发生。注册逻辑见 components/v2/init.pyjs参数既可以是内联 JS 字符串也可以是已安装组件asset_dir下的路径/glob。状态读取st.session_state.get(key, {})读取的是该组件实例以key标识的扁平状态映射。组件挂载时Python 通过 main.py 中的register_widget注册状态 widget反序列化器BidiComponentSerde会把前端回传的 JSON 解析为字典见 serialization.py。跨 rerun 的双向环按钮处理器先改写 Session State → 重跑时包装函数读到新值 → 通过data下发 → JS 水合更新 DOM。这个环每跑一次脚本就闭合一次。值得注意的是脚本中只有on_key_change形式才会被识别为事件回调_bidi_component在 main.py 中只接受on_前缀且_change后缀的 kwarg。上面的例子故意不注册回调因为包装函数用st.session_state手动管理状态如果你希望状态键始终出现在返回值中则应在挂载时传入对应的on_value_change回调。default...何时使用以及为什么它可能失败default{...}是可选的。它的用途是当某个已挂载实例的状态键在 Session State 中缺失时由 Streamlit 代为初始化。使用规则default只作用于状态键state keys不作用于触发器trigger keys。触发器本质是一次性事件不存在“默认值”语义。default中的每个键在挂载时都必须有对应的on_key_change回调参数否则 Streamlit 直接抛异常。规范写法result _COMPONENT( keykey, data{value: value}, default{value: value}, on_value_changelambda: None, # 使用 default[value] 时必须提供 )为什么default需要配套回调源码给出了确凿答案在 _bidi_component 中挂载时会遍历default的每个键并校验其是否存在于已解析的回调映射中不匹配即抛出BidiComponentInvalidDefaultKeyError。这是因为“允许的状态键集合”正是由回调集合定义的——allowed_state_keys决定哪些键能进入用户可见的 Session State见 main.py。default实际生效的位置在序列化层BidiComponentSerde.deserialize在把前端值解析为字典后会对default中尚不存在的键补上默认值见 serialization.py。理解这一点有助于你判断该用哪种模式需要Python 每次运行都驱动 UI 值例如响应按钮、回调、外部状态→ 用受控模式不依赖default每轮从data下发需要首次挂载时给缺失状态一个初始值→ 用default同时记得补回调。Python → JS 水合初始一次性 vs 真正同步社区中常见两种水合写法理解它们的差别是避免“Python 改了但界面不更新”的关键。初始一次性水合initial-onlyJS 只在首次挂载时读取data.initialX之后不再响应。适合做初始化但不会反映 Python 后续的修改// 用 hasMounted 做守卫的话Python 的后续修改将无法传播到界面 if (typeof data?.initialText ! undefined !hasMountedForKey) { input.value String(data.initialText) } hasMounted[key] true仓库自带的 e2e 示例 basics.py 中的_STATEFUL_JS正是这种模式的真实样板它用模块级let hasMounted {}按 key 记录是否已挂载仅在首次时把data.initialRange/data.initialText写入控件之后只靠setStateValue向上发射——因为该示例的 Python 侧并不打算在运行中改写值所以这是合理的初始化用法。真正同步受控true syncJS 每次渲染都用data对账且仅在值变化时才写入 DOMconst nextValue data.value ?? if (input.value ! nextValue) input.value nextValue当 Python 需要在运行中更新 UI 时必须采用受控模式。原因在于useHandleJsContent的 effect 依赖数组包含data见 useHandleJsContent.ts只要 Python 传入的data引用/内容变化组件 JS 就会重新执行受控写法保证每次重跑后 DOM 与 Python 数据一致而 initial-only 写法会因守卫而跳过更新。Session State 时序不要在挂载后修改Streamlit 可能抛错如果你在同一个运行中、组件实例化之后才修改st.session_state.key.field。这是因为组件挂载时register_widget已经把该 key 的 widget 注册进当前运行的 Session State 管理流程见 main.py挂载后外部直接修改其内部字段会破坏 widget 值与注册状态的一致性约束。安全模式有两种在挂载之前修改状态把st.session_state[key][...] ...放在组件挂载调用上方的逻辑里例如放在更早执行的按钮处理器中——这正是本文示例代码的做法按钮处理器在interactive_text_input(...)之前执行先写状态、后挂载。分两轮运行先设置状态并触发 rerun在下一轮运行中再挂载组件。故障排查清单把上面的知识点浓缩成一份可直接对照的排查清单光标跳变 / 打字感觉卡顿检查 JS 是否只在input.value与data值不同时才赋值。无条件写入是光标冲突的头号原因。Python 更新没反映到界面确认每轮运行都通过data下发最新值若想实现真正同步避免使用 initial-only 水合守卫hasMounted。default抛异常确保default中的每个键都有对应的on_key_change回调参数回调集合定义了允许的状态键集合BidiComponentInvalidDefaultKeyError即由此触发。Session State 修改报错把st.session_state[key][...] ...移到脚本中更靠前的位置组件挂载之前或重构为两轮运行流程先设状态再 rerun。补充State 与 Trigger 的边界来自源码的事实为了让你在实际组件设计中少踩坑这里补充文档未展开、但源码明确规定的两个边界setTriggerValue在表单内被忽略。useHandleJsContent.ts 明确实现当组件渲染在st.form内时setTriggerValue直接 no-op 并打警告日志——因为 Streamlit 执行模型不允许表单内触发器应改用setStateValue配合表单提交按钮。触发器按事件聚合。Python 侧每个触发器事件都会生成内部聚合器 ID$$STREAMLIT_INTERNAL_KEY_{base}__{event}形态见 main.py前端回传的 payload 列表经 serialization.py 的deserialize_trigger_list归一化为列表后再按事件名映射到回调并暴露在ComponentResult中main.py。触发器键会被内部前缀隐藏不会暴露在面向用户的st.session_state中。如果组件在打包、主题或疑难杂症上还有问题可以继续阅读同目录下的 ccv2-packaged-components.md、ccv2-troubleshooting.md 与 session-state.md并在 e2e_playwright/bidi_components/basics.py 中查看可运行的完整端到端示例。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 安全版本深度解析：Policy 机制绕过漏洞修复与 OpenSSL 1.1.1v 升级)
