Kivy 自定义事件与 KV 语言实战用__events__构建应用级多屏工作流【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址: https://gitcode.com/gh_mirrors/ki/kivy导读本文围绕 custom_workflows_with_kvlang.rst 所展示的示例系统讲解 Kivy 中「自定义事件」Custom Events的声明、绑定与触发机制以及如何借助 KV 语言将ScreenManager的多屏跳转、业务动作与应用级状态如购物车、订单编排成一个完整的工作流。读完本文你将掌握__events__类属性 空事件处理器的标准声明套路、on_*事件在 KV 中的绑定语法以及EventDispatcher底层自动注册事件的实现细节能直接照搬这套模式到自己的 Kivy 应用中。一、为什么要用自定义事件组织应用工作流Kivy 本身提供了大量内置事件on_press、on_touch_down、on_enter等但它们绑定在具体控件行为上。当一个应用需要表达「业务语义」时——例如「用户选好了日期」「购物车筛选完成」「用户决定提交订单」——直接用控件事件会把这些业务逻辑散落在各个屏幕的 KV 文件里难以复用和维护。原文档给出的思路非常清晰把业务动作建模为屏幕Screen的自定义事件然后在 KV 语言里用on_事件名:把这些事件与「屏幕切换」「应用方法调用」等动作连接起来。这样屏幕只负责「发出业务信号」不关心由谁处理应用级状态app.catalog、app.cart、app.order统一由App持有屏幕跳转逻辑集中写在 KV 中一目了然可读性极高。二、原示例逐行拆解一个四屏工作流原文档的核心是一个带ScreenManager的 KV 片段原样继承稍作注释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这段 KV 展示了一个典型的「空闲 → 选日期 → 浏览筛选结果 → 下单 → 返回」流程其中包含三个值得深挖的写法1. 用idscreenmanager.current做导航ScreenManager.current是 screenmanager.py 中定义的StringProperty(None, allownoneTrue)赋值为屏幕的name即可触发带过渡动画的切换。在 KV 中IdleScreen通过on_press: screenmanager.current date_selection跳转文档注释与 screenmanager.py 中的内置示例都指出也可以使用root.manager.current方式——每个Screen默认持有指向所属管理器的manager属性两种写法等价。2. 通过app.xxx访问应用级对象catalog: app.catalog、cart: app.cart、departure_datetime: app.departure_datetime是 KV 语言中的属性绑定表达式Kivy 的App单例在 KV 中以app关键字暴露任何定义在App子类上的属性都可以被直接引用并保持双向同步。这样多个屏幕共享同一份购物车/目录/订单实例避免了各自维护副本导致的数据不一致。3. 多语句事件处理器KV 中的on_*处理器支持缩进的多行语句块如on_submit:下的三行。这一点与 parser.py 的实现吻合解析器在编译 KV 时对以on_开头的属性名使用exec模式而非eval模式编译因此可以执行赋值、调用、连续语句而不只是求一个值。三、声明自定义事件的标准三步套路原文档特别强调了核心要点并用加粗NOTICE标出on_submit、on_date_edit、on_back、on_order_submit等——这些都是自定义事件。声明它们非常简单在__events__类属性中列出事件名然后为每个事件实现空的处理器方法。配套的 Python 代码原样继承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__元组把要声明的事件名必须以on_开头放进类的__events__实现同名空处理器每个事件都需有一个on_事件名(self, *args)方法作为默认处理哪怕什么都不做在 KV 中绑定子类在 KV 规则或实例化处写on_事件名: 动作即可接管该事件。Kivy 自带控件大量使用这一模式。例如 widget.py 中Widget声明了(on_motion, on_touch_down, on_touch_move, on_touch_up, on_kv_post)screenmanager.py 中Screen声明了(on_pre_enter, on_enter, on_pre_leave, on_leave)并提供了对应的空处理器。可见「__events__ 空方法」正是 Kivy 整个事件体系的标准写法。四、底层原理EventDispatcher如何自动注册__events__自定义事件之所以「声明即生效」是因为 Kivy 事件体系的核心类EventDispatcherCython 实现于 kivy/_event.pyx在对象初始化时做了自动注册。阅读源码可以发现以下关键逻辑kivy/_event.pyx按 MRO 收集遍历类的__mro__把基类与子类的所有__events__元组合并去重保证继承链上声明的事件全部生效强制on_前缀校验事件名不以on_开头会直接抛出Exception(... is not an event name ...)强制空处理器存在若类中没有实现对应事件名的方法会抛出Exception(Missing default handler on_xxx in ClassName)——这正是原文档要求「实现空处理器」的底层原因自动注册到事件栈校验通过后事件会被注册进self.__event_stack效果等同于手动调用register_event_type(event_type)。此外kivy/_event.pyx 的__init__还会自动扫描类中所有on_开头的方法并自动fbind到对应事件上——所以空处理器不需要手动 bind声明即接入分发链路。事件真正被触发时走dispatch(event_type, *largs, **kwargs)kivy/_event.pyx先依次调用所有通过bind/fbind注册的回调任一回调返回True则停止分发最后调用默认处理器handler getattr(self, event_type)并传入参数。也就是说KV 里写的on_submit:绑定本质上就是一次bind业务代码里执行self.dispatch(on_submit, 参数...)时KV 中的处理器会被自动调用——回调与默认处理器可以并存。从源码结构可以推断示例中的DateSelectionScreen、BrowseScreen必然在各自的 Python 类中声明了__events__并实现了空处理器on_submit、on_date_edit、on_back、on_order_submit并在合适的时机如用户点击确认按钮、点击返回按钮调用self.dispatch(on_submit)等来发出业务信号KV 层只负责响应这些信号。五、KV 中自定义事件的绑定细节1.on_事件名:与args关键字在 KV 中给任意事件绑定处理器只需写on_事件名:后跟表达式或语句块。Kivy 语言参考kivy/lang/init.py明确指出在on_action回调中可以使用args元组拿到dispatch传入的位置参数例如内置示例on_focus: self.insert_text(Focus if args[1] else No focus)这对自定义事件同样适用如果dispatch(on_submit, date)时传入了日期对象KV 处理器中就可以用args[1]读取它。示例 KV 中的app.departure_datetime self.departure_datetime正是通过属性绑定获取数据属于另一种常见做法属性传值比事件参数更利于持久化与共享。2. 绑定回调的执行顺序与短路结合上文dispatch的实现KV 中绑定的多个处理器按逆注册序执行一旦某个处理器返回True分发立即停止默认处理器也不会再执行。在编写「守卫式」工作流如校验失败返回True拦截跳转时可以善用这一特性。3. 与内置事件完全同构自定义事件与内置事件在 KV 中的使用方式完全一致——这正是该设计的目标。IdleScreen的on_press是ButtonBehavior内置事件而OrderScreen的on_back是自定义事件两者可以并排写在同一个 KV 规则里而毫无违和感也再次印证了「__events__ 空处理器」的通用性。六、事件声明的两种方式与注意事项除了__events__类属性EventDispatcher还提供了实例方法register_event_type(event_type)kivy/_event.pyx用于动态注册。两种方式的选择建议方式适用场景特点__events__类属性类级别、静态声明的事件推荐自动按 MRO 合并、自动校验、自动注册代码最简洁register_event_type()运行时按条件动态声明需在__init__中手动调用同样要求事件名以on_开头实践中应优先使用__events__原因有二校验更严格缺处理器、命名不合规会在实例化时立刻报错而不是等到事件触发时才静默失败继承更友好子类声明的__events__会与父类合并而register_event_type若在__init__中被覆盖则可能丢失注册。另外注意命名规范事件名必须以on_开头如on_submit而不是submit并且不要与类中已有属性同名——Widget的__init__kivy/uix/widget.py会把构造参数中所有on_前缀的 kwargs 提取出来自动绑定同名冲突会导致绑定错乱。七、把模式应用到自己的应用落地建议结合原示例与仓库源码落地一个「自定义事件驱动」的多屏应用时可遵循以下清单为每个屏幕定义业务事件在屏幕类的__events__中声明如on_submit、on_cancel、on_date_edit并实现同名空方法在业务动作处dispatch屏幕内部按钮回调、异步结果回调等调用self.dispatch(on_xxx, *args)发出信号在 KV 中集中编排用screenmanager.current ...做导航用app.xxx读写应用状态用多行语句块串起「取数据 → 处理 → 跳转」数据传递二选一轻量一次性数据用dispatch参数 args需要跨屏共享、长期保留的状态如catalog、cart、order用app上的属性绑定保持默认处理器为空把真正的业务逻辑放在 KV 绑定或显式bind的回调中默认处理器只作兜底避免逻辑分散。关于事件机制的更多背景可继续阅读仓库内的 gettingstarted/events.rst、guide/events.rst事件与属性体系以及 guide/lang.rst、gettingstarted/rules.rstKV 语言绑定规则语言级处理器的解析行为可对照 kivy/lang/parser.py 与 kivy/lang/init.py。仓库测试 test_lang_pre_process_and_post_process.py 中也包含对__events__声明的覆盖用例可作为行为验证参考。结语原文档用不到 60 行代码示范了 Kivy 中最值得掌握的架构模式之一用__events__声明自定义业务事件用 KV 语言把事件、屏幕切换和应用状态编织成完整工作流。这套模式把「界面」与「业务流」解耦——屏幕只发信号KV 决定流程App持有状态——让多屏应用的可读性、可维护性都大幅提升。理解了EventDispatcher的自动注册与dispatch分发机制后你不仅能熟练照抄这个四屏示例更能举一反三地设计属于自己的事件驱动应用。【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址: https://gitcode.com/gh_mirrors/ki/kivy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Kivy 自定义事件与 KV 语言实战：用 `__events__` 构建应用级多屏工作流
Kivy 自定义事件与 KV 语言实战用__events__构建应用级多屏工作流【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址: https://gitcode.com/gh_mirrors/ki/kivy导读本文围绕 custom_workflows_with_kvlang.rst 所展示的示例系统讲解 Kivy 中「自定义事件」Custom Events的声明、绑定与触发机制以及如何借助 KV 语言将ScreenManager的多屏跳转、业务动作与应用级状态如购物车、订单编排成一个完整的工作流。读完本文你将掌握__events__类属性 空事件处理器的标准声明套路、on_*事件在 KV 中的绑定语法以及EventDispatcher底层自动注册事件的实现细节能直接照搬这套模式到自己的 Kivy 应用中。一、为什么要用自定义事件组织应用工作流Kivy 本身提供了大量内置事件on_press、on_touch_down、on_enter等但它们绑定在具体控件行为上。当一个应用需要表达「业务语义」时——例如「用户选好了日期」「购物车筛选完成」「用户决定提交订单」——直接用控件事件会把这些业务逻辑散落在各个屏幕的 KV 文件里难以复用和维护。原文档给出的思路非常清晰把业务动作建模为屏幕Screen的自定义事件然后在 KV 语言里用on_事件名:把这些事件与「屏幕切换」「应用方法调用」等动作连接起来。这样屏幕只负责「发出业务信号」不关心由谁处理应用级状态app.catalog、app.cart、app.order统一由App持有屏幕跳转逻辑集中写在 KV 中一目了然可读性极高。二、原示例逐行拆解一个四屏工作流原文档的核心是一个带ScreenManager的 KV 片段原样继承稍作注释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这段 KV 展示了一个典型的「空闲 → 选日期 → 浏览筛选结果 → 下单 → 返回」流程其中包含三个值得深挖的写法1. 用idscreenmanager.current做导航ScreenManager.current是 screenmanager.py 中定义的StringProperty(None, allownoneTrue)赋值为屏幕的name即可触发带过渡动画的切换。在 KV 中IdleScreen通过on_press: screenmanager.current date_selection跳转文档注释与 screenmanager.py 中的内置示例都指出也可以使用root.manager.current方式——每个Screen默认持有指向所属管理器的manager属性两种写法等价。2. 通过app.xxx访问应用级对象catalog: app.catalog、cart: app.cart、departure_datetime: app.departure_datetime是 KV 语言中的属性绑定表达式Kivy 的App单例在 KV 中以app关键字暴露任何定义在App子类上的属性都可以被直接引用并保持双向同步。这样多个屏幕共享同一份购物车/目录/订单实例避免了各自维护副本导致的数据不一致。3. 多语句事件处理器KV 中的on_*处理器支持缩进的多行语句块如on_submit:下的三行。这一点与 parser.py 的实现吻合解析器在编译 KV 时对以on_开头的属性名使用exec模式而非eval模式编译因此可以执行赋值、调用、连续语句而不只是求一个值。三、声明自定义事件的标准三步套路原文档特别强调了核心要点并用加粗NOTICE标出on_submit、on_date_edit、on_back、on_order_submit等——这些都是自定义事件。声明它们非常简单在__events__类属性中列出事件名然后为每个事件实现空的处理器方法。配套的 Python 代码原样继承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__元组把要声明的事件名必须以on_开头放进类的__events__实现同名空处理器每个事件都需有一个on_事件名(self, *args)方法作为默认处理哪怕什么都不做在 KV 中绑定子类在 KV 规则或实例化处写on_事件名: 动作即可接管该事件。Kivy 自带控件大量使用这一模式。例如 widget.py 中Widget声明了(on_motion, on_touch_down, on_touch_move, on_touch_up, on_kv_post)screenmanager.py 中Screen声明了(on_pre_enter, on_enter, on_pre_leave, on_leave)并提供了对应的空处理器。可见「__events__ 空方法」正是 Kivy 整个事件体系的标准写法。四、底层原理EventDispatcher如何自动注册__events__自定义事件之所以「声明即生效」是因为 Kivy 事件体系的核心类EventDispatcherCython 实现于 kivy/_event.pyx在对象初始化时做了自动注册。阅读源码可以发现以下关键逻辑kivy/_event.pyx按 MRO 收集遍历类的__mro__把基类与子类的所有__events__元组合并去重保证继承链上声明的事件全部生效强制on_前缀校验事件名不以on_开头会直接抛出Exception(... is not an event name ...)强制空处理器存在若类中没有实现对应事件名的方法会抛出Exception(Missing default handler on_xxx in ClassName)——这正是原文档要求「实现空处理器」的底层原因自动注册到事件栈校验通过后事件会被注册进self.__event_stack效果等同于手动调用register_event_type(event_type)。此外kivy/_event.pyx 的__init__还会自动扫描类中所有on_开头的方法并自动fbind到对应事件上——所以空处理器不需要手动 bind声明即接入分发链路。事件真正被触发时走dispatch(event_type, *largs, **kwargs)kivy/_event.pyx先依次调用所有通过bind/fbind注册的回调任一回调返回True则停止分发最后调用默认处理器handler getattr(self, event_type)并传入参数。也就是说KV 里写的on_submit:绑定本质上就是一次bind业务代码里执行self.dispatch(on_submit, 参数...)时KV 中的处理器会被自动调用——回调与默认处理器可以并存。从源码结构可以推断示例中的DateSelectionScreen、BrowseScreen必然在各自的 Python 类中声明了__events__并实现了空处理器on_submit、on_date_edit、on_back、on_order_submit并在合适的时机如用户点击确认按钮、点击返回按钮调用self.dispatch(on_submit)等来发出业务信号KV 层只负责响应这些信号。五、KV 中自定义事件的绑定细节1.on_事件名:与args关键字在 KV 中给任意事件绑定处理器只需写on_事件名:后跟表达式或语句块。Kivy 语言参考kivy/lang/init.py明确指出在on_action回调中可以使用args元组拿到dispatch传入的位置参数例如内置示例on_focus: self.insert_text(Focus if args[1] else No focus)这对自定义事件同样适用如果dispatch(on_submit, date)时传入了日期对象KV 处理器中就可以用args[1]读取它。示例 KV 中的app.departure_datetime self.departure_datetime正是通过属性绑定获取数据属于另一种常见做法属性传值比事件参数更利于持久化与共享。2. 绑定回调的执行顺序与短路结合上文dispatch的实现KV 中绑定的多个处理器按逆注册序执行一旦某个处理器返回True分发立即停止默认处理器也不会再执行。在编写「守卫式」工作流如校验失败返回True拦截跳转时可以善用这一特性。3. 与内置事件完全同构自定义事件与内置事件在 KV 中的使用方式完全一致——这正是该设计的目标。IdleScreen的on_press是ButtonBehavior内置事件而OrderScreen的on_back是自定义事件两者可以并排写在同一个 KV 规则里而毫无违和感也再次印证了「__events__ 空处理器」的通用性。六、事件声明的两种方式与注意事项除了__events__类属性EventDispatcher还提供了实例方法register_event_type(event_type)kivy/_event.pyx用于动态注册。两种方式的选择建议方式适用场景特点__events__类属性类级别、静态声明的事件推荐自动按 MRO 合并、自动校验、自动注册代码最简洁register_event_type()运行时按条件动态声明需在__init__中手动调用同样要求事件名以on_开头实践中应优先使用__events__原因有二校验更严格缺处理器、命名不合规会在实例化时立刻报错而不是等到事件触发时才静默失败继承更友好子类声明的__events__会与父类合并而register_event_type若在__init__中被覆盖则可能丢失注册。另外注意命名规范事件名必须以on_开头如on_submit而不是submit并且不要与类中已有属性同名——Widget的__init__kivy/uix/widget.py会把构造参数中所有on_前缀的 kwargs 提取出来自动绑定同名冲突会导致绑定错乱。七、把模式应用到自己的应用落地建议结合原示例与仓库源码落地一个「自定义事件驱动」的多屏应用时可遵循以下清单为每个屏幕定义业务事件在屏幕类的__events__中声明如on_submit、on_cancel、on_date_edit并实现同名空方法在业务动作处dispatch屏幕内部按钮回调、异步结果回调等调用self.dispatch(on_xxx, *args)发出信号在 KV 中集中编排用screenmanager.current ...做导航用app.xxx读写应用状态用多行语句块串起「取数据 → 处理 → 跳转」数据传递二选一轻量一次性数据用dispatch参数 args需要跨屏共享、长期保留的状态如catalog、cart、order用app上的属性绑定保持默认处理器为空把真正的业务逻辑放在 KV 绑定或显式bind的回调中默认处理器只作兜底避免逻辑分散。关于事件机制的更多背景可继续阅读仓库内的 gettingstarted/events.rst、guide/events.rst事件与属性体系以及 guide/lang.rst、gettingstarted/rules.rstKV 语言绑定规则语言级处理器的解析行为可对照 kivy/lang/parser.py 与 kivy/lang/init.py。仓库测试 test_lang_pre_process_and_post_process.py 中也包含对__events__声明的覆盖用例可作为行为验证参考。结语原文档用不到 60 行代码示范了 Kivy 中最值得掌握的架构模式之一用__events__声明自定义业务事件用 KV 语言把事件、屏幕切换和应用状态编织成完整工作流。这套模式把「界面」与「业务流」解耦——屏幕只发信号KV 决定流程App持有状态——让多屏应用的可读性、可维护性都大幅提升。理解了EventDispatcher的自动注册与dispatch分发机制后你不仅能熟练照抄这个四屏示例更能举一反三地设计属于自己的事件驱动应用。【免费下载链接】kivyOpen source UI framework written in Python, running on Windows, Linux, macOS, Android and iOS项目地址: https://gitcode.com/gh_mirrors/ki/kivy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考