uni-app 微信小程序开发：常用事件指令（@xxx）(一)

目录

[一、 点击与按压类指令](#一、 点击与按压类指令)

[1. @tap：手指点击](#1. @tap：手指点击)

[2. @longpress：长按事件](#2. @longpress：长按事件)

[二、 触摸与手势类指令](#二、 触摸与手势类指令)

[1. @touchstart：触摸开始](#1. @touchstart：触摸开始)

[2. @touchmove：触摸移动](#2. @touchmove：触摸移动)

[3. @touchend：触摸结束](#3. @touchend：触摸结束)

[三、 表单与输入类指令](#三、 表单与输入类指令)

[1. @input：实时输入](#1. @input：实时输入)

[2. @confirm：键盘回车/搜索](#2. @confirm：键盘回车/搜索)

[3. @change：值改变](#3. @change：值改变)

[4. @focus 与 @blur：聚焦与失焦](#4. @focus 与 @blur：聚焦与失焦)

[四、 滚动与视图类指令](#四、 滚动与视图类指令)

[1. @scroll：实时滚动](#1. @scroll：实时滚动)

[2. @scrolltolower：滚动到底部](#2. @scrolltolower：滚动到底部)

[3. @scrolltoupper：滚动到顶部](#3. @scrolltoupper：滚动到顶部)

[五、 多媒体与特殊系统指令](#五、 多媒体与特殊系统指令)

[1. @error：资源加载错误](#1. @error：资源加载错误)

[2. @load：资源加载完成](#2. @load：资源加载完成)

[3. 开放能力事件（如 @getphonenumber）](#3. 开放能力事件（如 @getphonenumber）)

[六、 补充：自定义组件事件 @自定义名](#六、 补充：自定义组件事件 @自定义名)

总结

在 uni-app 开发微信小程序的过程中，事件机制是连接视图层（WXML）和逻辑层（JS）的核心纽带。得益于 uni-app 采用 Vue 的语法规范，我们可以非常优雅地使用 v-on:（简写为 @）来绑定各种事件。

很多刚接触 uni-app 的开发者可能只知道 @tap 和 @click，但在实际的小程序业务开发中，表单输入、滚动加载、长按手势等交互场景非常丰富。

一、 点击与按压类指令

这类指令处理最基础的用户手指点击和长按交互，是日常开发中用到频率最高的一组。

1. @tap：手指点击

最基础、最常用的点击事件。手指触摸屏幕后马上离开时触发。

在 uni-app 中，底层会将 @tap 编译为微信小程序的 bindtap。强烈建议小程序端统一使用 @tap 替代 @click，以避免跨端时可能出现的 300ms 点击延迟问题。

<view @tap="handleTap">点击我</view>

2. @longpress：长按事件

手指触摸屏幕并超过 350ms 后离开时触发。常用于"长按删除图片"、"长按保存二维码"等场景。

<image src="..." @longpress="saveImage"></image>

避坑指南 ：早期版本有 @longtap 指令，但目前已不推荐使用，部分平台可能会与 @tap 产生冲突导致事件触发两次，请统一使用 @longpress。

二、 触摸与手势类指令

当需要实现自定义的手势交互（如拖拽元素、滑动翻页、手势解锁）时，就需要用到这组基础触摸事件。它们通常成组配合使用。

1. @touchstart：触摸开始

手指刚接触屏幕时触发。常用于记录触摸的初始坐标。

2. @touchmove：触摸移动

手指在屏幕上滑动时实时触发。常用于根据坐标差值改变元素的 left / top 实现拖拽跟手。

3. @touchend：触摸结束

手指离开屏幕时触发。常用于计算最终的滑动距离和速度，判断是左滑还是右滑。

实战示例：实现一个简单的拖拽盒子

<template>
  <view 
    class="box" 
    :style="{ transform: `translate(${x}px, ${y}px)` }"
    @touchstart="onStart" 
    @touchmove="onMove"
    @touchend="onEnd"
  ></view>
</template>

<script>
export default {
  data() {
    return { x: 0, y: 0, startX: 0, startY: 0 };
  },
  methods: {
    onStart(e) {
      // 记录按下时的初始位置
      this.startX = e.touches[0].clientX - this.x;
      this.startY = e.touches[0].clientY - this.y;
    },
    onMove(e) {
      // 实时计算偏移量
      this.x = e.touches[0].clientX - this.startX;
      this.y = e.touches[0].clientY - this.startY;
    },
    onEnd() {
      console.log('拖拽结束');
    }
  }
}
</script>

三、 表单与输入类指令

表单组件（<input>、<textarea>、<picker> 等）是小程序的刚需，掌握它们的事件指令至关重要。

1. @input：实时输入

每次键盘输入时触发。常用于搜索框的实时联想、或者文本框的字数实时统计。

注意 ：在 uni-app 中获取输入框的值，使用 e.detail.value。

<input type="text" @input="onInput" />
<!-- js: onInput(e) { console.log(e.detail.value) } -->

2. @confirm：键盘回车/搜索

当用户点击软键盘右下角的按钮（如"搜索"、"完成"、"前往"）时触发。配合 confirm-type="search" 是实现搜索功能的标配。

<input confirm-type="search" @confirm="doSearch" placeholder="输入并回车搜索" />

3. @change：值改变

常用于 <picker>（选择器）、<switch>（开关）、<radio>（单选框）等。当用户做出选择导致值发生改变时触发。

<picker mode="selector" :range="array" @change="bindPickerChange">
  <view>请选择</view>
</picker>

4. @focus 与 @blur：聚焦与失焦

输入框获取焦点（弹出键盘）和失去焦点（收起键盘）时触发。常用于输入内容的格式校验，或者解决键盘弹起遮挡底部按钮的问题。

四、 滚动与视图类指令

在小程序中实现"长列表分页加载"、"下拉刷新"或"吸顶导航"时，离不开 scroll-view 组件及其滚动事件。

1. @scroll：实时滚动

滚动视图内滚动时实时触发。可以通过 event.detail.scrollTop 获取当前滚动距离。常用于控制"回到顶部"按钮的显示与隐藏。

2. @scrolltolower：滚动到底部

极其常用。当滚动条滚动到底部时触发，这是实现"触底加载下一页数据"的核心指令。

<scroll-view scroll-y @scrolltolower="loadMore" lower-threshold="50">
  <view v-for="item in list" :key="item.id">{{item.name}}</view>
  <view class="loading">正在加载更多...</view>
</scroll-view>

3. @scrolltoupper：滚动到顶部

滚动到顶部时触发，常用于局部区域的自定义下拉刷新逻辑。

五、 多媒体与特殊系统指令

1. @error：资源加载错误

当 <image> 或 <video> 加载失败时触发。实际开发中常用来做图片加载失败的兜底图替换。

<image src="user.avatar" @error="handleImageError"></image>
<!-- js: handleImageError() { this.user.avatar = '/static/default.png' } -->

2. @load：资源加载完成

图片或视频加载成功时触发，常用于计算图片的宽高比以做自适应缩放。

3. 开放能力事件（如 @getphonenumber）

微信小程序提供了很多原生能力，通常需要配合 <button> 组件的 open-type 属性使用。

<button open-type="getPhoneNumber" @getphonenumber="getPhone">一键获取手机号</button>
<button open-type="share" @tap="share">分享给好友</button>

六、 补充：自定义组件事件 @自定义名

除了内置指令，在 uni-app 中开发自定义组件时，子组件可以通过 this.$emit 触发任意自定义事件，父组件同样使用 @ 来监听。

子组件 Child.vue：

methods: {
  submit() {
    this.$emit('confirm', { id: 1, status: 'ok' });
  }
}

父组件：

<template>
  <Child @confirm="handleChildConfirm"></Child>
</template>
<script>
export default {
  methods: {
    handleChildConfirm(data) {
      console.log('接收到子组件传来的数据:', data);
    }
  }
}
</script>

总结

在 uni-app 微信小程序开发中，事件指令虽然多，但只要按场景分类记忆，就能迅速掌握：

1. 基础交互 记住 @tap 和 @longpress。
2. 自定义手势 记住 @touchstart / @touchmove / @touchend 三剑客。
3. 表单操作 记住 @input（实时取值）、@change（选择器变化）、@confirm（回车提交）。
4. 滚动列表 记住 @scrolltolower（触底加载）。
5. 组件通信 灵活使用 @自定义事件名。

掌握这些高频事件指令，配合 uni-app 提供的 .stop、.self 等事件修饰符，就能写出结构清晰、交互流畅的小程序代码了。