# 组件的公共属性和事件

每个组件都有属性和事件。有些属性和事件,是所有组件都支持的。

调整

  1. uni-app x 4.0+ ,组件事件类型的名称增加 Uni 前缀,避免与浏览器全局事件冲突
  2. 非 Uni 开头的事件类型名称被标记为废弃,功能不受影响。
  3. 如您使用uni-app x 4.0以下版本,仍需去掉 Uni 前缀

变更示例

<template>
  <slider @change="sliderChange" />
</template>
<script>
  export default {
    data() {
      return {
      }
    },
    methods: {
      // 变更之前类型为 SliderChangeEvent
      // sliderChange(e : SliderChangeEvent) {
      // }

      // 变更之后类型为 UniSliderChangeEvent
      sliderChange(e : UniSliderChangeEvent) {
      }
    }
  }
</script>

# 组件公共属性

名称 类型 描述
id string(string.IDString) 组件的唯一标识,一般用于获取组件上下文对象
style string 组件的内联样式,可以动态设置的内联样式
class string(string.ClassString) 组件的样式类,在对应的 css 中定义的样式类
ref string vue中组件的唯一标识,用来给子组件注册引用信息
data-* any 自定义属性,组件上触发的事件时,会发送给事件处理函数
android-* any App-Android平台专有属性,详见App-Android平台专有属性章节
Android iOS web
id 3.9 4.11 4.0
style 3.9 4.11 4.0
class 3.9 4.11 4.0
ref 3.9 4.11 4.0
data-* 3.9 4.11 4.0
android-* 3.9 x 4.0

# App-Android平台专有属性

android-开头的属性名称为App-Android平台专有属性

# android-layer-type HBuilderX 4.01+

不支持动态修改此属性

更多信息可参考Android官方文档硬件加速

App-Android平台设置组件视图渲染模型,字符串类型,可取值:

  • "hardware": 视图在硬件中渲染为硬件纹理
  • "software": 视图在软件中渲染为位图
  • "none": 视图正常渲染,不使用缓冲区 默认值为"none"。

Tips

  • 通过DrawableContext或其他方式绘制复杂图形时,建议设置为hardware
  • 执行复杂动画或大量动画时,建议设置为hardware

# 示例

hello uni-app x

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
    <!-- #endif -->
    <view>
      <page-head :title="title"></page-head>
      <view class="uni-padding-wrap">
        <view
          :id="generalId"
          :class="generalClass"
          :name="generalName"
          :title="generalTitle"
          :data-test="generalData"
          :style="generalStyle"
          ref="general-target"
        >
          <text>id: {{ generalId }}</text>
          <text>class: {{ generalClass }}</text>
          <text>name: {{ generalName }}</text>
          <text>title: {{ generalTitle }}</text>
          <text>data-test: {{ generalData }}</text>
          <text>style: {{ generalStyle }}</text>
        </view>
        <view
          class="btn btn-style uni-common-mt"
          @click="validateGeneralAttributes"
        >
          <text class="btn-inner">{{ validateGeneralAttrText }}</text>
        </view>
        <view class="btn btn-ref uni-common-mt" @click="changeHeight">
          <text class="btn-inner">{{changeHeightByRefText}}</text>
        </view>
        <view class="view-class" :hover-class="hoverClass" ref="view-target">
          <text class="text">按下 50 ms 后背景变红</text>
          <text class="text">抬起 400 ms 后背景恢复</text>
        </view>
        <view
          class="view-class"
          :hover-class="hoverClass"
          :hover-start-time="1000"
          :hover-stay-time="1000"
          ref="view-target"
        >
          <text class="text">按下 1000 ms 后背景变红</text>
          <text class="text">抬起 1000 ms 后背景恢复</text>
        </view>
      </view>
    </view>
    <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>



<style>
.btn {
  height: 50px;
  display: flex;
  align-items: center;
  justify-content: center;
  background-color: #409eff;
  border-radius: 5px;
}
.btn-inner {
  color: #fff;
}
.general-class {
  margin-left: 40px;
  padding: 10px;
  width: 260px;
  height: 160px;
  background-color: antiquewhite;
}
.view-class {
  margin: 20px 0 0 50px;
  padding: 10px;
  width: 240px;
  height: 100px;
  background-color: antiquewhite;
}
.view-class .text {
  margin-top: 5px;
  text-align: center;
}
.hover-class {
  background-color: red;
}
</style>

# 组件公共事件

