Reflex 事件触发器Event Triggers完全指南从生命周期事件到全局键盘监听【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex事件触发器Event Triggers是 Reflex 中连接用户交互与状态更新的桥梁组件通过on_click、on_change等触发器捕获浏览器事件并调用对应的事件处理器Event Handler来修改应用状态。本文以 Reflex 官方 API 文档中的事件触发器为骨架结合仓库源码与集成测试系统讲解组件生命周期事件on_mount/on_unmount、页面加载事件on_load以及全部交互型事件触发器的使用方式与底层实现原理读完即可在实际应用中正确选用并组合这些触发器。事件触发器与事件处理器两个核心概念在深入各类触发器之前先明确 Reflex 事件系统的两个组成部分详见 事件总览事件处理器Event Handlers更新 Reflex 应用状态的方法由用户在界面上的交互点击按钮、悬停元素触发也可以由页面加载或其他事件触发。事件触发器Event Triggers组件上的 props属性用于产生一条发送给事件处理器的事件。每个组件支持一组事件触发器具体列表见各组件文档的 event trigger 部分。二者的协作模式可以用如下经典示例说明标题组件挂载了on_mouse_over触发器每当鼠标悬停时调用next_word处理器循环切换单词处理器返回后 UI 自动更新。class WordCycleState(rx.State): # The words to cycle through. text: list[str] [Welcome, to, Reflex, !] # The index of the current word. index: int 0 rx.event def next_word(self): self.index (self.index 1) % len(self.text) rx.var def get_text(self) - str: return self.text[self.index] def event_triggers_example(): return rx.heading( WordCycleState.get_text, as_h2, on_mouse_overWordCycleState.next_word, colorgreen, )需要注意官方文档强烈建议为事件处理器添加rx.event装饰器该装饰器启用正确的静态类型检查确保事件处理器接收正确数量和类型的参数。组件生命周期事件on_mount 与 on_unmountReflex 组件拥有类似on_mount和on_unmount的生命周期事件允许在组件存在的特定时间点执行代码。它们是初始化数据、清理资源、构建动态界面的关键工具。on_mount组件挂载后触发on_mount在组件被渲染并挂载到 DOM 之后立即触发。它会触发的场景包括包含该组件的页面首次加载时组件被条件渲染例如通过rx.cond从隐藏变为显示时使用内部导航跳转到包含该组件的页面时。它不会在页面刷新或跟随外部链接进入页面时触发。on_unmount组件移除前触发on_unmount在组件即将从 DOM 中移除之前触发。它会触发的场景包括使用内部导航离开包含该组件的页面时组件被条件渲染移除例如通过条件将其隐藏时。它不会在刷新页面、关闭浏览器标签页或跟随外部链接时触发。生命周期演示数据加载与资源清理官方文档给出了一个完整的生命周期演示。MountState通过on_mount记录触发时间并用异步处理器模拟数据加载设置loading标志、yield立即推送到前端、asyncio.sleep模拟耗时操作配合rx.cond在加载中显示 spinner、加载完成后渲染数据列表class MountState(rx.State): events: list[str] [] data: list[dict] [] loading: bool False rx.event def on_mount(self): self.events self.events[-4:] [on_mount str(datetime.now())] rx.event async def load_data(self): self.loading True yield import asyncio await asyncio.sleep(1) self.data [dict(id1, nameItem 1), dict(id2, nameItem 2)] self.loading False def mount_example(): return rx.vstack( rx.heading(Component Lifecycle Demo, as_h2), rx.foreach(MountState.events, rx.text), rx.cond( MountState.loading, rx.spinner(), rx.foreach( MountState.data, lambda item: rx.text(fID: {item[id]} - {item[name]}), ), ), on_mountMountState.on_mount, )UnmountState则展示了资源清理的典型用法on_mount初始化资源on_unmount执行清理并更新状态页面内提供一个内部导航链接rx.link指向/点击后触发卸载流程class UnmountState(rx.State): events: list[str] [] resource_id: str resource-12345 status: str Resource active rx.event def on_unmount(self): self.events self.events[-4:] [on_unmount str(datetime.now())] self.status fResource {self.resource_id} cleaned up rx.event def initialize_resource(self): self.status fResource {self.resource_id} initialized def unmount_example(): return rx.vstack( rx.heading(Unmount Demo, as_h2), rx.foreach(UnmountState.events, rx.text), rx.text(UnmountState.status), rx.link( rx.button(Navigate Away (Triggers Unmount)), href/, ), on_mountUnmountState.initialize_resource, on_unmountUnmountState.on_unmount, )生命周期事件的源码定义在仓库中on_mount与on_unmount是组件的默认事件触发器之一定义于 component.pyEventTriggers.ON_MOUNT: TriggerDefinition( specno_args_event_spec, descriptionFired when the component is mounted to the page., ), EventTriggers.ON_UNMOUNT: TriggerDefinition( specno_args_event_spec, descriptionFired when the component is removed from the page. Only called during navigation, not on page refresh., ),集成测试 test_event_chain.py 验证了on_mount/on_unmount与事件链的执行顺序并特别指出在 dev 模式下React StrictMode 会导致这些事件触发两次prod 模式下仅触发一次。这是调试生命周期事件时需要注意的重要细节。页面加载事件on_load除了组件生命周期事件Reflex 还提供页面级事件on_load在页面加载时触发。它的典型用途包括页面首次加载时获取数据检查认证状态初始化页面级状态为 cookie 或浏览器存储设置默认值。在 on_load 中获取数据on_load事件处理器通过rx.page装饰器的on_load参数或app.add_page()方法指定class State(rx.State): data: dict dict() rx.event def get_data(self): # Fetch data when the page loads self.data fetch_data() rx.page(on_loadState.get_data) def index(): return rx.text(Data loaded on page load)在 on_load 中做认证检查on_load尤其适合实现路由保护页面加载时检查认证状态未认证则通过rx.redirect重定向到登录页class State(rx.State): authenticated: bool False rx.event def check_auth(self): # Check if user is authenticated self.authenticated check_auth() if not self.authenticated: return rx.redirect(/login) rx.page(on_loadState.check_auth) def protected_page(): return rx.text(Protected content)on_load 的加载与错误处理页面在on_load处理器完成前就会渲染因此在处理器中做重量级同步工作会让用户面对陈旧或空白数据。官方建议详见 页面加载事件文档网络或数据库调用使用异步处理器避免阻塞事件循环设置loading标志并通过yield立即推送到前端配合rx.cond渲染 spinner 或占位内容用try/except包裹耗时操作让失败以错误消息呈现而不是让页面永远处于加载中。class DataState(rx.State): data: dict {} loading: bool False error: str rx.event async def load_initial_data(self): self.loading True yield # Send the loading state to the frontend immediately. try: self.data await fetch_data() except Exception as e: self.error str(e) finally: self.loading False rx.page(on_loadDataState.load_initial_data) def index(): return rx.cond( DataState.loading, rx.spinner(), rx.cond( DataState.error ! , rx.text(fError: {DataState.error}), rx.text(fData loaded: {DataState.data}), ), )on_load 的源码与测试佐证从源码结构看on_load是页面级的配置项在 page.py 中on_load作为Page的参数被保存在 app.py 中add_page()接受on_load并将其绑定到页面state.py 中定义了专门用于枚举并排队on_load处理器的子状态。集成测试 test_dynamic_routes.py 验证了通过链接在动态页面间导航时on_load的正确触发顺序包括/404页面同样支持on_load。交互型事件触发器参考以下触发器均为组件 props具体支持情况以各组件文档为准。官方文档为每个触发器提供了可直接运行的演示。on_focus 与 on_bluron_focus在元素或其内部元素获得焦点时调用例如用户点击文本输入框on_blur在焦点离开元素或其内部元素时调用例如用户点击输入框外部class FocusState(rx.State): text: str Change Me! rx.event def change_text(self, text): if self.text Change Me!: self.text Changed! else: self.text Change Me! def focus_example(): return rx.input(valueFocusState.text, on_focusFocusState.change_text)class BlurState(rx.State): text: str Change Me! rx.event def change_text(self, text): if self.text Change Me!: self.text Changed! else: self.text Change Me! def blur_example(): return rx.input(valueBlurState.text, on_blurBlurState.change_text)on_changeon_change在元素的值发生变化时调用。例如用户向文本输入框键入内容时每次击键都会触发一次class ChangeState(rx.State): checked: bool False rx.event def set_checked(self): self.checked not self.checked def change_example(): return rx.switch(on_changeChangeState.set_checked)on_clickon_click在用户点击元素时调用是使用频率最高的触发器例如点击按钮class ClickState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def click_example(): return rx.button(ClickState.text, on_clickClickState.change_text)on_context_menuon_context_menu在用户右键点击元素时调用例如右键点击按钮class ContextState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def context_menu_example(): return rx.button(ContextState.text, on_context_menuContextState.change_text)on_double_clickon_double_click在用户双击元素时调用例如双击按钮class DoubleClickState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def double_click_example(): return rx.button( DoubleClickState.text, on_double_clickDoubleClickState.change_text )鼠标事件系列以下触发器覆盖鼠标的完整交互状态on_mouse_up用户在某元素上释放鼠标按键时调用例如释放左键on_mouse_down用户在某元素上按下鼠标按键时调用例如按下左键on_mouse_enter鼠标进入元素时调用on_mouse_leave鼠标离开元素时调用on_mouse_move鼠标在元素上移动时调用on_mouse_out鼠标移出元素时调用on_mouse_over鼠标进入元素时调用。class MouseUpState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def mouse_up_example(): return rx.button(MouseUpState.text, on_mouse_upMouseUpState.change_text)on_mouse_down、on_mouse_enter、on_mouse_leave、on_mouse_move、on_mouse_out、on_mouse_over的写法完全相同只需替换状态类名、触发器名与组件绑定。注意on_mouse_enter/on_mouse_leave与on_mouse_over/on_mouse_out的语义区别enter/leave 不冒泡不会在鼠标穿过子元素时反复触发而 over/out 会冒泡。选择时需结合具体交互需求。class MouseEnterState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def mouse_enter_example(): return rx.button(MouseEnterState.text, on_mouse_enterMouseEnterState.change_text)on_scrollon_scroll在用户滚动页面时调用例如向下滚动页面。演示中通过overflowauto、height3em、width100%让容器产生滚动区域class ScrollState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def scroll_example(): return rx.vstack( rx.text(Scroll to make the text below change.), rx.text(ScrollState.text), rx.text(Scroll to make the text above change.), on_scrollScrollState.change_text, overflowauto, height3em, width100%, )on_key_down 与 on_key_upon_key_down在元素获得焦点时用户按键时调用。处理器接收按键名称如Enter、Escape、a、ArrowUp以及描述活动修饰键的字典alt_key、ctrl_key、meta_key、shift_key。如果不需要修饰键信息处理器可以只接收按键名class KeyDownState(rx.State): message: str rx.event def handle_key_down(self, key: str): if key Enter: self.message You pressed Enter! else: self.message fLast key pressed: {key} def key_down_example(): return rx.vstack( rx.text(KeyDownState.message), rx.input( placeholderFocus me and press a key..., on_key_downKeyDownState.handle_key_down, ), )on_key_up在用户释放按键时调用接收与on_key_down相同的参数。从源码看按键事件的参数由key_event参数规范spec定义位于 event/init.py返回(e.key, {alt_key, ctrl_key, meta_key, shift_key})二元组。这意味着事件处理器既可以只接收key: str也可以接收(key, modifiers)两个参数。全局键盘事件window_event_listener元素上的on_key_down只在元素持有焦点时触发。若要在页面任意位置监听键盘事件例如实现全局快捷键可将on_key_down挂载到rx.window_event_listener组件——它监听浏览器 window 且不渲染任何可见输出class HotkeyState(rx.State): last_key_pressed: str rx.event def on_hotkey_press(self, key: str): if key not in (w, a, s, d): return self.last_key_pressed key def hotkey_example(): return rx.vstack( rx.text(Press w, a, s, or d anywhere on the page.), rx.text(fLast hotkey pressed: {HotkeyState.last_key_pressed}), rx.window_event_listener( on_key_downHotkeyState.on_hotkey_press, ), )window_event_listener 的完整能力该组件还提供了比文档示例更丰富的窗口级触发器定义于 window_events.py触发器触发时机处理器接收的参数on_resize浏览器窗口大小变化新的宽、高像素on_scroll用户滚动页面当前水平、垂直滚动位置on_focus浏览器标签页/窗口获得焦点如切回该标签页无on_blur浏览器标签页/窗口失去焦点如切到其他标签页无on_visibility_change页面变为可见或隐藏如切换标签页或最小化布尔值文档是否隐藏on_before_unload用户即将离开或关闭页面前无可用于清理或提示未保存更改on_key_down页面任意位置按键按键名与修饰键shift、ctrl、alt、metaon_popstate用户通过浏览器历史按钮前进/后退无on_storage其他标签页修改 localStorage 或 sessionStoragekey、旧值、新值、修改存储的文档 URL其底层实现window_events.py会在渲染时生成一个useEffecthook将on_前缀去掉、下划线移除后得到原生 JS 事件名如on_key_down→keydown通过window.addEventListener注册监听并在清理函数中removeEventListener。由于该组件继承自Fragment且排除了事件处理器 props因此不会产生任何可见 DOM 输出——这正是它可以隐形地实现全局监听的原因。触发器的默认参数规范源码视角在 component.py 中DEFAULT_TRIGGERS_AND_DESC定义了所有组件共享的默认事件触发器及其参数规范ArgsSpecno_args_event_spec处理器不接受额外参数——适用于on_focus、on_blur、on_mouse_up、on_mouse_down、on_mouse_enter、on_mouse_leave、on_mouse_move、on_mouse_out、on_mouse_over、on_scroll、on_mount、on_unmountpointer_event_spec处理器可接收指针事件信息按钮编号、坐标、修饰键等——适用于on_click、on_context_menu、on_double_clickkey_event处理器接收按键名与修饰键字典——适用于on_key_down、on_key_up。这意味着事件处理器的签名不是随意书写的定义处理器时必须与所挂载触发器的参数规范匹配而rx.event装饰器会在编译期帮助类型检查器校验这一点。例如on_clickClickState.change_text中的change_text(self)不接收参数而on_key_downKeyDownState.handle_key_down中的handle_key_down(self, key: str)接收按键名二者都符合各自触发器的规范。小结与选型建议一次性初始化与清理页面加载时的数据拉取优先使用rx.page(on_load...)组件出现/消失时的资源初始化与释放使用on_mount/on_unmount并牢记刷新与外部链接不会触发这两个组件生命周期事件。耗时操作在on_load、on_mount中做网络或数据库调用时务必使用异步处理器配合yield推送加载状态并用try/except处理失败。普通交互根据交互语义选择on_click、on_change、on_focus/on_blur、鼠标系列与on_scroll需要区分鼠标穿越子元素的重复触发时注意 enter/leave 与 over/out 的冒泡差异。键盘快捷键局部输入监听用元素的on_key_down/on_key_up全局热键用rx.window_event_listener还可顺带利用on_visibility_change、on_storage等窗口级触发器。参数规范匹配编写处理器时让签名与触发器的 ArgsSpec 对齐配合rx.event装饰器获得静态类型检查保障。开发模式注意dev 模式下 React StrictMode 会让on_mount/on_unmount触发两次生产环境只触发一次见 test_event_chain.py。更多细节可继续查阅 事件总览 与 页面加载事件以及各组件文档中的 event trigger 章节。【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Reflex 事件触发器（Event Triggers）完全指南：从生命周期事件到全局键盘监听
Reflex 事件触发器Event Triggers完全指南从生命周期事件到全局键盘监听【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex事件触发器Event Triggers是 Reflex 中连接用户交互与状态更新的桥梁组件通过on_click、on_change等触发器捕获浏览器事件并调用对应的事件处理器Event Handler来修改应用状态。本文以 Reflex 官方 API 文档中的事件触发器为骨架结合仓库源码与集成测试系统讲解组件生命周期事件on_mount/on_unmount、页面加载事件on_load以及全部交互型事件触发器的使用方式与底层实现原理读完即可在实际应用中正确选用并组合这些触发器。事件触发器与事件处理器两个核心概念在深入各类触发器之前先明确 Reflex 事件系统的两个组成部分详见 事件总览事件处理器Event Handlers更新 Reflex 应用状态的方法由用户在界面上的交互点击按钮、悬停元素触发也可以由页面加载或其他事件触发。事件触发器Event Triggers组件上的 props属性用于产生一条发送给事件处理器的事件。每个组件支持一组事件触发器具体列表见各组件文档的 event trigger 部分。二者的协作模式可以用如下经典示例说明标题组件挂载了on_mouse_over触发器每当鼠标悬停时调用next_word处理器循环切换单词处理器返回后 UI 自动更新。class WordCycleState(rx.State): # The words to cycle through. text: list[str] [Welcome, to, Reflex, !] # The index of the current word. index: int 0 rx.event def next_word(self): self.index (self.index 1) % len(self.text) rx.var def get_text(self) - str: return self.text[self.index] def event_triggers_example(): return rx.heading( WordCycleState.get_text, as_h2, on_mouse_overWordCycleState.next_word, colorgreen, )需要注意官方文档强烈建议为事件处理器添加rx.event装饰器该装饰器启用正确的静态类型检查确保事件处理器接收正确数量和类型的参数。组件生命周期事件on_mount 与 on_unmountReflex 组件拥有类似on_mount和on_unmount的生命周期事件允许在组件存在的特定时间点执行代码。它们是初始化数据、清理资源、构建动态界面的关键工具。on_mount组件挂载后触发on_mount在组件被渲染并挂载到 DOM 之后立即触发。它会触发的场景包括包含该组件的页面首次加载时组件被条件渲染例如通过rx.cond从隐藏变为显示时使用内部导航跳转到包含该组件的页面时。它不会在页面刷新或跟随外部链接进入页面时触发。on_unmount组件移除前触发on_unmount在组件即将从 DOM 中移除之前触发。它会触发的场景包括使用内部导航离开包含该组件的页面时组件被条件渲染移除例如通过条件将其隐藏时。它不会在刷新页面、关闭浏览器标签页或跟随外部链接时触发。生命周期演示数据加载与资源清理官方文档给出了一个完整的生命周期演示。MountState通过on_mount记录触发时间并用异步处理器模拟数据加载设置loading标志、yield立即推送到前端、asyncio.sleep模拟耗时操作配合rx.cond在加载中显示 spinner、加载完成后渲染数据列表class MountState(rx.State): events: list[str] [] data: list[dict] [] loading: bool False rx.event def on_mount(self): self.events self.events[-4:] [on_mount str(datetime.now())] rx.event async def load_data(self): self.loading True yield import asyncio await asyncio.sleep(1) self.data [dict(id1, nameItem 1), dict(id2, nameItem 2)] self.loading False def mount_example(): return rx.vstack( rx.heading(Component Lifecycle Demo, as_h2), rx.foreach(MountState.events, rx.text), rx.cond( MountState.loading, rx.spinner(), rx.foreach( MountState.data, lambda item: rx.text(fID: {item[id]} - {item[name]}), ), ), on_mountMountState.on_mount, )UnmountState则展示了资源清理的典型用法on_mount初始化资源on_unmount执行清理并更新状态页面内提供一个内部导航链接rx.link指向/点击后触发卸载流程class UnmountState(rx.State): events: list[str] [] resource_id: str resource-12345 status: str Resource active rx.event def on_unmount(self): self.events self.events[-4:] [on_unmount str(datetime.now())] self.status fResource {self.resource_id} cleaned up rx.event def initialize_resource(self): self.status fResource {self.resource_id} initialized def unmount_example(): return rx.vstack( rx.heading(Unmount Demo, as_h2), rx.foreach(UnmountState.events, rx.text), rx.text(UnmountState.status), rx.link( rx.button(Navigate Away (Triggers Unmount)), href/, ), on_mountUnmountState.initialize_resource, on_unmountUnmountState.on_unmount, )生命周期事件的源码定义在仓库中on_mount与on_unmount是组件的默认事件触发器之一定义于 component.pyEventTriggers.ON_MOUNT: TriggerDefinition( specno_args_event_spec, descriptionFired when the component is mounted to the page., ), EventTriggers.ON_UNMOUNT: TriggerDefinition( specno_args_event_spec, descriptionFired when the component is removed from the page. Only called during navigation, not on page refresh., ),集成测试 test_event_chain.py 验证了on_mount/on_unmount与事件链的执行顺序并特别指出在 dev 模式下React StrictMode 会导致这些事件触发两次prod 模式下仅触发一次。这是调试生命周期事件时需要注意的重要细节。页面加载事件on_load除了组件生命周期事件Reflex 还提供页面级事件on_load在页面加载时触发。它的典型用途包括页面首次加载时获取数据检查认证状态初始化页面级状态为 cookie 或浏览器存储设置默认值。在 on_load 中获取数据on_load事件处理器通过rx.page装饰器的on_load参数或app.add_page()方法指定class State(rx.State): data: dict dict() rx.event def get_data(self): # Fetch data when the page loads self.data fetch_data() rx.page(on_loadState.get_data) def index(): return rx.text(Data loaded on page load)在 on_load 中做认证检查on_load尤其适合实现路由保护页面加载时检查认证状态未认证则通过rx.redirect重定向到登录页class State(rx.State): authenticated: bool False rx.event def check_auth(self): # Check if user is authenticated self.authenticated check_auth() if not self.authenticated: return rx.redirect(/login) rx.page(on_loadState.check_auth) def protected_page(): return rx.text(Protected content)on_load 的加载与错误处理页面在on_load处理器完成前就会渲染因此在处理器中做重量级同步工作会让用户面对陈旧或空白数据。官方建议详见 页面加载事件文档网络或数据库调用使用异步处理器避免阻塞事件循环设置loading标志并通过yield立即推送到前端配合rx.cond渲染 spinner 或占位内容用try/except包裹耗时操作让失败以错误消息呈现而不是让页面永远处于加载中。class DataState(rx.State): data: dict {} loading: bool False error: str rx.event async def load_initial_data(self): self.loading True yield # Send the loading state to the frontend immediately. try: self.data await fetch_data() except Exception as e: self.error str(e) finally: self.loading False rx.page(on_loadDataState.load_initial_data) def index(): return rx.cond( DataState.loading, rx.spinner(), rx.cond( DataState.error ! , rx.text(fError: {DataState.error}), rx.text(fData loaded: {DataState.data}), ), )on_load 的源码与测试佐证从源码结构看on_load是页面级的配置项在 page.py 中on_load作为Page的参数被保存在 app.py 中add_page()接受on_load并将其绑定到页面state.py 中定义了专门用于枚举并排队on_load处理器的子状态。集成测试 test_dynamic_routes.py 验证了通过链接在动态页面间导航时on_load的正确触发顺序包括/404页面同样支持on_load。交互型事件触发器参考以下触发器均为组件 props具体支持情况以各组件文档为准。官方文档为每个触发器提供了可直接运行的演示。on_focus 与 on_bluron_focus在元素或其内部元素获得焦点时调用例如用户点击文本输入框on_blur在焦点离开元素或其内部元素时调用例如用户点击输入框外部class FocusState(rx.State): text: str Change Me! rx.event def change_text(self, text): if self.text Change Me!: self.text Changed! else: self.text Change Me! def focus_example(): return rx.input(valueFocusState.text, on_focusFocusState.change_text)class BlurState(rx.State): text: str Change Me! rx.event def change_text(self, text): if self.text Change Me!: self.text Changed! else: self.text Change Me! def blur_example(): return rx.input(valueBlurState.text, on_blurBlurState.change_text)on_changeon_change在元素的值发生变化时调用。例如用户向文本输入框键入内容时每次击键都会触发一次class ChangeState(rx.State): checked: bool False rx.event def set_checked(self): self.checked not self.checked def change_example(): return rx.switch(on_changeChangeState.set_checked)on_clickon_click在用户点击元素时调用是使用频率最高的触发器例如点击按钮class ClickState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def click_example(): return rx.button(ClickState.text, on_clickClickState.change_text)on_context_menuon_context_menu在用户右键点击元素时调用例如右键点击按钮class ContextState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def context_menu_example(): return rx.button(ContextState.text, on_context_menuContextState.change_text)on_double_clickon_double_click在用户双击元素时调用例如双击按钮class DoubleClickState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def double_click_example(): return rx.button( DoubleClickState.text, on_double_clickDoubleClickState.change_text )鼠标事件系列以下触发器覆盖鼠标的完整交互状态on_mouse_up用户在某元素上释放鼠标按键时调用例如释放左键on_mouse_down用户在某元素上按下鼠标按键时调用例如按下左键on_mouse_enter鼠标进入元素时调用on_mouse_leave鼠标离开元素时调用on_mouse_move鼠标在元素上移动时调用on_mouse_out鼠标移出元素时调用on_mouse_over鼠标进入元素时调用。class MouseUpState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def mouse_up_example(): return rx.button(MouseUpState.text, on_mouse_upMouseUpState.change_text)on_mouse_down、on_mouse_enter、on_mouse_leave、on_mouse_move、on_mouse_out、on_mouse_over的写法完全相同只需替换状态类名、触发器名与组件绑定。注意on_mouse_enter/on_mouse_leave与on_mouse_over/on_mouse_out的语义区别enter/leave 不冒泡不会在鼠标穿过子元素时反复触发而 over/out 会冒泡。选择时需结合具体交互需求。class MouseEnterState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def mouse_enter_example(): return rx.button(MouseEnterState.text, on_mouse_enterMouseEnterState.change_text)on_scrollon_scroll在用户滚动页面时调用例如向下滚动页面。演示中通过overflowauto、height3em、width100%让容器产生滚动区域class ScrollState(rx.State): text: str Change Me! rx.event def change_text(self): if self.text Change Me!: self.text Changed! else: self.text Change Me! def scroll_example(): return rx.vstack( rx.text(Scroll to make the text below change.), rx.text(ScrollState.text), rx.text(Scroll to make the text above change.), on_scrollScrollState.change_text, overflowauto, height3em, width100%, )on_key_down 与 on_key_upon_key_down在元素获得焦点时用户按键时调用。处理器接收按键名称如Enter、Escape、a、ArrowUp以及描述活动修饰键的字典alt_key、ctrl_key、meta_key、shift_key。如果不需要修饰键信息处理器可以只接收按键名class KeyDownState(rx.State): message: str rx.event def handle_key_down(self, key: str): if key Enter: self.message You pressed Enter! else: self.message fLast key pressed: {key} def key_down_example(): return rx.vstack( rx.text(KeyDownState.message), rx.input( placeholderFocus me and press a key..., on_key_downKeyDownState.handle_key_down, ), )on_key_up在用户释放按键时调用接收与on_key_down相同的参数。从源码看按键事件的参数由key_event参数规范spec定义位于 event/init.py返回(e.key, {alt_key, ctrl_key, meta_key, shift_key})二元组。这意味着事件处理器既可以只接收key: str也可以接收(key, modifiers)两个参数。全局键盘事件window_event_listener元素上的on_key_down只在元素持有焦点时触发。若要在页面任意位置监听键盘事件例如实现全局快捷键可将on_key_down挂载到rx.window_event_listener组件——它监听浏览器 window 且不渲染任何可见输出class HotkeyState(rx.State): last_key_pressed: str rx.event def on_hotkey_press(self, key: str): if key not in (w, a, s, d): return self.last_key_pressed key def hotkey_example(): return rx.vstack( rx.text(Press w, a, s, or d anywhere on the page.), rx.text(fLast hotkey pressed: {HotkeyState.last_key_pressed}), rx.window_event_listener( on_key_downHotkeyState.on_hotkey_press, ), )window_event_listener 的完整能力该组件还提供了比文档示例更丰富的窗口级触发器定义于 window_events.py触发器触发时机处理器接收的参数on_resize浏览器窗口大小变化新的宽、高像素on_scroll用户滚动页面当前水平、垂直滚动位置on_focus浏览器标签页/窗口获得焦点如切回该标签页无on_blur浏览器标签页/窗口失去焦点如切到其他标签页无on_visibility_change页面变为可见或隐藏如切换标签页或最小化布尔值文档是否隐藏on_before_unload用户即将离开或关闭页面前无可用于清理或提示未保存更改on_key_down页面任意位置按键按键名与修饰键shift、ctrl、alt、metaon_popstate用户通过浏览器历史按钮前进/后退无on_storage其他标签页修改 localStorage 或 sessionStoragekey、旧值、新值、修改存储的文档 URL其底层实现window_events.py会在渲染时生成一个useEffecthook将on_前缀去掉、下划线移除后得到原生 JS 事件名如on_key_down→keydown通过window.addEventListener注册监听并在清理函数中removeEventListener。由于该组件继承自Fragment且排除了事件处理器 props因此不会产生任何可见 DOM 输出——这正是它可以隐形地实现全局监听的原因。触发器的默认参数规范源码视角在 component.py 中DEFAULT_TRIGGERS_AND_DESC定义了所有组件共享的默认事件触发器及其参数规范ArgsSpecno_args_event_spec处理器不接受额外参数——适用于on_focus、on_blur、on_mouse_up、on_mouse_down、on_mouse_enter、on_mouse_leave、on_mouse_move、on_mouse_out、on_mouse_over、on_scroll、on_mount、on_unmountpointer_event_spec处理器可接收指针事件信息按钮编号、坐标、修饰键等——适用于on_click、on_context_menu、on_double_clickkey_event处理器接收按键名与修饰键字典——适用于on_key_down、on_key_up。这意味着事件处理器的签名不是随意书写的定义处理器时必须与所挂载触发器的参数规范匹配而rx.event装饰器会在编译期帮助类型检查器校验这一点。例如on_clickClickState.change_text中的change_text(self)不接收参数而on_key_downKeyDownState.handle_key_down中的handle_key_down(self, key: str)接收按键名二者都符合各自触发器的规范。小结与选型建议一次性初始化与清理页面加载时的数据拉取优先使用rx.page(on_load...)组件出现/消失时的资源初始化与释放使用on_mount/on_unmount并牢记刷新与外部链接不会触发这两个组件生命周期事件。耗时操作在on_load、on_mount中做网络或数据库调用时务必使用异步处理器配合yield推送加载状态并用try/except处理失败。普通交互根据交互语义选择on_click、on_change、on_focus/on_blur、鼠标系列与on_scroll需要区分鼠标穿越子元素的重复触发时注意 enter/leave 与 over/out 的冒泡差异。键盘快捷键局部输入监听用元素的on_key_down/on_key_up全局热键用rx.window_event_listener还可顺带利用on_visibility_change、on_storage等窗口级触发器。参数规范匹配编写处理器时让签名与触发器的 ArgsSpec 对齐配合rx.event装饰器获得静态类型检查保障。开发模式注意dev 模式下 React StrictMode 会让on_mount/on_unmount触发两次生产环境只触发一次见 test_event_chain.py。更多细节可继续查阅 事件总览 与 页面加载事件以及各组件文档中的 event trigger 章节。【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考