用途:当 Streamlit 内置 UI 无法满足需求时,用 Custom Components v2(CCv2)构建可复用的交互组件,从单文件内联 HTML 到完整打包前端应用。
主要能力:Python 通过 st.components.v2.component(...) 注册组件并获得挂载函数;前端默认导出函数接收 { data, key, name, parentElement, setStateValue, setTriggerValue };JS 用 setStateValue 持久化状态、setTriggerValue 触发事件,Python 通过 data=... 回填 UI,形成双向循环。支持 on_<key>_change 回调、default 默认值、layout 宽高、isolate_styles 样式隔离与 --st-* 主题变量。
使用方式:内联模式直接传 html/css/js 字符串,适合单文件原型;打包模式需从官方 component-template v2 生成,将构建产物放入 Python 包并按 asset_dir 相对路径/glob 引用,用 streamlit run 验证。建议声明一次组件并封装成自有 Python API。
限制:严禁使用 v1 API,包括 st.components.v1、declare_component、components.html、Streamlit.setComponentValue/setFrameHeight/setComponentReady、window.Streamlit、postMessage 及 streamlit-component-lib。打包组件必须基于官方模板,不得手工搭建脚手架;js/css glob 须精确匹配一个文件。内联 JS/CSS 应多行书写,查询应基于 parentElement。具体版本、收费与平台信息暂未提供。