名称 类型 描述
@click (event: UniPointerEvent) => void 手指触摸后马上离开。与tap相同,(推荐使用tap事件代替),冒泡事件
@mousedown (event: UniMouseEvent) => void 鼠标在元素上点击后触发
@mousemove (event: UniMouseEvent) => void 鼠标在元素上移动时触发
@mouseup (event: UniMouseEvent) => void 鼠标主按钮在元素上松开时触发
@touchstart (event: UniTouchEvent) => void 手指触摸动作开始,冒泡事件,event.type 值为 touchstart
@touchmove (event: UniTouchEvent) => void 手指触摸后移动,冒泡事件,event.type 值为 touchmove
@touchcancel (event: UniTouchEvent) => void 手指触摸动作被打断,如来电提醒,弹窗,冒泡事件,event.type 值为 touchcancel
@touchend (event: UniTouchEvent) => void 手指触摸动作结束,冒泡事件,event.type 值为 touchend
@tap (event: UniPointerEvent) => void 手指触摸后马上离开,冒泡事件
@longpress (event: UniTouchEvent) => void 如果一个组件被绑定了 longpress 事件,那么当用户手指触摸后,超过350ms再离开会触发,冒泡事件
@longtap (event: UniTouchEvent) => void 手指触摸后,超过350ms再离开(推荐使用 longpress 事件代替)
@transitionend (event: UniEvent) => void transition 效果结束时触发
Android iOS web
@click 3.9 4.11 4.0
@mousedown x x 4.0
@mousemove x x 4.0
@mouseup x x 4.0
@touchstart 3.9 4.11 4.0
@touchmove 3.9 4.11 4.0
@touchcancel 3.9 4.11 4.0
@touchend 3.9 4.11 4.0
@tap 3.9 4.11 4.0
@longpress 3.9 4.11 4.0
@longtap 3.9 4.11 4.0
@transitionend 3.93 4.11 4.0

# 示例

hello uni-app x

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
  <!-- #endif -->
    <page-head title="触摸方块测试相关事件"></page-head>
    <view class="uni-padding-wrap uni-common-mt container">
      <view class="target" @touchstart="onTouchStart" @touchcancel="onTouchCancel" @touchmove="onTouchMove"
        @touchend="onTouchEnd" @tap="onTap" @click="onClick" @longpress="onLongPress"></view>
      <view v-if="touchStartEvent !== null">
        <text class="title1">touchStart Event: </text>
        <text class="title2">touches: </text>
        <template v-for="(touch, index) in touchStartEvent!.touches" :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
        <text class="title2 uni-common-mt">changedTouches: </text>
        <template v-for="(touch, index) in touchStartEvent!.changedTouches" :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
      </view>
      <view v-if="touchCancelEvent !== null">
        <text class="title1">touchCancel Event: </text>
        <text class="title2">touches: </text>
        <template v-for="(touch, index) in touchCancelEvent!.touches" :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
        <text class="title2 uni-common-mt">changedTouches: </text>
        <template v-for="(touch, index) in touchCancelEvent!.changedTouches" :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
      </view>
      <view v-if="touchMoveEvent !== null">
        <text class="title1">touchMove Event: </text>
        <text class="title2">touches: </text>
        <template v-for="(touch, index) in touchMoveEvent!.touches" :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
        <text class="title2 uni-common-mt">changedTouches: </text>
        <template v-for="(touch, index) in touchMoveEvent!.changedTouches" :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
      </view>
      <view v-if="longPressEvent !== null">
        <text class="title1">longPress Event: </text>
        <text class="title2">touches: </text>
        <template v-if="longPressEvent!.touches.length > 0" v-for="(touch, index) in longPressEvent!.touches"
          :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
        <text class="title2 uni-common-mt">changedTouches: </text>
        <template v-for="(touch, index) in longPressEvent!.changedTouches" :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
      </view>
      <view v-if="touchEndEvent !== null">
        <text class="title1">touchEnd Event: </text>
        <text class="title2">touches: </text>
        <template v-if="touchEndEvent!.touches.length > 0" v-for="(touch, index) in touchEndEvent!.touches"
          :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
        <text class="title2 uni-common-mt">changedTouches: </text>
        <template v-for="(touch, index) in touchEndEvent!.changedTouches" :key="index">
          <text class="title3">touch[{{ index }}]:</text>
          <text>identifier: {{touch.identifier}}</text>
          <text>pageX: {{ touch.pageX }}, pageY: {{ touch.pageY }}</text>
          <text>clientX: {{ touch.clientX }}, clientY: {{ touch.clientY }}</text>
          <text>screenX: {{ touch.screenX }}, screenY: {{ touch.screenY }}</text>
        </template>
      </view>
      <view v-if="tapEvent !== null">
        <text class="title1">tap Event: </text>
        <text>x: {{ tapEvent!.x }}, y: {{ tapEvent!.y }}</text>
      </view>
      <view v-if="clickEvent !== null">
        <text class="title1">click Event: </text>
        <text>x: {{ clickEvent!.x }}, y: {{ clickEvent!.y }}</text>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>


