common.md 11.3 KB
Newer Older
D
DCloud_LXH 已提交
1 2 3 4 5 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 35 36

## 组件公共事件

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

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

D
DCloud_LXH 已提交
41 42
<!-- CUSTOMTYPEJSON.general-event.example -->

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

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

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

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

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

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

D
DCloud_LXH 已提交
58 59 60 61 62 63

### transition 事件

- @transitionend

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

D
DCloud_LXH 已提交
65
	#### 兼容性
D
DCloud_LXH 已提交
66

D
DCloud_LXH 已提交
67
	安卓 3.93+ 版本开始支持
D
DCloud_LXH 已提交
68

D
DCloud_LXH 已提交
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
  ```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 已提交
86 87
      }
    }
D
DCloud_LXH 已提交
88
  </script>
D
DCloud_LXH 已提交
89

D
DCloud_LXH 已提交
90 91 92 93 94 95 96 97
  <style>
    .transition-transform {
      transition-duration: 2000;
      transition-property: transform;
      transform: rotate(0deg);
    }
  </style>
  ```
D
DCloud_LXH 已提交
98 99 100

### 冒泡事件系统

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

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

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

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

#### 阻止冒泡

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

```ts
DCloud-yyl's avatar
DCloud-yyl 已提交
121
handleClick (event : UniPointerEvent) {
D
DCloud_LXH 已提交
122 123 124 125 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
    // 阻止继续冒泡.
    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 已提交
162 163
### Bug & Tips

DCloud_Heavensoft's avatar
DCloud_Heavensoft 已提交
164 165 166 167 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
- 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 已提交
196

D
DCloud_LXH 已提交
197
## UniEvent
D
DCloud_LXH 已提交
198

D
DCloud_LXH 已提交
199
<!-- CUSTOMTYPEJSON.UniEvent.description -->
D
DCloud_LXH 已提交
200

D
DCloud_LXH 已提交
201
<!-- CUSTOMTYPEJSON.UniEvent.extends -->
D
DCloud_LXH 已提交
202

D
DCloud_LXH 已提交
203
<!-- CUSTOMTYPEJSON.UniEvent.param -->
D
DCloud_LXH 已提交
204 205 206



D
DCloud_LXH 已提交
207 208
### UniEvent 方法 @event-methods
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.name -->
D
DCloud_LXH 已提交
209

D
DCloud_LXH 已提交
210
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.description -->
D
DCloud_LXH 已提交
211

D
DCloud_LXH 已提交
212
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.param -->
D
DCloud_LXH 已提交
213

D
DCloud_LXH 已提交
214
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.returnValue -->
D
DCloud_LXH 已提交
215

D
DCloud_LXH 已提交
216
<!-- CUSTOMTYPEJSON.UniEvent.methods.stopPropagation.compatibility -->
D
DCloud_LXH 已提交
217

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

D
DCloud_LXH 已提交
220
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.name -->
D
DCloud_LXH 已提交
221

D
DCloud_LXH 已提交
222
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.description -->
D
DCloud_LXH 已提交
223

D
DCloud_LXH 已提交
224
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.param -->
D
DCloud_LXH 已提交
225

D
DCloud_LXH 已提交
226
<!-- CUSTOMTYPEJSON.UniEvent.methods.preventDefault.returnValue -->
D
DCloud_LXH 已提交
227

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

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

D
DCloud_LXH 已提交
232
## UniCustomEvent
D
DCloud_LXH 已提交
233

D
DCloud_LXH 已提交
234
<!-- CUSTOMTYPEJSON.UniCustomEvent.description -->
D
DCloud_LXH 已提交
235

D
DCloud_LXH 已提交
236
<!-- CUSTOMTYPEJSON.UniCustomEvent.extends -->
D
DCloud_LXH 已提交
237

D
DCloud_LXH 已提交
238
<!-- CUSTOMTYPEJSON.UniCustomEvent.param -->
D
DCloud_LXH 已提交
239 240 241



D
DCloud_LXH 已提交
242 243
### UniCustomEvent 方法 @customevent-methods
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.stopPropagation.name -->
D
DCloud_LXH 已提交
244

D
DCloud_LXH 已提交
245
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.stopPropagation.description -->
D
DCloud_LXH 已提交
246

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

D
DCloud_LXH 已提交
249
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.stopPropagation.returnValue -->
D
DCloud_LXH 已提交
250

D
DCloud_LXH 已提交
251
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.stopPropagation.compatibility -->
D
DCloud_LXH 已提交
252

D
DCloud_LXH 已提交
253
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.stopPropagation.tutorial -->
D
DCloud_LXH 已提交
254

D
DCloud_LXH 已提交
255
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.preventDefault.name -->
D
DCloud_LXH 已提交
256

D
DCloud_LXH 已提交
257
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.preventDefault.description -->
D
DCloud_LXH 已提交
258

D
DCloud_LXH 已提交
259
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.preventDefault.param -->
D
DCloud_LXH 已提交
260

D
DCloud_LXH 已提交
261
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.preventDefault.returnValue -->
D
DCloud_LXH 已提交
262

D
DCloud_LXH 已提交
263
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.preventDefault.compatibility -->
D
DCloud_LXH 已提交
264

D
DCloud_LXH 已提交
265
<!-- CUSTOMTYPEJSON.UniCustomEvent.methods.preventDefault.tutorial -->
D
DCloud_LXH 已提交
266

dc_zhanglei's avatar
dc_zhanglei 已提交
267
## UniPointerEvent
D
DCloud_LXH 已提交
268

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

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

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

D
DCloud_LXH 已提交
275
<!-- CUSTOMTYPEJSON.UniPointerEvent.example -->
D
DCloud_LXH 已提交
276

D
DCloud_LXH 已提交
277
### UniPointerEvent 的方法 @unipointerevent-methods
dc_zhanglei's avatar
dc_zhanglei 已提交
278
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.stopPropagation.name -->
D
DCloud_LXH 已提交
279

dc_zhanglei's avatar
dc_zhanglei 已提交
280
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.stopPropagation.description -->
D
DCloud_LXH 已提交
281

dc_zhanglei's avatar
dc_zhanglei 已提交
282
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.stopPropagation.param -->
D
DCloud_LXH 已提交
283

dc_zhanglei's avatar
dc_zhanglei 已提交
284
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.stopPropagation.returnValue -->
D
DCloud_LXH 已提交
285

dc_zhanglei's avatar
dc_zhanglei 已提交
286
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.stopPropagation.compatibility -->
D
DCloud_LXH 已提交
287

dc_zhanglei's avatar
dc_zhanglei 已提交
288
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.stopPropagation.tutorial -->
D
DCloud_LXH 已提交
289

dc_zhanglei's avatar
dc_zhanglei 已提交
290
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.preventDefault.name -->
D
DCloud_LXH 已提交
291

dc_zhanglei's avatar
dc_zhanglei 已提交
292
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.preventDefault.description -->
D
DCloud_LXH 已提交
293

dc_zhanglei's avatar
dc_zhanglei 已提交
294
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.preventDefault.param -->
D
DCloud_LXH 已提交
295

dc_zhanglei's avatar
dc_zhanglei 已提交
296
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.preventDefault.returnValue -->
D
DCloud_LXH 已提交
297

dc_zhanglei's avatar
dc_zhanglei 已提交
298
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.preventDefault.compatibility -->
D
DCloud_LXH 已提交
299

dc_zhanglei's avatar
dc_zhanglei 已提交
300
<!-- CUSTOMTYPEJSON.UniPointerEvent.methods.preventDefault.tutorial -->
D
DCloud_LXH 已提交
301

D
DCloud_LXH 已提交
302
## UniTouchEvent
D
DCloud_LXH 已提交
303

D
DCloud_LXH 已提交
304
<!-- CUSTOMTYPEJSON.UniTouchEvent.description -->
D
DCloud_LXH 已提交
305

D
DCloud_LXH 已提交
306
<!-- CUSTOMTYPEJSON.UniTouchEvent.extends -->
D
DCloud_LXH 已提交
307

D
DCloud_LXH 已提交
308
<!-- CUSTOMTYPEJSON.UniTouchEvent.param -->
D
DCloud_LXH 已提交
309

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

D
DCloud_LXH 已提交
312 313
### UniTouchEvent 方法 @touchevent-methods
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.stopPropagation.name -->
D
DCloud_LXH 已提交
314

D
DCloud_LXH 已提交
315
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.stopPropagation.description -->
D
DCloud_LXH 已提交
316

D
DCloud_LXH 已提交
317
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.stopPropagation.param -->
D
DCloud_LXH 已提交
318

D
DCloud_LXH 已提交
319
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.stopPropagation.returnValue -->
D
DCloud_LXH 已提交
320

D
DCloud_LXH 已提交
321
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.stopPropagation.compatibility -->
D
DCloud_LXH 已提交
322

D
DCloud_LXH 已提交
323
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.stopPropagation.tutorial -->
D
DCloud_LXH 已提交
324

D
DCloud_LXH 已提交
325
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.preventDefault.name -->
D
DCloud_LXH 已提交
326

D
DCloud_LXH 已提交
327
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.preventDefault.description -->
D
DCloud_LXH 已提交
328

D
DCloud_LXH 已提交
329
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.preventDefault.param -->
D
DCloud_LXH 已提交
330

D
DCloud_LXH 已提交
331
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.preventDefault.returnValue -->
D
DCloud_LXH 已提交
332

D
DCloud_LXH 已提交
333
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.preventDefault.compatibility -->
D
DCloud_LXH 已提交
334

D
DCloud_LXH 已提交
335
<!-- CUSTOMTYPEJSON.UniTouchEvent.methods.preventDefault.tutorial -->
D
DCloud_LXH 已提交
336

D
DCloud_LXH 已提交
337
## UniTouch
D
DCloud_LXH 已提交
338

D
DCloud_LXH 已提交
339
<!-- CUSTOMTYPEJSON.UniTouch.description -->
D
DCloud_LXH 已提交
340

D
DCloud_LXH 已提交
341
<!-- CUSTOMTYPEJSON.UniTouch.extends -->
D
DCloud_LXH 已提交
342

D
DCloud_LXH 已提交
343
<!-- CUSTOMTYPEJSON.UniTouch.param -->
D
DCloud_LXH 已提交
344

D
DCloud_LXH 已提交
345
<!-- CUSTOMTYPEJSON.Unigeneral-event.example -->
D
DCloud_LXH 已提交
346

347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382
## UniMouseEvent

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

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

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

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

### UniMouseEvent 的方法 @unimouseevent-methods
<!-- CUSTOMTYPEJSON.UniMouseEvent.methods.stopPropagation.name -->

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

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

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

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

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

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

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

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

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

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

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


D
DCloud_LXH 已提交
383 384 385 386
## 参见

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