一、 基础交互与手势事件
在 uni-app 移动端开发中，手势事件是最基础的交互能力，常见于按钮点击、列表操作、长按菜单以及拖拽等场景。
| 事件名称 | 触发时机 | 实际开发场景 |
|---|---|---|
@tap | 手指触摸后马上离开 | 按钮点击、列表项跳转、弹窗关闭（强烈建议替代@click） |
@longpress | 手指触摸屏幕超过 350ms 后触发 | 长按图片保存、长按消息弹出“删除/复制”菜单 |
@touchstart | 手指刚接触屏幕时触发 | 记录拖拽元素的初始坐标 |
@touchmove | 手指在屏幕上持续滑动时触发 | 配合touchstart实现拖拽跟手、滑动抽屉菜单 |
@touchend | 手指离开屏幕时触发 | 拖拽结束后的位置吸附、判断左滑/右滑操作 |
二、表单与输入事件
当页面中存在<input>、<textarea>、<picker>等表单组件时，需要用到以下事件。
| 事件名称 | 触发时机 | 实际开发场景 |
|---|---|---|
@input | 输入框内容发生变化时实时触发 | 搜索框的实时联想词提示、输入框右下角的字数统计 |
@confirm | 点击软键盘右下角按钮（如“搜索/完成”）时触发 | 用户在搜索框输入关键词后，点击键盘上的“搜索”键执行查询 |
@change | 表单组件的值发生改变且用户确认时触发 | 切换开关（switch）、选择日期（picker）后更新页面数据 |
@focus | 输入框获取焦点（键盘弹起）时触发 | 解决键盘弹起时遮挡底部输入框或按钮的问题 |
@blur | 输入框失去焦点（键盘收起）时触发 | 用户输入完毕后，对填写的手机号进行格式校验 |
@submit | 表单提交时触发 | 点击提交按钮，收集所有表单数据并发送给后端接口 |
三、滚动与视图事件
主要用于处理长列表、轮播图等需要监听滚动状态的组件（如<scroll-view>、<swiper>）。
| 事件名称 | 触发时机 | 实际开发场景 |
|---|---|---|
@scroll | 滚动视图滚动时触发 | 监听滚动距离，实现“回到顶部”按钮的显示与隐藏 |
@scrolltolower | 滚动到底部/右边时触发 | 核心场景：实现列表的下拉加载更多（分页请求） |
@scrolltoupper | 滚动到顶部/左边时触发 | 实现滚动到顶部时的特殊提示或刷新 |
@load | 媒体资源（如 image）加载完成时触发 | 图片加载完成前显示骨架屏或 loading 动画 |
@error | 媒体资源加载失败时触发 | 图片加载失败时，替换为默认的“加载失败”占位图 |
四、全局事件总线（跨页面/跨组件通信）
当两个页面或组件之间没有直接的父子关系，但需要互相传递数据时，使用 uni-app 提供的全局事件 API。
| API 方法 | 作用 | 实际开发场景 |
|---|---|---|
uni.$on(eventName, callback) | 订阅（监听）一个全局事件 | 在首页onLoad时注册监听，等待其他页面发来通知 |
uni.$emit(eventName, data) | 发布（触发）一个全局事件 | 登录页登录成功后，触发事件并携带用户信息，通知首页更新 |
uni.$off(eventName, callback) | 取消订阅（移除监听） | ⚠️ 必做：在onUnload或beforeDestroy中移除监听，防止内存泄漏 |
uni.$once(eventName, callback) | 只监听一次全局事件 | 触发一次后自动移除监听，适用于只需执行一次的初始化逻辑 |
五、实战避坑指南
- 统一使用
@tap：在小程序端，@click可能会有 300ms 的点击延迟，强烈建议全项目统一使用@tap替代@click。 - 全局事件必须成对出现：使用了
uni.$on，就必须在页面销毁时（onUnload）使用uni.$off移除它。如果不移除，每次进入页面都会叠加一次监听，导致一次触发执行多次回调，引发严重的 Bug。 - 事件名命名规范：全局事件名建议使用全小写加中划线（如
login-success），千万不要以uni.开头，以免与框架内部系统事件冲突。 - 获取事件参数：在 Vue3 中，处理事件时记得通过
e.detail获取数据。例如输入框的值是e.detail.value，而不是e.target.value。