<style>
  .container {
    padding-bottom: 10px;
  }

  .target {
    margin: 20px 0 0 50px;
    width: 200px;
    height: 100px;
    background-color: aqua;
  }

  .title1 {
    margin-top: 15px;
    font-size: 20px;
  }

  .title2 {
    margin-top: 10px;
    font-size: 18px;
  }

  .title3 {
    margin-top: 5px;
    font-size: 16px;
  }
</style>

# touch 事件

触摸事件包括:touchstart、touchmove、touchcancel、touchend 等。

在多点触摸的屏幕上,touch事件返回数组,包含了每个touch点对应的x、y坐标。

# tap/click 事件

# App端

  • HBuilderX4.0及以下版本手指按下后移动会取消tap/click事件的触发,即手指移动后抬起不会响应tap/click事件
  • HBuilder4.0及以上版本App端调整手指按下后在组件区域内移动不会取消tap/click事件的触发,移动到组件区域外才会取消tap/click事件的触发

# Web端

手指按下后移动会取消tap/click事件的触发,即手指移动后抬起不会响应tap/click事件

# transition 事件

  • @transitionend

    transition 效果结束时触发

    # 兼容性

    安卓 3.93+ 版本开始支持

    <template>
      <image class="transition-transform" id="transition-transform" @transitionend="onEnd" src="/static/uni.png"></image>
    </template>
    <script>
      export default {
        data() {
          return {}
        },
        onReady() {
          var element = uni.getElementById('transition-transform')
          element!.style.setProperty('transform', 'rotate(360deg)')
        },
        methods: {
          onEnd() {
            console.log("transition效果结束")
          }
        }
      }
    </script>
    
    <style>
      .transition-transform {
        transition-duration: 2000;
        transition-property: transform;
        transform: rotate(0deg);
      }
    </style>
    

# 冒泡事件系统

DOM事件主要有三个阶段:捕获阶段目标阶段冒泡阶段

uvue 目前暂不支持事件的捕获阶段。

以点击事件为例,当触发点击时,

  1. 首先从根节点逐级向下分发,直到监听点击事件的节点为止(捕获阶段);
  2. 然后事件到达当前节点并触发点击事件(目标阶段);
  3. 接着继续向上逐级触发父节点的点击事件,直到根节点为止(冒泡阶段)。

注意

虽然有3个阶段,但第2个阶段(“目标阶段”:事件到达了元素)并没有单独处理:捕获和冒泡阶段的处理程序都会在该阶段触发。

我们一般使用默认的事件注册机制,将事件注册到冒泡阶段,相对来说,大多数处理情况都在冒泡阶段。

# 阻止冒泡

在事件回调中,可以通过调用event.stopPropagation方法阻止事件冒泡。

handleClick (event : UniPointerEvent) {
    // 阻止继续冒泡.
    event.stopPropagation();
}

# 阻止默认行为

在事件回调中,可以通过调用event.preventDefault方法阻止默认行为。event.preventDefault仅处理默认行为,事件冒泡不会被阻止。

<template>
	<scroll-view style="flex: 1;">
		<view style="width: 750rpx;height: 1750rpx;background-color: bisque;">
			滑动框中区域修改进度并阻止滚动,滑动其余空白区域触发滚动
			<view style="width: 750rpx;height: 40rpx; margin-top: 100rpx;border:5rpx;" @touchmove="slider">
				<view ref="view1" style="background-color: chocolate;width: 0rpx;height: 30rpx;"></view>
			</view>
		</view>
	</scroll-view>
</template>
<script>
	export default {
		data() {
			return {
				$view1Element: null as UniElement | null
			}
		},
    onReady() {
      this.$view1Element = this.$refs['view1'] as UniElement
    },
		methods: {
			slider(e : TouchEvent) {
				e.preventDefault() // 阻止外层scroll-view滚动行为
				this.$view1Element!.style?.setProperty('width', e.touches[0].screenX);
			}
		}
	}
</script>

# Bug & Tips

  • HBuilder X 4.0以前,连续触发clicktap事件,可能会出现事件丢失的情况。请升级新版

# UniEvent

# 构造函数

名称 类型 必备 默认值 描述
type string - 事件的名称

# 构造函数

名称 类型 必备 默认值 描述
type string - 事件的名称
eventInit UTSJSONObject - 事件初始参数。支持字段:bubbles表明该事件是否冒泡。可选,默认为false;cancelable表明该事件是否可以被取消。可选,默认为false。

# UniEvent 的属性值

名称 类型 必备 默认值 描述
bubbles boolean - 是否冒泡
cancelable boolean - 是否可以取消
type string - 事件类型
target UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number - 事件发生时的时间戳

# UniEvent 方法

# stopPropagation()

阻止当前事件的进一步传播

# preventDefault()

阻止当前事件的默认行为

# preventDefault 兼容性
Android iOS web
3.9 x 4.0

# UniCustomEvent

# 构造函数

名称 类型 必备 默认值 描述
type string - -
detail T - -

