Textual Checkbox 组件完全指南从布尔状态管理到交互定制【免费下载链接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.项目地址: https://gitcode.com/gh_mirrors/te/textual本文基于 Textual 官方文档 docs/widgets/checkbox.md并结合源码 src/textual/widgets/_checkbox.py、基类 src/textual/widgets/_toggle_button.py 与测试用例 tests/toggles/test_checkbox.py 展开带你完整掌握 Textual 复选框组件的用法、事件模型与底层实现。Checkbox是 Textual 提供的一个轻量级复选框组件用于存储一个布尔值True/False是构建表单、设置页、筛选器等界面时最常用的交互控件之一。本文将从零开始讲解如何创建复选框、如何响应其状态变化事件、如何定制外观样式并深入到源码层面剖析它的实现原理让你在实战中既能快速上手也能知其所以然。组件概览Checkbox于 Textual 0.13.0 版本加入其定位非常简单——存储并展示一个布尔值。在组件特性上✅可聚焦Focusable支持键盘操作可以被 Tab 键聚焦❌非容器Not a Container不承担布局容器职责不能作为其他控件的挂载点。从源码结构看Checkbox并不是从零实现的独立控件而是继承自内部基类ToggleButton见 src/textual/widgets/_toggle_button.py。ToggleButton同时是Checkbox与RadioButton的公共核心因此复选框与单选按钮在渲染、绑定、事件模型上高度同构——复选框表示可独立切换的布尔值单选按钮则表示互斥选择中的一项。# src/textual/widgets/_checkbox.py class Checkbox(ToggleButton): A check box widget that represents a boolean value.快速上手一个完整的示例应用官方文档在 docs/widgets/checkbox.md 中提供了一个展示复选框多种状态的完整示例代码位于 docs/examples/widgets/checkbox.py样式表位于 docs/examples/widgets/checkbox.tcss。完整代码如下from textual.app import App, ComposeResult from textual.containers import VerticalScroll from textual.widgets import Checkbox class CheckboxApp(App[None]): CSS_PATH checkbox.tcss def compose(self) - ComposeResult: with VerticalScroll(): yield Checkbox(Arrakis :sweat:) yield Checkbox(Caladan) yield Checkbox(Chusuk) yield Checkbox([b]Giedi Prime[/b]) yield Checkbox([magenta]Ginaz[/]) yield Checkbox(Grumman, True) yield Checkbox(Kaitain, idinitial_focus) yield Checkbox(Novebruns, True) def on_mount(self): self.query_one(#initial_focus, Checkbox).focus() if __name__ __main__: CheckboxApp().run()配套的样式表Screen { align: center middle; } VerticalScroll { width: auto; height: auto; background: $boost; padding: 2; }示例的运行效果展示了复选框的各种形态纯文本标签如Checkbox(Caladan)Emoji 标签Textual 支持富文本与 Emoji 简写:sweat:会被渲染为表情符号Rich 标记标签[b]Giedi Prime[/b]使用粗体[magenta]Ginaz[/]使用洋红色说明标签天然支持 markup 语法默认勾选Checkbox(Grumman, True)、Checkbox(Novebruns, True)的第二个位置参数valueTrue使复选框初始即为选中状态按 id 定位并聚焦idinitial_focus配合on_mount中的self.query_one(#initial_focus, Checkbox).focus()实现应用启动后自动聚焦指定复选框。在项目目录下运行python docs/examples/widgets/checkbox.py即可看到该应用的实际效果。复选框的选中项会显示一个X标记未选中项则为空白框体选中的标签颜色会变为强调色。响应式属性Reactive AttributesCheckbox暴露了一个响应式属性value是组件唯一的公开状态属性NameTypeDefaultDescriptionvalueboolFalseThe value of the checkbox.该属性在源码中定义为见 src/textual/widgets/_toggle_button.pyvalue: reactive[bool] reactive(False, initFalse) The value of the button. True for on, False for off.reactive是 Textual 的响应式系统参见 docs/api/reactive.md其核心行为由watch_value方法驱动见 src/textual/widgets/_toggle_button.pydef watch_value(self) - None: React to the value being changed. ... self.set_class(self.value, -on) self.post_message(self.Changed(self, self.value))从这段实现可以看出每次value变化会触发两件事同步切换 CSS 类set_class(self.value, -on)根据新值添加或移除-on类。选中时组件挂上-on类未选中时移除默认样式表正是利用这个类来改变勾选标记的颜色派发 Changed 消息向消息队列投递Changed事件供应用层监听。注意初始化时不会触发事件构造函数中有一段关键逻辑见 src/textual/widgets/_toggle_button.py# NOTE: Dont send a Changed message in response to the initial set. with self.prevent(self.Changed): self.value value即通过prevent上下文管理器屏蔽了初始赋值产生的Changed消息——在compose阶段用valueTrue创建的复选框不会在挂载时触发on_checkbox_changed。这一点在测试 tests/toggles/test_checkbox.py 中也有明确断言async def test_checkbox_initial_state() - None: The initial states of the check boxes should be as we specified. async with CheckboxApp().run_test() as pilot: assert [box.value for box in pilot.app.query(Checkbox)] [False, False, True] assert [box.has_class(-on) for box in pilot.app.query(Checkbox)] [ False, False, True, ] assert pilot.app.events_received []三个复选框初始值分别为False/False/True对应的-on类也同步匹配而事件列表为空——证明初始化不产生Changed消息。消息事件Checkbox.ChangedCheckbox的文档中只列出了一个消息Checkbox.Changed当复选框的值发生变化时触发。在应用类中通过约定命名的方法on_checkbox_changed即可接收并处理该事件例如class MyApp(App): def on_checkbox_changed(self, event: Checkbox.Changed) - None: self.notify(fCheckbox changed to: {event.value})从源码见 src/textual/widgets/_checkbox.py来看Checkbox.Changed继承自ToggleButton.Changed并在此基础上提供了两个便捷属性class Changed(ToggleButton.Changed): Posted when the value of the checkbox changes. ... property def checkbox(self) - Checkbox: The checkbox that was changed. assert isinstance(self._toggle_button, Checkbox) return self._toggle_button property def control(self) - Checkbox: An alias for Changed.checkbox. return self.checkbox事件对象可用属性汇总属性类型说明event.valuebool变化后的值event.checkboxCheckbox触发事件的复选框实例可从其上读取id、value等event.controlCheckboxcheckbox的别名便于与 Textual 其他控件的事件接口保持一致测试 tests/toggles/test_checkbox.py 验证了消息携带的信息以及checkbox与control的等价性async def test_checkbox_toggle() - None: Test the status of the check boxes after theyve been toggled. async with CheckboxApp().run_test() as pilot: for box in pilot.app.query(Checkbox): box.toggle() assert [box.value for box in pilot.app.query(Checkbox)] [True, True, False] assert [box.has_class(-on) for box in pilot.app.query(Checkbox)] [ True, True, False, ] await pilot.pause() assert pilot.app.events_received [ (cb1, True, True), (cb2, True, True), (cb3, False, True), ]注意该测试中的事件处理函数tests/toggles/test_checkbox.py同时用到了event.checkbox.id、event.checkbox.value以及event.checkbox event.control三者完整覆盖了事件对象的全部接口。键位绑定BindingsCheckbox继承自ToggleButton其键位绑定定义在基类中见 src/textual/widgets/_toggle_button.pyBINDINGS: ClassVar[list[BindingType]] [ Binding(enter,space, toggle_button, Toggle, showFalse), ]| Key(s) | Description | | :- | :- | | enter, space | Toggle the value. |也就是说在复选框获得焦点时按下Enter或空格键即可切换选中状态绑定使用showFalse因此不会出现在 Footer 的按键提示栏中绑定的 action 为toggle_button对应基类方法action_toggle_button见 src/textual/widgets/_toggle_button.py内部调用toggle()方法取反当前值。除了键盘鼠标点击同样可以切换状态。基类实现了点击事件处理器见 src/textual/widgets/_toggle_button.pyasync def _on_click(self, _: Click) - None: Toggle the value of the widget when clicked with the mouse. self.toggle()而toggle()本身只做一件事见 src/textual/widgets/_toggle_button.pydef toggle(self) - Self: Toggle the value of the widget. ... self.value not self.value return selfvalue变化后前面提到的watch_value会被响应式系统自动调用进而同步-on类并派发Changed消息。因此鼠标点击、键盘快捷键与编程式调用toggle()最终走的是同一条状态更新链路。组件类Component ClassesCheckbox的外观由两个组件类Component Classes控制它们同样继承自ToggleButton见 src/textual/widgets/_toggle_button.pyCOMPONENT_CLASSES: ClassVar[set[str]] { toggle--button, toggle--label, }| Class | Description | | :- | :- | |toggle--button| Targets the toggle button itself. | |toggle--label| Targets the text label of the toggle button. |组件类与普通 CSS 类不同它们作用于控件内部渲染的子区域用于细分样式控制。在 CSS 中针对某个复选框定制时可以这样使用Checkbox .toggle--button { color: $accent; } Checkbox .toggle--label { text-style: bold; }从渲染实现看见 src/textual/widgets/_toggle_button.pyrender()方法会分别获取toggle--button与toggle--label的视觉样式拼装出「按钮 标签」的完整内容其中按钮部分由三个字符段组成BUTTON_LEFT ▐、BUTTON_INNER X、BUTTON_RIGHT ▌见源码 src/textual/widgets/_toggle_button.py左右侧字符使用与背景融合的side_style从而呈现出一体化的勾选块效果。构造函数参数详解Checkbox的完整构造参数定义在基类ToggleButton.__init__中见 src/textual/widgets/_toggle_button.pydef __init__( self, label: ContentText , value: bool False, button_first: bool True, *, name: str | None None, id: str | None None, classes: str | None None, disabled: bool False, tooltip: RenderableType | None None, compact: bool False, ) - None:各参数说明如下参数类型默认值说明labelContentText复选框的文本标签支持 Rich 标记markup与 Emoji 简写valueboolFalse初始值True表示选中注意初始化不触发Changed消息button_firstboolTrue勾选块是否位于标签之前False时按钮排在标签之后namestr \| NoneNone组件名称idstr \| NoneNoneDOM 中的唯一标识配合query_one定位使用classesstr \| NoneNone附加的 CSS 类disabledboolFalse是否禁用禁用后不可交互tooltipRenderableType \| NoneNone悬停提示内容compactboolFalse是否启用紧凑模式见下文其中label的处理值得注意见 src/textual/widgets/_toggle_button.pydef _make_label(self, label: ContentText) - Content: Make label content. ... label Content.from_text(label).first_line.rstrip() return label标签会被转换为Content对象并仅保留首行first_line、去除尾部空白——多行标签会被自动截断为单行且支持运行期通过label属性重新赋值赋值时会触发refresh(layoutTrue)重绘。紧凑模式compactToggleButton还暴露了一个响应式属性compact见 src/textual/widgets/_toggle_button.pycompact: reactive[bool] reactive(False, toggle_class-textual-compact) Enable compact display?将compactTrue传入构造函数或在运行期设置checkbox.compact True组件会挂上-textual-compact类对应的默认 CSS 会去掉边框与内边距见 src/textual/widgets/_toggle_button.py使复选框在表格、列表等空间紧凑的场景下占用更小。样式定制与默认 CSSCheckbox的默认外观定义在基类的DEFAULT_CSS中见 src/textual/widgets/_toggle_button.py核心规则如下ToggleButton { width: auto; border: tall $border-blurred; padding: 0 1; background: $surface; text-wrap: nowrap; text-overflow: ellipsis; pointer: pointer; ... }要点解读尺寸width: auto让复选框宽度随内容自适应text-wrap: nowrap防止标签换行过长文本以省略号截断边框border: tall $border-blurred使用双线模糊边框聚焦时切换为$border高亮指针pointer: pointer让鼠标悬停时显示手型指针提示可点击选中态:on即挂有-on类的状态此时勾选块前景色变为$text-success见 src/textual/widgets/_toggle_button.py聚焦态:focus时边框加粗并给标签套上$block-cursor-*背景色悬停blur:hover时标签背景变为$block-hover-backgroundANSI 终端适配:ansi规则为不支持真彩色的终端提供了降级配色见 src/textual/widgets/_toggle_button.py。在业务应用中覆盖这些默认样式时可以基于组件类或状态类编写更高优先级的规则例如Checkbox { background: $panel; padding: 1 2; } Checkbox.-on .toggle--button { color: $success; text-style: bold; }在真实界面中的组合用法Textual 自带的演示应用 src/textual/demo/widgets.py 展示了Checkbox与RadioButton、RadioSet的典型组合场景class Checkboxes(containers.VerticalGroup): Demonstrates Checkboxes. DEFAULT_CSS Checkboxes { height: auto; Checkbox, RadioButton { width: 1fr; } ... } def compose(self) - ComposeResult: yield Markdown(self.CHECKBOXES_MD) yield Checkbox(A Checkbox) yield RadioButton(A Radio Button) yield RadioSet( Amanda, Connor MacLeod, ... )从该示例的 CSSCheckbox, RadioButton { width: 1fr; }可以看出复选框经常被放进VerticalGroup、HorizontalGroup等容器中通过1fr均分宽度实现整齐的列表布局。选择建议当需要多个可独立开/关的布尔开关时用Checkbox当需要一组互斥选项、只能选其一时用 RadioButton 配合RadioSet。二者共享ToggleButton基类因此本文介绍的事件模型、绑定方式与组件类体系对单选按钮同样适用。常见实战模式小结编程式取值/设值直接读写checkbox.value或调用checkbox.toggle()取反响应式系统会自动同步界面。响应变化在应用或容器上定义on_checkbox_changed(self, event: Checkbox.Changed)通过event.checkbox.id区分是哪个复选框发生了变化。动态修改标签checkbox.label 新标签即可热更新标签文本无需重建组件。定位复选框self.query_one(#some_id, Checkbox)按 id 获取实例self.query(Checkbox)获取全部复选框。禁用交互Checkbox(只读项, disabledTrue)使复选框不可点击、不可聚焦。测试驱动使用App.run_test()配合Pilot见 docs/api/pilot.md可以在无终端环境下断言value、-on类与事件序列官方测试 tests/toggles/test_checkbox.py 就是可直接参考的范例。结语Checkbox虽然只存储一个布尔值但其背后凝聚了 Textual 响应式属性、消息事件、键位绑定、组件类样式与 ANSI 适配等多套核心机制。通过本文你不仅掌握了它的全部 API 用法——value属性、Checkbox.Changed事件、enter/space键位、toggle--button/toggle--label组件类与完整构造参数——也借助 src/textual/widgets/_toggle_button.py 与 tests/toggles/test_checkbox.py 理解了其状态同步链路与初始化语义。下一步你可以直接运行示例应用或参考 docs/widgets/checkbox.md 及 widget 总览 探索更多组件。【免费下载链接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.项目地址: https://gitcode.com/gh_mirrors/te/textual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考