Kivy 實(shí)用代碼片段指南自定義控件、線程安全 UI 與異步工作流實(shí)戰(zhàn)【免費(fèi)下載鏈接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS項(xiàng)目地址: https://gitcode.com/gh_mirrors/ki/kivy本篇技術(shù)指南以 Kivy 官方入門文檔中的 Snippets 片段集為主體逐條剖析六個(gè)可直接復(fù)用的實(shí)戰(zhàn)片段自定義控件封裝、mainthread線程安全更新 UI、基于 Trio 的異步事件循環(huán)、通過EventDispatcher自定義事件與插件、用 KV 語(yǔ)言組織跨屏幕工作流以及在 Windows 上也能運(yùn)行的 Flask 內(nèi)嵌方案。讀完本文你將掌握這些片段背后的 Kivy 核心機(jī)制事件系統(tǒng)、屬性綁定、時(shí)鐘調(diào)度并能直接復(fù)制到自己的項(xiàng)目中運(yùn)行。Snippets 片段集是什么在 Kivy 文檔的入門Getting Started章節(jié)中Snippets是一組由社區(qū)貢獻(xiàn)的、短小精悍的即插即用代碼片段覆蓋了日常開發(fā)中最容易踩坑的場(chǎng)景如何組織自定義控件、如何安全地在子線程中更新界面、如何接入trio異步生態(tài)、如何自定義事件讓 KV 代碼更簡(jiǎn)潔以及如何把 Web 服務(wù)嵌入桌面應(yīng)用。其組織方式比較特殊入口文檔 doc/sources/gettingstarted/snippets.rst 本身只包含用于渲染輪播carousel的 HTML 樣式與對(duì)_code_snippets_slides.html的引用真正的片段正文存放在 doc/sources/snippets_slides/ 目錄下由 doc/sources/snippets_slides.js 負(fù)責(zé)按需異步加載loadSlideContent通過fetch拉取每個(gè)data-src對(duì)應(yīng)的 HTML 并注入.rst-content容器實(shí)現(xiàn)輪播切換時(shí)的懶加載與卸載。因此閱讀這些片段的完整內(nèi)容應(yīng)直接查看snippets_slides目錄下的各.rst文件。片段一自定義控件 CustomWidget第一個(gè)片段 custom_widgets.rst 演示了如何編寫自己的控件把純 Python 邏輯從 KV 腳本中剝離出來讓項(xiàng)目保持整潔、易于維護(hù)。片段給出的實(shí)踐原則是不要把大段 Python 塞進(jìn) KV 腳本自定義控件通常是更好控制代碼、區(qū)分短任務(wù)與長(zhǎng)任務(wù)的最佳選擇。# Filepath: libs/customwidget.py from kivy.lang import Builder from kivy.properties import ColorProperty from kivy.uix.behaviors import ButtonBehavior from kivy.uix.widget import Widget __all__ (CustomWidget,) Builder.load_string( CustomWidget: on_release: print(Short code goes here) # Remove this line if you are using the call from the Python script itself canvas.before: Color: rgba: self.color Rectangle: size: self.size pos: self.pos ) class CustomWidget(ButtonBehavior, Widget): color ColorProperty((.5, .5, .5, .8)) def on_release(self): print(Long code goes here) # remove this definition if you are instead using on_release from your KV code這個(gè)片段的關(guān)鍵點(diǎn)在于多重繼承組合能力CustomWidget繼承自ButtonBehavior與Widget。ButtonBehavior實(shí)現(xiàn)在 kivy/uix/behaviors/button.py是一個(gè)不負(fù)責(zé)繪制、只提供按下/釋放交互行為的 Mixin 類它與Widget組合即可得到一個(gè)帶按鈕語(yǔ)義的自繪控件而無需引入完整的Button。ColorProperty聲明式屬性color ColorProperty((.5, .5, .5, .8))是 Kivy 屬性系統(tǒng)的應(yīng)用——屬性的每次賦值都會(huì)自動(dòng)觸發(fā)綁定刷新KV 中的Color: rgba: self.color會(huì)隨屬性變化自動(dòng)重繪無需手寫 setter。KV 內(nèi)聯(lián)與 Python 回調(diào)的兩種用法KV 模板里用on_release: print(...)處理短邏輯Python 類里再定義同名on_release方法處理長(zhǎng)邏輯二者保留其一即可注釋里已明確說明如何取舍。使用方式有兩種# 在 Python 腳本中導(dǎo)入 from libs.customwidget import CustomWidget# 在 KV 語(yǔ)言中導(dǎo)入 #:import CustomWidget libs.customwidget.CustomWidget導(dǎo)入之后就可以結(jié)合 Kivy 的Factory機(jī)制kivy/factory.py在任意位置實(shí)例化或繼承該控件。這與 Kivy 文檔對(duì) Factory 的定位一致它讓你在 KV 中按名稱注冊(cè)類從而解耦類定義與使用位置。片段二子線程中安全更新 UImainthreadthreading_example.rst 展示了 Kivy 中最常見的并發(fā)陷阱UI 只能在主線程中修改子線程拿到數(shù)據(jù)后必須切回主線程再更新界面。片段的核心武器是kivy.clock.mainthread裝飾器。import threading import time from kivy.clock import mainthread from kivy.lang import Builder from kivy.properties import NumericProperty, StringProperty from kivy.uix.boxlayout import BoxLayout __all__ (MyBL,) class MyBL(BoxLayout): counter NumericProperty() data_label StringProperty(Nothing yet!) def __init__(self, **kwargs): super().__init__(**kwargs) threading.Thread(targetself.get_data).start() def get_data(self): while App.get_running_app(): # get data here # sock.recv(1024) or how you do it time.sleep(1) # if you change the UI you need to do it on main thread self.set_data_label(self.counter) self.counter 1 mainthread def set_data_label(self, counter: int): self.data_label str(counter) Builder.load_string( MyBL: Label: font_size: 30sp text: Some Data Label: font_size: 30sp text: root.data_label ) if __name__ __main__: from kivy.app import App class MyApp(App): def build(self): return MyBL() MyApp().run()從源碼層面看mainthread定義在 kivy/clock.pydef mainthread(func): Decorator that will schedule the call of the function for the next available frame in the mainthread. It can be useful when you use :class:~kivy.network.urlrequest.UrlRequest or when you do Thread ...也就是說被mainthread裝飾的方法調(diào)用時(shí)并不會(huì)立即執(zhí)行而是被調(diào)度到主線程的下一個(gè)可用幀中運(yùn)行。這保證了data_label這類屬性對(duì)界面的更新發(fā)生在主線程避免跨線程直接操作 UI 引發(fā)的競(jìng)態(tài)與崩潰。片段中的幾個(gè)工程細(xì)節(jié)值得注意threading.Thread(targetself.get_data).start()在__init__里啟動(dòng)后臺(tái)線程模擬sock.recv(1024)這類阻塞式數(shù)據(jù)采集循環(huán)條件while App.get_running_app()讓線程在應(yīng)用退出時(shí)自然結(jié)束避免僵尸線程counter與data_label分別使用NumericProperty和StringProperty定義于 kivy/properties.pyxKV 中text: root.data_label會(huì)自動(dòng)隨屬性變化刷新需要說明的是片段中的App是在if __name__ __main__分支內(nèi)導(dǎo)入的實(shí)際使用時(shí)應(yīng)把from kivy.app import App移到模塊頂部。片段三用 Trio 運(yùn)行異步 Kivy 應(yīng)用async_with_trio.rst 演示了如何把 Kivy 的事件循環(huán)交給trio結(jié)構(gòu)化并發(fā)框架托管。Kivy 從 2.0 開始原生支持異步事件循環(huán)async_run并允許通過async_lib參數(shù)選擇asyncio或trio作為底層實(shí)現(xiàn)。import trio from kivy.app import App from kivy.uix.label import Label class AsyncApp(App): def build(self): return Label(textHello Kivy) async def async_run(self): async with trio.open_nursery() as nursery: self.nursery nursery await super().async_run(async_libtrio) nursery.cancel_scope.cancel() if __name__ __main__: trio.run(AsyncApp().async_run)運(yùn)行方式是trio.run(AsyncApp().async_run)以trio.run作為程序入口在async_run內(nèi)打開一個(gè) nurserytrio 的任務(wù)作用域再調(diào)用super().async_run(async_libtrio)讓 Kivy 在 trio 的循環(huán)中運(yùn)行。當(dāng) Kivy 退出時(shí)nursery.cancel_scope.cancel()負(fù)責(zé)取消其余任務(wù)保證結(jié)構(gòu)化并發(fā)的清理語(yǔ)義。倉(cāng)庫(kù)自帶的 examples/async/trio_basic.py 與 examples/async/trio_advanced.py 展示了更完整的 trio 用法在子任務(wù)中定期通過Clock更新界面、與 Kivy 事件循環(huán)協(xié)作可作為深入學(xué)習(xí)的參照。Kivy 官方也將其作為一等公民支持App.async_run的async_lib參數(shù)即用于在asyncio與trio之間切換。片段四基于 EventDispatcher 的自定義插件/事件custom_plugins.rst 解決了一個(gè)常見的 Python 陷阱普通類無法與 Kivy 的控件/布局多重繼承。Kivy 的控件體系建立在EventDispatcher實(shí)現(xiàn)在 kivy/_event.pyx 編譯產(chǎn)物之上接口見 kivy/event.py之上因此可復(fù)用邏輯也應(yīng)從它派生。# Filepath: libs/customevent.py from kivy.event import EventDispatcher from kivy.properties import ColorProperty __all__ (CustomEvent,) class CustomEvent(EventDispatcher): color ColorProperty((.5, .5, .5, .8)) def is_going_to_happen(self): print(Kivy rules!)使用方式# 在 Python 腳本中導(dǎo)入 from libs.customevent import CustomEvent# 與布局/控件多重繼承 class OtherLayout(BoxLayout, CustomEvent): ...為什么必須用EventDispatcher片段原文的解釋是有時(shí)你無法用普通類class MyClass:與布局、控件做多重繼承。其根源在于Kivy 的屬性Property系統(tǒng)在類創(chuàng)建時(shí)通過元類EventDispatcher的 metaclass為每個(gè)屬性生成_event_properties等內(nèi)部注冊(cè)信息Widget、Layout等基類也依賴這套機(jī)制完成事件綁定與屬性通知。只有同樣基于EventDispatcher的類才能與其他 Kivy 控件在 MRO 上正確協(xié)作、讓ColorProperty等屬性在多重繼承下正常工作。這也是自定義插件的通用模式把可復(fù)用的狀態(tài)與行為收斂進(jìn)一個(gè)EventDispatcher子類再通過多重繼承混入任意布局或控件。片段五用 KV 語(yǔ)言編排應(yīng)用級(jí)工作流custom_workflows_with_kvlang.rst 展示了一種應(yīng)用級(jí)工作流組織方式用ScreenManager 自定義事件把屏幕跳轉(zhuǎn)邏輯全部寫在 KV 里Python 只負(fù)責(zé)聲明事件。這是片段集中最能體現(xiàn) Kivy 聲明式風(fēng)格的一個(gè)。ScreenManager: id: screenmanager IdleScreen: name: idle on_press: screenmanager.current date_selection DateSelectionScreen: name: date_selection catalog: app.catalog on_submit: app.departure_datetime self.departure_datetime app.cart.filter_by_deadline(self.departure_datetime) screenmanager.current browse BrowseScreen: name: browse catalog: app.catalog cart: app.cart departure_datetime: app.departure_datetime on_date_edit: screenmanager.current date_selection on_back: screenmanager.current date_selection on_order_submit: app.create_order() screenmanager.current order OrderScreen: id: order_screen name: order cart: app.cart order: app.order on_back: screenmanager.current browse請(qǐng)注意on_submit、on_date_edit、on_back、on_order_submit等都是自定義事件。聲明它們非常簡(jiǎn)單在類的__events__屬性中列出事件名并實(shí)現(xiàn)對(duì)應(yīng)的空處理器。ScreenManager與Screen實(shí)現(xiàn)在 kivy/uix/screenmanager.py。from kivy.uix.screenmanager import Screen class OrderScreen(Screen): __events__ (on_reset, on_back) def on_reset(self): pass def on_back(self): pass__events__是 Kivy 事件系統(tǒng)的核心約定事件分發(fā)器會(huì)依據(jù)__events__元組注冊(cè)命名事件并自動(dòng)調(diào)用同名的on_event處理器若存在。倉(cāng)庫(kù)中到處可見這一約定例如 kivy/animation.py 的__events__ (on_start, on_progress, on_complete)、kivy/app.py 的__events__ (on_start, on_ready, on_stop, on_pause, on_resume, ...)以及 kivy/base.py 的__events__ (on_start, on_pause, on_stop)。當(dāng)多個(gè)屏幕需要復(fù)用同一批事件比如訂單頁(yè)和瀏覽頁(yè)都有返回時(shí)把事件定義在基類、由各屏幕繼承再在 KV 中通過on_event:綁定跳轉(zhuǎn)邏輯就可以把流程控制整體上浮到 KV 層讓 Python 保持為純粹的領(lǐng)域邏輯。片段六把 Flask 嵌入 KivyWindows 也可用flask_with_kivy/snippet.rst 是片段集中最完整的實(shí)戰(zhàn)示例把 Flask 后端以獨(dú)立線程內(nèi)嵌進(jìn) Kivy 應(yīng)用二者通過共享的ListProperty交互并用 Server-Sent EventsSSE做實(shí)時(shí)推送附帶一個(gè)測(cè)試客戶端。作者特別注明works on Windows too——這通常意味著在 Windows 上無法依賴某些 Unix 專用 API方案應(yīng)保持純跨平臺(tái)實(shí)現(xiàn)。服務(wù)端代碼保存為獨(dú)立文件如server.pyimport json import threading import time from collections.abc import Generator from typing import Any import trio import waitress # type: ignore[import-untyped] from flask import Flask, request from flask.typing import ResponseReturnValue from kivy.app import App # type: ignore[import-untyped] from kivy.lang.builder import Builder # type: ignore[import-untyped] from kivy.properties import ListProperty # type: ignore[import-untyped] api Flask(__name__) api.get(/messages) def message_stream() - ResponseReturnValue: app App.get_running_app() def stream_messages() - Generator[str, None, None]: next_index 0 while True: for index, message in enumerate( app.messages[next_index:], startnext_index, ): data {message: message} yield fdata: {json.dumps(data)}\n\n next_index index 1 time.sleep(1) yield :heartbeat\n return stream_messages() api.post(/messages) def post_message() - ResponseReturnValue: app App.get_running_app() data request.get_json() message data[message] app.messages.append(message) return , 201 def run_backend() - None: api_thread threading.Thread( targetwaitress.serve, kwargs{ app: api, host: 0.0.0.0, port: 8080, threads: 256, }, daemonTrue, ) api_thread.start() KV r Label: text: Messages:\n{}.format(\n.join(app.messages)) text_size: self.size valign: top class EmbeddedFlask(App): # type: ignore messages ListProperty() async def async_run(self) - None: async with trio.open_nursery() as nursery: self.nursery nursery run_backend() await super().async_run(async_libtrio) nursery.cancel_scope.cancel() def build(self) - Any: return Builder.load_string(KV) app EmbeddedFlask() if __name__ __main__: trio.run(app.async_run)客戶端測(cè)試代碼保存為client.py Usage: - python client.py - Listens to messages stream and displays the results - python client.py my message - Sends a new message to the backend import json import sys from collections.abc import Sequence import requests # type: ignore[import-untyped] API_URI http://localhost:8080/messages def main(args: Sequence[str]) - None: if len(args) 1: message .join(sys.argv[1:]) requests.post(API_URI, json{message: message}) return for line in requests.get(API_URI, streamTrue).iter_lines(): data line.decode(utf8).strip() if data.startswith(:): continue command, _, payload data.partition(:) if command ! data: continue event json.loads(payload) print(event) if __name__ __main__: main(sys.argv)這個(gè)示例的關(guān)鍵設(shè)計(jì)數(shù)據(jù)共享而非跨線程調(diào)用Flask 路由通過App.get_running_app()拿到運(yùn)行中的 Kivy 應(yīng)用實(shí)例直接追加到app.messages一個(gè)ListProperty。由于messages是 Kivy 屬性KV 中的\n.join(app.messages)會(huì)在列表變化時(shí)自動(dòng)刷新界面——這正是片段二所強(qiáng)調(diào)的屬性系統(tǒng)讓數(shù)據(jù)流自動(dòng)驅(qū)動(dòng) UI的進(jìn)階應(yīng)用。線程安全的前提示例中后臺(tái)線程只追加messages列表數(shù)據(jù)UI 文本通過屬性綁定重算Kivy 屬性的線程行為雖非完全無鎖但ListProperty的賦值/追加配合主線程幀刷新在演示場(chǎng)景下是可行且常見的做法。若需要更嚴(yán)格的線程安全應(yīng)配合片段二的mainthread模式。waitress 作為 WSGI 服務(wù)器用waitress.serve在守護(hù)線程中啟動(dòng)threads256指明并發(fā)線程數(shù)host0.0.0.0、port8080是監(jiān)聽地址。SSE 實(shí)時(shí)推送GET /messages返回一個(gè)生成器按 SSE 協(xié)議逐條data: {...}\n\n推送新消息并以:heartbeat心跳維持連接客戶端用requests.get(streamTrue).iter_lines()逐行消費(fèi)跳過以:開頭的心跳行解析data:載荷。trio 托管整體生命周期run_backend()在async_run內(nèi)啟動(dòng)Kivy 退出時(shí) nursery 的cancel_scope.cancel()一并結(jié)束應(yīng)用進(jìn)程。總結(jié)與延伸閱讀六個(gè)片段覆蓋了 Kivy 開發(fā)中反復(fù)出現(xiàn)的四類主題控件封裝自定義 Widget ButtonBehavior、線程與異步mainthread、trio、async_run、事件系統(tǒng)EventDispatcher、__events__、自定義事件、以及進(jìn)程內(nèi)服務(wù)嵌入Flask SSE。它們的共同底層支撐是 Kivy 的屬性系統(tǒng)kivy/properties.pyx與事件分發(fā)系統(tǒng)kivy/_event.pyx、kivy/event.py——理解了這兩者所有片段都能舉一反三。若想繼續(xù)深入屬性與事件的基礎(chǔ)原理見 doc/sources/gettingstarted/properties.rst 與 doc/sources/gettingstarted/events.rstKV 語(yǔ)言規(guī)則見 doc/sources/guide/lang.rst官方異步示例位于 examples/async/asyncio_basic.py、trio_basic.py、trio_advanced.py時(shí)鐘調(diào)度與mainthread的完整語(yǔ)義見 kivy/clock.py控件行為 Mixin 家族見 kivy/uix/behaviors/。這些片段由 Kivy 社區(qū)成員貢獻(xiàn)并收錄進(jìn)官方文檔是經(jīng)過真實(shí)項(xiàng)目驗(yàn)證的慣用法直接對(duì)照片段源碼與上述核心模塊閱讀是理解 Kivy 設(shè)計(jì)哲學(xué)最有效率的方式?！久赓M(fèi)下載鏈接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS項(xiàng)目地址: https://gitcode.com/gh_mirrors/ki/kivy創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考