# 构造函数

名称 类型 必备 默认值 描述
type string - -
options any - -

# UniCustomEvent 的属性值

名称 类型 必备 默认值 描述
detail T - -
bubbles boolean - 是否冒泡
cancelable boolean - 是否可以取消
type string - 事件类型
target UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number - 事件发生时的时间戳

# UniCustomEvent 方法

# stopPropagation()

阻止当前事件的进一步传播

# preventDefault()

阻止当前事件的默认行为

# preventDefault 兼容性
Android iOS web
3.9 x 4.0

# UniPointerEvent

# UniPointerEvent 的属性值

名称 类型 必备 默认值 描述
clientX number - 相对于页面可显示区域左边的距离
clientY number - 相对于页面可显示区域顶部的距离
x number - 相对于页面可显示区域左边的距离,同clientX
y number - 相对于页面可显示区域顶部的距离,同clientY
pageX number - 相对于文档左边的距离
pageY number - 相对于文档顶部的距离
screenX number - 相对于屏幕左边距离
screenY number - 相对于屏幕顶部的距离
bubbles boolean - 是否冒泡
cancelable boolean - 是否可以取消
type string - 事件类型
target UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number - 事件发生时的时间戳

# UniPointerEvent 的方法

# stopPropagation()

阻止当前事件的进一步传播

# preventDefault()

阻止当前事件的默认行为

# preventDefault 兼容性
Android iOS web
3.9 x 4.0

# UniTouchEvent

# UniTouchEvent 的属性值

名称 类型 必备 默认值 描述
touches Array<UniTouch> - 当前停留在屏幕中的触摸点信息的数组
名称 类型 必备 默认值 描述
clientX number - 相对于页面可显示区域左边的距离
clientY number - 相对于页面可显示区域顶部的距离
identifier number - 触摸点的标识符。这个值在这根手指所引发的所有事件中保持一致,直到手指抬起。
pageX number - 相对于文档左边的距离
pageY number - 相对于文档顶部的距离
screenX number - 相对于屏幕左边距离
screenY number - 相对于屏幕顶部的距离
force number | null - 返回当前触摸点按下的压力大小
changedTouches Array<UniTouch> - 当前变化的触摸点信息的数组
名称 类型 必备 默认值 描述
clientX number - 相对于页面可显示区域左边的距离
clientY number - 相对于页面可显示区域顶部的距离
identifier number - 触摸点的标识符。这个值在这根手指所引发的所有事件中保持一致,直到手指抬起。
pageX number - 相对于文档左边的距离
pageY number - 相对于文档顶部的距离
screenX number - 相对于屏幕左边距离
screenY number - 相对于屏幕顶部的距离
force number | null - 返回当前触摸点按下的压力大小
bubbles boolean - 是否冒泡
cancelable boolean - 是否可以取消
type string - 事件类型
target UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number - 事件发生时的时间戳

UniTouchEvent 的 type 类型包括:touchstart、touchmove、touchend、touchcancel、longpress。

# UniTouchEvent 方法

# stopPropagation()

阻止当前事件的进一步传播

# preventDefault()

阻止当前事件的默认行为

# preventDefault 兼容性
Android iOS web
3.9 x 4.0

# UniTouch

# UniTouch 的属性值

名称 类型 必备 默认值 描述
clientX number - 相对于页面可显示区域左边的距离
clientY number - 相对于页面可显示区域顶部的距离
identifier number - 触摸点的标识符。这个值在这根手指所引发的所有事件中保持一致,直到手指抬起。
pageX number - 相对于文档左边的距离
pageY number - 相对于文档顶部的距离
screenX number - 相对于屏幕左边距离
screenY number - 相对于屏幕顶部的距离
force number | null - 返回当前触摸点按下的压力大小

# UniMouseEvent

# UniMouseEvent 的属性值

名称 类型 必备 默认值 描述
clientX number - 相对于页面可显示区域左边的距离
clientY number - 相对于页面可显示区域顶部的距离
x number - 相对于页面可显示区域左边的距离,同clientX
y number - 相对于页面可显示区域顶部的距离,同clientY
pageX number - 相对于文档左边的距离
pageY number - 相对于文档顶部的距离
screenX number - 相对于屏幕左边距离
screenY number - 相对于屏幕顶部的距离
bubbles boolean - 是否冒泡
cancelable boolean - 是否可以取消
type string - 事件类型
target UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
currentTarget UniElement | null - UVUE DOM 元素对象,描述了 UVUE DOM 元素所普通具有的属性和方法。
timeStamp number - 事件发生时的时间戳

# UniMouseEvent 的方法

# stopPropagation()

阻止当前事件的进一步传播

# preventDefault()

阻止当前事件的默认行为

# preventDefault 兼容性
Android iOS web
3.9 x 4.0

# 参见