Textual Checkbox 組件完全指南從布爾狀態(tài)管理到交互定制【免費下載鏈接】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并結(jié)合源碼 src/textual/widgets/_checkbox.py、基類 src/textual/widgets/_toggle_button.py 與測試用例 tests/toggles/test_checkbox.py 展開帶你完整掌握 Textual 復(fù)選框組件的用法、事件模型與底層實現(xiàn)。Checkbox是 Textual 提供的一個輕量級復(fù)選框組件用于存儲一個布爾值True/False是構(gòu)建表單、設(shè)置頁、篩選器等界面時最常用的交互控件之一。本文將從零開始講解如何創(chuàng)建復(fù)選框、如何響應(yīng)其狀態(tài)變化事件、如何定制外觀樣式并深入到源碼層面剖析它的實現(xiàn)原理讓你在實戰(zhàn)中既能快速上手也能知其所以然。組件概覽Checkbox于 Textual 0.13.0 版本加入其定位非常簡單——存儲并展示一個布爾值。在組件特性上?可聚焦Focusable支持鍵盤操作可以被 Tab 鍵聚焦?非容器Not a Container不承擔(dān)布局容器職責(zé)不能作為其他控件的掛載點。從源碼結(jié)構(gòu)看Checkbox并不是從零實現(xiàn)的獨立控件而是繼承自內(nèi)部基類ToggleButton見 src/textual/widgets/_toggle_button.py。ToggleButton同時是Checkbox與RadioButton的公共核心因此復(fù)選框與單選按鈕在渲染、綁定、事件模型上高度同構(gòu)——復(fù)選框表示可獨立切換的布爾值單選按鈕則表示互斥選擇中的一項。# src/textual/widgets/_checkbox.py class Checkbox(ToggleButton): A check box widget that represents a boolean value.快速上手一個完整的示例應(yīng)用官方文檔在 docs/widgets/checkbox.md 中提供了一個展示復(fù)選框多種狀態(tài)的完整示例代碼位于 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; }示例的運行效果展示了復(fù)選框的各種形態(tài)純文本標(biāo)簽如Checkbox(Caladan)Emoji 標(biāo)簽Textual 支持富文本與 Emoji 簡寫:sweat:會被渲染為表情符號Rich 標(biāo)記標(biāo)簽[b]Giedi Prime[/b]使用粗體[magenta]Ginaz[/]使用洋紅色說明標(biāo)簽天然支持 markup 語法默認(rèn)勾選Checkbox(Grumman, True)、Checkbox(Novebruns, True)的第二個位置參數(shù)valueTrue使復(fù)選框初始即為選中狀態(tài)按 id 定位并聚焦idinitial_focus配合on_mount中的self.query_one(#initial_focus, Checkbox).focus()實現(xiàn)應(yīng)用啟動后自動聚焦指定復(fù)選框。在項目目錄下運行python docs/examples/widgets/checkbox.py即可看到該應(yīng)用的實際效果。復(fù)選框的選中項會顯示一個X標(biāo)記未選中項則為空白框體選中的標(biāo)簽顏色會變?yōu)閺娬{(diào)色。響應(yīng)式屬性Reactive AttributesCheckbox暴露了一個響應(yīng)式屬性value是組件唯一的公開狀態(tài)屬性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 的響應(yīng)式系統(tǒng)參見 docs/api/reactive.md其核心行為由watch_value方法驅(qū)動見 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))從這段實現(xiàn)可以看出每次value變化會觸發(fā)兩件事同步切換 CSS 類set_class(self.value, -on)根據(jù)新值添加或移除-on類。選中時組件掛上-on類未選中時移除默認(rèn)樣式表正是利用這個類來改變勾選標(biāo)記的顏色派發(fā) Changed 消息向消息隊列投遞Changed事件供應(yīng)用層監(jiān)聽。注意初始化時不會觸發(fā)事件構(gòu)造函數(shù)中有一段關(guān)鍵邏輯見 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上下文管理器屏蔽了初始賦值產(chǎn)生的Changed消息——在compose階段用valueTrue創(chuàng)建的復(fù)選框不會在掛載時觸發(fā)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 []三個復(fù)選框初始值分別為False/False/True對應(yīng)的-on類也同步匹配而事件列表為空——證明初始化不產(chǎn)生Changed消息。消息事件Checkbox.ChangedCheckbox的文檔中只列出了一個消息Checkbox.Changed當(dāng)復(fù)選框的值發(fā)生變化時觸發(fā)。在應(yīng)用類中通過約定命名的方法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并在此基礎(chǔ)上提供了兩個便捷屬性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觸發(fā)事件的復(fù)選框?qū)嵗蓮钠渖献x取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), ]注意該測試中的事件處理函數(shù)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. |也就是說在復(fù)選框獲得焦點時按下Enter或空格鍵即可切換選中狀態(tài)綁定使用showFalse因此不會出現(xiàn)在 Footer 的按鍵提示欄中綁定的 action 為toggle_button對應(yīng)基類方法action_toggle_button見 src/textual/widgets/_toggle_button.py內(nèi)部調(diào)用toggle()方法取反當(dāng)前值。除了鍵盤鼠標(biāo)點擊同樣可以切換狀態(tài)?；悓崿F(xiàn)了點擊事件處理器見 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會被響應(yīng)式系統(tǒng)自動調(diào)用進而同步-on類并派發(fā)Changed消息。因此鼠標(biāo)點擊、鍵盤快捷鍵與編程式調(diào)用toggle()最終走的是同一條狀態(tài)更新鏈路。組件類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 類不同它們作用于控件內(nèi)部渲染的子區(qū)域用于細(xì)分樣式控制。在 CSS 中針對某個復(fù)選框定制時可以這樣使用Checkbox .toggle--button { color: $accent; } Checkbox .toggle--label { text-style: bold; }從渲染實現(xiàn)看見 src/textual/widgets/_toggle_button.pyrender()方法會分別獲取toggle--button與toggle--label的視覺樣式拼裝出「按鈕 標(biāo)簽」的完整內(nèi)容其中按鈕部分由三個字符段組成BUTTON_LEFT ?、BUTTON_INNER X、BUTTON_RIGHT ▌見源碼 src/textual/widgets/_toggle_button.py左右側(cè)字符使用與背景融合的side_style從而呈現(xiàn)出一體化的勾選塊效果。構(gòu)造函數(shù)參數(shù)詳解Checkbox的完整構(gòu)造參數(shù)定義在基類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:各參數(shù)說明如下參數(shù)類型默認(rèn)值說明labelContentText復(fù)選框的文本標(biāo)簽支持 Rich 標(biāo)記markup與 Emoji 簡寫valueboolFalse初始值True表示選中注意初始化不觸發(fā)Changed消息button_firstboolTrue勾選塊是否位于標(biāo)簽之前False時按鈕排在標(biāo)簽之后namestr \| NoneNone組件名稱idstr \| NoneNoneDOM 中的唯一標(biāo)識配合query_one定位使用classesstr \| NoneNone附加的 CSS 類disabledboolFalse是否禁用禁用后不可交互tooltipRenderableType \| NoneNone懸停提示內(nèi)容compactboolFalse是否啟用緊湊模式見下文其中l(wèi)abel的處理值得注意見 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標(biāo)簽會被轉(zhuǎn)換為Content對象并僅保留首行first_line、去除尾部空白——多行標(biāo)簽會被自動截斷為單行且支持運行期通過label屬性重新賦值賦值時會觸發(fā)refresh(layoutTrue)重繪。緊湊模式compactToggleButton還暴露了一個響應(yīng)式屬性compact見 src/textual/widgets/_toggle_button.pycompact: reactive[bool] reactive(False, toggle_class-textual-compact) Enable compact display?將compactTrue傳入構(gòu)造函數(shù)或在運行期設(shè)置checkbox.compact True組件會掛上-textual-compact類對應(yīng)的默認(rèn) CSS 會去掉邊框與內(nèi)邊距見 src/textual/widgets/_toggle_button.py使復(fù)選框在表格、列表等空間緊湊的場景下占用更小。樣式定制與默認(rèn) CSSCheckbox的默認(rèn)外觀定義在基類的DEFAULT_CSS中見 src/textual/widgets/_toggle_button.py核心規(guī)則如下ToggleButton { width: auto; border: tall $border-blurred; padding: 0 1; background: $surface; text-wrap: nowrap; text-overflow: ellipsis; pointer: pointer; ... }要點解讀尺寸width: auto讓復(fù)選框?qū)挾入S內(nèi)容自適應(yīng)text-wrap: nowrap防止標(biāo)簽換行過長文本以省略號截斷邊框border: tall $border-blurred使用雙線模糊邊框聚焦時切換為$border高亮指針pointer: pointer讓鼠標(biāo)懸停時顯示手型指針提示可點擊選中態(tài):on即掛有-on類的狀態(tài)此時勾選塊前景色變?yōu)?text-success見 src/textual/widgets/_toggle_button.py聚焦態(tài):focus時邊框加粗并給標(biāo)簽套上$block-cursor-*背景色懸停blur:hover時標(biāo)簽背景變?yōu)?block-hover-backgroundANSI 終端適配:ansi規(guī)則為不支持真彩色的終端提供了降級配色見 src/textual/widgets/_toggle_button.py。在業(yè)務(wù)應(yīng)用中覆蓋這些默認(rèn)樣式時可以基于組件類或狀態(tài)類編寫更高優(yōu)先級的規(guī)則例如Checkbox { background: $panel; padding: 1 2; } Checkbox.-on .toggle--button { color: $success; text-style: bold; }在真實界面中的組合用法Textual 自帶的演示應(yīng)用 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; }可以看出復(fù)選框經(jīng)常被放進VerticalGroup、HorizontalGroup等容器中通過1fr均分寬度實現(xiàn)整齊的列表布局。選擇建議當(dāng)需要多個可獨立開/關(guān)的布爾開關(guān)時用Checkbox當(dāng)需要一組互斥選項、只能選其一時用 RadioButton 配合RadioSet。二者共享ToggleButton基類因此本文介紹的事件模型、綁定方式與組件類體系對單選按鈕同樣適用。常見實戰(zhàn)模式小結(jié)編程式取值/設(shè)值直接讀寫checkbox.value或調(diào)用checkbox.toggle()取反響應(yīng)式系統(tǒng)會自動同步界面。響應(yīng)變化在應(yīng)用或容器上定義on_checkbox_changed(self, event: Checkbox.Changed)通過event.checkbox.id區(qū)分是哪個復(fù)選框發(fā)生了變化。動態(tài)修改標(biāo)簽checkbox.label 新標(biāo)簽即可熱更新標(biāo)簽文本無需重建組件。定位復(fù)選框self.query_one(#some_id, Checkbox)按 id 獲取實例self.query(Checkbox)獲取全部復(fù)選框。禁用交互Checkbox(只讀項, disabledTrue)使復(fù)選框不可點擊、不可聚焦。測試驅(qū)動使用App.run_test()配合Pilot見 docs/api/pilot.md可以在無終端環(huán)境下斷言value、-on類與事件序列官方測試 tests/toggles/test_checkbox.py 就是可直接參考的范例。結(jié)語Checkbox雖然只存儲一個布爾值但其背后凝聚了 Textual 響應(yīng)式屬性、消息事件、鍵位綁定、組件類樣式與 ANSI 適配等多套核心機制。通過本文你不僅掌握了它的全部 API 用法——value屬性、Checkbox.Changed事件、enter/space鍵位、toggle--button/toggle--label組件類與完整構(gòu)造參數(shù)——也借助 src/textual/widgets/_toggle_button.py 與 tests/toggles/test_checkbox.py 理解了其狀態(tài)同步鏈路與初始化語義。下一步你可以直接運行示例應(yīng)用或參考 docs/widgets/checkbox.md 及 widget 總覽 探索更多組件?！久赓M下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考