common.md 9.6 KB
Newer Older
D
DCloud_LXH 已提交
1
# 组件的全局属性和事件
D
DCloud_LXH 已提交
2 3 4

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

D
DCloud_LXH 已提交
5
## 组件全局属性
D
DCloud_LXH 已提交
6

7 8 9
<!-- CUSTOMTYPEJSON.general-attribute.attribute -->

<!-- CUSTOMTYPEJSON.general-attribute.compatibility -->
DCloud-yyl's avatar
DCloud-yyl 已提交
10

D
DCloud_LXH 已提交
11
### App-Android平台专有属性@attribute-android
DCloud-yyl's avatar
DCloud-yyl 已提交
12

D
DCloud_LXH 已提交
13 14 15 16 17 18 19
> android-开头的属性名称为App-Android平台专有属性

#### android-layer-type <Badge text="HBuilderX 4.01+">

> 不支持动态修改此属性
>
> 更多信息可参考Android官方文档[硬件加速](https://developer.android.google.cn/topic/performance/hardware-accel?hl=zh-cn)。
DCloud-yyl's avatar
DCloud-yyl 已提交
20 21

App-Android平台设置组件视图渲染模型,字符串类型,可取值:
D
DCloud_LXH 已提交
22 23 24
- "hardware": 视图在硬件中渲染为硬件纹理
- "software": 视图在软件中渲染为位图
- "none": 视图正常渲染,不使用缓冲区
DCloud-yyl's avatar
DCloud-yyl 已提交
25 26
默认值为"none"。

D
DCloud_LXH 已提交
27
::: tip Tips
张磊 已提交
28 29
- 通过[DrawableContext](../dom/drawablecontext.md)或其他方式绘制复杂图形时,建议设置为`hardware`
- 执行复杂动画或大量动画时,建议设置为`hardware`
30
- 由于安卓原生限制,当设置`android-layer-type``hardware``software`时,`overflow: visible`不生效。
D
DCloud_LXH 已提交
31
:::
D
DCloud_LXH 已提交
32

33
<!-- CUSTOMTYPEJSON.general-attribute.example -->
D
DCloud_LXH 已提交
34

D
DCloud_LXH 已提交
35 36 37 38 39
### 参见

- [相关 Bug](https://issues.dcloud.net.cn/?mid=component.global-properties-events.global-properties)

## 组件全局事件
D
DCloud_LXH 已提交
40

41
<!-- CUSTOMTYPEJSON.general-event.attribute -->
DCloud-yyl's avatar
DCloud-yyl 已提交
42

43
<!-- CUSTOMTYPEJSON.general-event.compatibility -->
DCloud-yyl's avatar
DCloud-yyl 已提交
44

D
DCloud_LXH 已提交
45 46
<!-- CUSTOMTYPEJSON.general-event.example -->

DCloud-yyl's avatar
DCloud-yyl 已提交
47 48
### touch 事件@touch
触摸事件包括:touchstart、touchmove、touchcancel、touchend 等。
D
DCloud_LXH 已提交
49

D
DCloud_LXH 已提交
50
在多点触摸的屏幕上,touch事件返回数组,包含了每个touch点对应的x、y坐标。
DCloud-yyl's avatar
DCloud-yyl 已提交
51

D
DCloud_LXH 已提交
52
### tap/click 事件@tap
DCloud-yyl's avatar
DCloud-yyl 已提交
53

DCloud_Heavensoft's avatar
DCloud_Heavensoft 已提交
54 55
- App端
App端手指按下后在组件区域内移动不会取消tap/click事件的触发,移动到组件区域外才会取消tap/click事件的触发。
DCloud-yyl's avatar
DCloud-yyl 已提交
56

DCloud_Heavensoft's avatar
DCloud_Heavensoft 已提交
57 58 59
注意老版问题:uni-app x 4.0及以下版本手指按下后移动会取消tap/click事件的触发,即手指移动后抬起不会响应tap/click事件。

- Web端
DCloud-yyl's avatar
DCloud-yyl 已提交
60 61
手指按下后移动会取消tap/click事件的触发,即手指移动后抬起不会响应tap/click事件

D
DCloud_LXH 已提交
62 63 64 65 66 67

### transition 事件

- @transitionend

	transition 效果结束时触发
D
DCloud_LXH 已提交
68

D
DCloud_LXH 已提交
69
	#### 兼容性
D
DCloud_LXH 已提交
70

D
DCloud_LXH 已提交
71
	安卓 3.93+ 版本开始支持
D
DCloud_LXH 已提交
72

D
DCloud_LXH 已提交
73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
  ```vue
  <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效果结束")
        }
D
DCloud_LXH 已提交
90 91
      }
    }
D
DCloud_LXH 已提交
92
  </script>
D
DCloud_LXH 已提交
93

D
DCloud_LXH 已提交
94 95
  <style>
    .transition-transform {
张磊 已提交
96
      transition-duration: 2000ms;
D
DCloud_LXH 已提交
97 98 99 100 101
      transition-property: transform;
      transform: rotate(0deg);
    }
  </style>
  ```
D
DCloud_LXH 已提交
102 103 104

### 冒泡事件系统

D
DCloud_LXH 已提交
105 106 107
> DOM事件主要有三个阶段:`捕获阶段`、`目标阶段`和`冒泡阶段`。
>
> `uvue` 目前暂不支持事件的捕获阶段。
D
DCloud_LXH 已提交
108 109 110 111 112 113

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

D
DCloud_LXH 已提交
114 115
::: warning 注意
虽然有3个阶段,但第2个阶段(“目标阶段”:事件到达了元素)并没有单独处理:捕获和冒泡阶段的处理程序都会在该阶段触发。
D
DCloud_LXH 已提交
116 117

我们一般使用默认的事件注册机制,将事件注册到冒泡阶段,相对来说,大多数处理情况都在冒泡阶段。
D
DCloud_LXH 已提交
118
:::
D
DCloud_LXH 已提交
119 120 121 122 123 124

#### 阻止冒泡

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

```ts
DCloud-yyl's avatar
DCloud-yyl 已提交
125
handleClick (event : UniPointerEvent) {
D
DCloud_LXH 已提交
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
    // 阻止继续冒泡.
    event.stopPropagation();
}
```

#### 阻止默认行为

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

```vue
<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>
```

dc_zhanglei's avatar
dc_zhanglei 已提交
166 167
### Bug & Tips

DCloud_Heavensoft's avatar
DCloud_Heavensoft 已提交
168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
- uni-app x 4.0以前,连续触发`click``tap`事件,可能会出现事件丢失的情况。请升级新版

::: info 调整

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

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

      // 变更之后类型为 UniSliderChangeEvent
      sliderChange(e : UniSliderChangeEvent) {
      }
    }
  }
