Mesop Button Toggle 组件完全指南：在 Python 中构建单选/多选切换按钮组

Mesop Button Toggle 组件完全指南在 Python 中构建单选/多选切换按钮组【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesopButton toggle按钮切换组是 Mesop 基于 Angular Material button toggle 封装的原生组件用于把一组按钮组织成互斥单选或多选的切换控件。它非常适合实现富文本工具栏加粗/斜体/下划线、筛选条件面板、视图模式切换等交互场景。读完本文你将掌握me.button_toggle的完整 API、单选/多选/禁用等状态控制、事件回调用法以及它从 Python 到前端 Angular 的底层数据流实现原理。Overview组件是什么Button toggle 的核心形态是一组并列的按钮用户点击后按钮进入选中高亮状态。它由两个层级组成组groupme.button_toggle本身负责管理选中状态、多选/单选模式与禁用逻辑按钮button组内每个可独立点击的ButtonToggleButton包含label展示文案与value选中时上报的值。Mesop 中该组件的 Python 侧定义位于 button_toggle.py通过register_native_component注册为原生组件前端由 Angular 的MatButtonToggleModule渲染见 button_toggle.ts。快速上手完整示例官方 demo 位于 demo/button_toggle.py实现了一个典型的格式工具栏from dataclasses import field import mesop as me me.stateclass class State: selected_values: list[str] field( default_factorylambda: [bold, underline] ) def load(e: me.LoadEvent): me.set_theme_mode(system) me.page( on_loadload, security_policyme.SecurityPolicy( allowed_iframe_parents[https://mesop-dev.github.io] ), path/button_toggle, ) def app(): state me.state(State) with me.box(styleme.Style(marginme.Margin.all(15))): me.button_toggle( valuestate.selected_values, buttons[ me.ButtonToggleButton(labelBold, valuebold), me.ButtonToggleButton(labelItalic, valueitalic), me.ButtonToggleButton(labelUnderline, valueunderline), ], multipleTrue, hide_selection_indicatorFalse, disabledFalse, on_changeon_change, styleme.Style(marginme.Margin(bottom20)), ) me.text(Select buttons: .join(state.selected_values)) def on_change(e: me.ButtonToggleChangeEvent): state me.state(State) state.selected_values e.values要点拆解状态驱动选中选中值存放在State.selected_values中默认选中bold与underline初始渲染时这两个按钮即为高亮态value传入的是状态变量组件是受控的——任何选中变化都会先触发on_change更新状态再通过状态回流完成界面刷新这是 Mesop 事件驱动模型的典型用法事件处理器on_change接收ButtonToggleChangeEvent从中取出e.values写回状态。API 详解button_toggle的函数签名与参数说明如下摘自 button_toggle.py参数类型默认值说明valuelist[str] \| str当前选中的值。传str时会被自动包装为单元素列表buttonsIterable[ButtonToggleButton]必填组内按钮列表on_changeCallable[[ButtonToggleChangeEvent], Any] \| NoneNone组内选中值变化时触发的事件回调multipleboolFalse是否允许多选。False为互斥单选模式disabledboolFalse是否禁用整个按钮组hide_selection_indicatorboolFalse是否隐藏选中指示器勾选标记styleStyle \| NoneNone组件样式如外边距等keystr \| NoneNone组件 key用于事件溯源详见 组件 key 说明辅助数据类ButtonToggleButton每个按钮由ButtonToggleButton数据类描述包含两个可选字段见 button_toggle.pylabel按钮上展示的文本内容value该按钮被选中时上报的取值。两者均允许为None实际使用时应保证value唯一以便事件回调能准确判断用户点了哪个按钮。事件ButtonToggleChangeEvent选中状态变化时触发ButtonToggleChangeEvent其关键成员见 button_toggle.pyvalues: list[str]变化后的全部选中值列表value属性快捷方式返回首个选中值列表为空时返回空字符串。在单选模式下直接使用e.value即可。注意values反映的是整组切换后的完整状态而非仅变化的单个按钮因此在多选模式下更新状态时应整体覆盖如 demo 中的state.selected_values e.values。单选与多选模式multiple参数决定组的行为模式官方 e2e 测试分别验证了两种模式见 button_toggle_test.ts单选模式multipleFalse单选用例见 single_button_toggle_app.py。此时value适合用单个字符串状态承载me.stateclass class State: selected_value: str bold事件回调使用e.value快捷属性即可拿到当前唯一选中项def on_change(e: me.ButtonToggleChangeEvent): state me.state(State) state.selected_value e.value该模式下点击按钮会替换当前选中项——点击Italic后bold自动取消选中这正是互斥单选的行为测试中断言点击 Italic 后显示Select button: italic。多选模式multipleTrue多选用例见 multiple_button_toggle_app.py。value传入list[str]on_change中通过e.values整体覆盖状态def on_change(e: me.ButtonToggleChangeEvent): state me.state(State) state.selected_values e.values多选模式下点击已选中按钮会将其取消选中测试中断言再次点击Bold后列表变为underline。适合做标签筛选多条件叠加类 UI。禁用与选中指示器禁用整个组disabledTruedisabledTrue时组内所有按钮均不可点击。e2e 的禁用用例见 disabled_button_toggle_app.py 与其测试断言点击 Bold 后选中值不变。注意该参数作用于整个组无法通过本组件 API 单独禁用组内某个按钮若需要精细化控制可考虑用me.button自行组装。隐藏选中指示器hide_selection_indicatorTrue该参数控制选中态的视觉标记勾选图标。在前端模板 button_toggle.ng.html 中它会同时映射到 Angular Material 的两个输入属性mat-button-toggle-group [hideMultipleSelectionIndicator]config().getHideSelectionIndicator() [hideSingleSelectionIndicator]config().getHideSelectionIndicator() [multiple]config().getMultiple() (change)onChangeEvent($event) 即无论单选还是多选勾选指示器的显隐都由这一个参数统一控制。视觉上更紧凑的工具栏通常设置hide_selection_indicatorTrue仅靠高亮底色区分选中态。底层原理Python 与 Angular 的数据流Proto 定义Python ↔ 前端的契约组件属性通过 protobuf 传输契约定义在 button_toggle.protomessage ButtonToggleType { repeated string value 1; repeated ButtonToggleButton buttons 2; optional bool multiple 3; optional bool disabled 4; optional bool hide_selection_indicator 5; optional string on_change_event_handler_id 6; } message ButtonToggleButton { optional string label 1; optional string value 2; } message ButtonToggleChangeEvent { repeated string values 1; }Python 侧的button_toggle()函数将参数组装为ButtonToggleTypeproto 后调用insert_component注入组件树其中value经过_format_value_field_proto归一化——空值返回[]字符串被包装成单元素列表见 button_toggle.pydef _format_value_field_proto(value: list[str] | str): if not value: return [] if isinstance(value, list): return value return [value]事件回传链路用户在浏览器点击按钮Angular 触发MatButtonToggleChange前端 button_toggle.ts 的onChangeEvent将选中值序列化为ButtonToggleChangeEventproto字符串值调用addValues多选数组则循环添加连同on_change_event_handler_id一起包装成UserEvent通过Channel发送给服务端服务端依据 handler id 找到注册的回调Python 侧由map_change_eventbutton_toggle.py通过ParseFromString反序列化字节还原出ButtonToggleChangeEvent(key..., values[...])并调用你的on_change函数回调更新State后新状态回流前端isCheckedbutton_toggle.ts比对value列表决定每个按钮的checked状态界面随之刷新。其中事件类型与映射函数通过register_event_mapper(ButtonToggleChangeEvent, map_change_event)建立关联。测试验证行为有据可依组件行为由 Playwright e2e 测试覆盖见 button_toggle_test.ts共三个用例用例验证点single selection单选模式下点击按钮互斥替换选中值始终为单一项multiple selection多选模式下可叠加选中、可取消选中列表整体更新disabled禁用状态下点击不改变选中值这些测试通过page.getByLabel(Bold)等断言驱动真实浏览器交互验证了从事件触发、状态更新到文本渲染的完整闭环可作为你自建应用的行为参考基线。小结me.button_toggle是 Mesop 构建工具栏、筛选器与视图切换等交互的高频组件。记住三条核心实践单选用multipleFalse 字符串状态 e.value多选用multipleTrue 列表状态 e.values整体覆盖选中值由状态驱动务必在on_change中回写状态否则组件不会随点击刷新需要紧凑工具栏时开启hide_selection_indicatorTrue需要锁定选项时设置disabledTrue。若需查看实时交互效果可在仓库中运行 demo 应用访问/button_toggle路由并参考 demo/button_toggle.py 与 button_toggle.proto 进一步深入。【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考