</script>
```
:::
dc_zhanglei's avatar
dc_zhanglei 已提交
200

D
DCloud_LXH 已提交
201 202 203 204
### 参见

- [相关 Bug](https://issues.dcloud.net.cn/?mid=component.global-properties-events.global-events)

D
DCloud_LXH 已提交
205
## UniEvent
D
DCloud_LXH 已提交
206

D
DCloud_LXH 已提交
207
<!-- CUSTOMTYPEJSON.UniEvent.description -->
D
DCloud_LXH 已提交
208

D
DCloud_LXH 已提交
209
<!-- CUSTOMTYPEJSON.UniEvent.extends -->
D
DCloud_LXH 已提交
210

D
DCloud_LXH 已提交
211
<!-- CUSTOMTYPEJSON.UniEvent.param -->
D
DCloud_LXH 已提交
212 213 214



D
DCloud_LXH 已提交
215 216
### UniEvent 方法 @event-methods
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.name -->
D
DCloud_LXH 已提交
217

D
DCloud_LXH 已提交
218
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.description -->
D
DCloud_LXH 已提交
219

D
DCloud_LXH 已提交
220
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.param -->
D
DCloud_LXH 已提交
221

D
DCloud_LXH 已提交
222
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.returnValue -->
D
DCloud_LXH 已提交
223

D
DCloud_LXH 已提交
224
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.compatibility -->
D
DCloud_LXH 已提交
225

D
DCloud_LXH 已提交
226
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.tutorial -->
D
DCloud_LXH 已提交
227

D
DCloud_LXH 已提交
228
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.name -->
D
DCloud_LXH 已提交
229

D
DCloud_LXH 已提交
230
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.description -->
D
DCloud_LXH 已提交
231

D
DCloud_LXH 已提交
232
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.param -->
D
DCloud_LXH 已提交
233

D
DCloud_LXH 已提交
234
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.returnValue -->
D
DCloud_LXH 已提交
235

D
DCloud_LXH 已提交
236
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.compatibility -->
D
DCloud_LXH 已提交
237

D
DCloud_LXH 已提交
238
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.tutorial -->
D
DCloud_LXH 已提交
239

D
DCloud_LXH 已提交
240
## UniCustomEvent\<T> @unicustomevent
D
DCloud_LXH 已提交
241

D
DCloud_LXH 已提交
242
<!-- CUSTOMTYPEJSON.UniCustomEvent.description -->
D
DCloud_LXH 已提交
243

D
DCloud_LXH 已提交
244
<!-- CUSTOMTYPEJSON.UniCustomEvent.extends -->
D
DCloud_LXH 已提交
245

D
DCloud_LXH 已提交
246
<!-- CUSTOMTYPEJSON.UniCustomEvent.param -->
D
DCloud_LXH 已提交
247 248


dc_zhanglei's avatar
dc_zhanglei 已提交
249
## UniPointerEvent
D
DCloud_LXH 已提交
250

dc_zhanglei's avatar
dc_zhanglei 已提交
251
<!-- CUSTOMTYPEJSON.UniPointerEvent.description -->
D
DCloud_LXH 已提交
252

dc_zhanglei's avatar
dc_zhanglei 已提交
253
<!-- CUSTOMTYPEJSON.UniPointerEvent.extends -->
D
DCloud_LXH 已提交
254

dc_zhanglei's avatar
dc_zhanglei 已提交
255
<!-- CUSTOMTYPEJSON.UniPointerEvent.param -->
D
DCloud_LXH 已提交
256

D
DCloud_LXH 已提交
257
<!-- CUSTOMTYPEJSON.UniPointerEvent.example -->
D
DCloud_LXH 已提交
258

D
DCloud_LXH 已提交
259
## UniTouchEvent
D
DCloud_LXH 已提交
260

D
DCloud_LXH 已提交
261
<!-- CUSTOMTYPEJSON.UniTouchEvent.description -->
D
DCloud_LXH 已提交
262

D
DCloud_LXH 已提交
263
<!-- CUSTOMTYPEJSON.UniTouchEvent.extends -->
D
DCloud_LXH 已提交
264

D
DCloud_LXH 已提交
265
<!-- CUSTOMTYPEJSON.UniTouchEvent.param -->
D
DCloud_LXH 已提交
266

D
DCloud_LXH 已提交
267
UniTouchEvent 的 type 类型包括:touchstart、touchmove、touchend、touchcancel、longpress。
dc_zhanglei's avatar
dc_zhanglei 已提交
268

D
DCloud_LXH 已提交
269
## UniTouch
D
DCloud_LXH 已提交
270

D
DCloud_LXH 已提交
271
<!-- CUSTOMTYPEJSON.UniTouch.description -->
D
DCloud_LXH 已提交
272

D
DCloud_LXH 已提交
273
<!-- CUSTOMTYPEJSON.UniTouch.extends -->
D
DCloud_LXH 已提交
274

D
DCloud_LXH 已提交
275
<!-- CUSTOMTYPEJSON.UniTouch.param -->
D
DCloud_LXH 已提交
276

D
DCloud_LXH 已提交
277
<!-- CUSTOMTYPEJSON.Unigeneral-event.example -->
D
DCloud_LXH 已提交
278

279 280 281 282 283 284 285 286 287 288
## UniMouseEvent

<!-- CUSTOMTYPEJSON.UniMouseEvent.description -->

<!-- CUSTOMTYPEJSON.UniMouseEvent.extends -->

<!-- CUSTOMTYPEJSON.UniMouseEvent.param -->

<!-- CUSTOMTYPEJSON.UniMouseEvent.example -->

D
DCloud_LXH 已提交
289
## UniKeyEvent
290

D
DCloud_LXH 已提交
291
<!-- CUSTOMTYPEJSON.UniKeyEvent.description -->
292

D
DCloud_LXH 已提交
293
<!-- CUSTOMTYPEJSON.UniKeyEvent.extends -->
294

D
DCloud_LXH 已提交
295
<!-- CUSTOMTYPEJSON.UniKeyEvent.param -->
296

D
DCloud_LXH 已提交
297
<!-- CUSTOMTYPEJSON.UniKeyEvent.compatibility -->
298

D
DCloud_LXH 已提交
299
<!-- CUSTOMTYPEJSON.UniKeyEvent.example -->
300

D
DCloud_LXH 已提交
301 302 303 304 305 306 307 308 309 310 311 312
## UniNativeViewEvent

<!-- CUSTOMTYPEJSON.UniNativeViewEvent.description -->

<!-- CUSTOMTYPEJSON.UniNativeViewEvent.extends -->

<!-- CUSTOMTYPEJSON.UniNativeViewEvent.param -->

<!-- CUSTOMTYPEJSON.UniNativeViewEvent.compatibility -->

<!-- CUSTOMTYPEJSON.UniNativeViewEvent.example -->

D
DCloud_LXH 已提交
313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350
## UniVideoEvent

<!-- CUSTOMTYPEJSON.UniVideoEvent.description -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.extends -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.param -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.compatibility -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.example -->

### UniVideoEvent 的方法 @univideoevent-methods
<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.stopPropagation.name -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.stopPropagation.description -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.stopPropagation.compatibility -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.stopPropagation.param -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.stopPropagation.returnValue -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.stopPropagation.tutorial -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.preventDefault.name -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.preventDefault.description -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.preventDefault.compatibility -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.preventDefault.param -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.preventDefault.returnValue -->

<!-- CUSTOMTYPEJSON.UniVideoEvent.methods.preventDefault.tutorial -->


D
DCloud_LXH 已提交
351 352
## 参见

D
DCloud_LXH 已提交
353
- [相关 Bug](https://issues.dcloud.net.cn/?mid=component.global-properties-events)