1# PanGesture 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9滑动手势事件，当滑动的最小距离达到设定的最小值时触发滑动手势事件。 10 11以下场景可以触发滑动手势： 12 13| 触发方式 | 输入源类型 | 输入设备类型 | 备注 | 14|----------------------|---------------------|------------------------|-----------------------------------| 15| 手指按下滑动。 | [SourceTool](ts-gesture-settings.md#sourcetool枚举说明9).Finger | [SourceType](ts-gesture-settings.md#sourcetype枚举说明8).TouchScreen | axisVertical和axisHorizontal均为0。 | 16| 鼠标左键按下滑动。 | [SourceTool](ts-gesture-settings.md#sourcetool枚举说明9).MOUSE | [SourceType](ts-gesture-settings.md#sourcetype枚举说明8).Mouse | axisVertical和axisHorizontal均为0。 | 17| 鼠标滚轮滚动。 | [SourceTool](ts-gesture-settings.md#sourcetool枚举说明9).MOUSE | [SourceType](ts-gesture-settings.md#sourcetype枚举说明8).Mouse | axisVertical或axisHorizontal不为0。 | 18| 触摸板按下左键后滑动。 | [SourceTool](ts-gesture-settings.md#sourcetool枚举说明9).MOUSE | [SourceType](ts-gesture-settings.md#sourcetype枚举说明8).Mouse | axisVertical和axisHorizontal均为0。 | 19| 触摸板双指滑动。 | [SourceTool](ts-gesture-settings.md#sourcetool枚举说明9).TOUCHPAD | [SourceType](ts-gesture-settings.md#sourcetype枚举说明8).Mouse | axisVertical或axisHorizontal不为0。 | 20| 手写笔滑动。 | [SourceTool](ts-gesture-settings.md#sourcetool枚举说明9).Pen | [SourceType](ts-gesture-settings.md#sourcetype枚举说明8).TouchScreen | axisVertical和axisHorizontal均为0。 | 21 22> **说明：** 23> 24> 从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 25 26 27## 接口 28 29### PanGesture 30 31PanGesture(value?: { fingers?: number; direction?: PanDirection; distance?: number } | PanGestureOptions) 32 33创建滑动手势对象。继承自[GestureInterface\<T>](ts-gesture-common.md#gestureinterfacet11) 34 35**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39**参数：** 40 41| 参数名 | 类型 | 必填 | 说明 | 42| -------- | -------- | -------- | -------- | 43| value | { fingers?: number; direction?: PanDirection; distance?: number } \| [PanGestureOptions](#pangestureoptions) | 否 | 滑动手势参数。<br> - fingers：用于指定触发滑动的最少手指数，最小为1指，最大取值为10指。<br/>默认值：1<br/>取值范围：[1, 10]<br/>**说明：** <br/>当设置的值小于1或不设置时，会被转化为默认值。<br> - direction：用于指定触发滑动的手势方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。<br/>默认值：PanDirection.All<br> - distance：用于指定触发滑动手势事件的最小滑动距离，单位为vp。<br/>取值范围：[0, +∞)<br/>手写笔默认值：8，其余输入源默认值：5<br/>**说明：**<br/>[Tabs组件](ts-container-tabs.md)滑动与该滑动手势事件同时存在时，可将distance值设为1，使滑动更灵敏，避免造成事件错乱。<br/>当设定的值小于0时，按默认值处理。 | 44 45### PanGesture<sup>15+</sup> 46 47PanGesture(options?: PanGestureHandlerOptions) 48 49创建滑动手势对象。与[PanGesture](#pangesture-1)相比，options参数新增了对isFingerCountLimited和distanceMap参数，分别表示是否检查触摸屏幕的手指数量以及指定不同输入源触发滑动手势事件的最小滑动距离。 50 51**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 52 53**系统能力：** SystemCapability.ArkUI.ArkUI.Full 54 55**参数：** 56 57| 参数名 | 类型 | 必填 | 说明 | 58| -------- | -------- | -------- | -------- | 59| options | [PanGestureHandlerOptions](./ts-gesturehandler.md#pangesturehandleroptions) | 否 | 滑动手势处理器配置参数。 | 60 61## PanDirection枚举说明 62 63与SwipeDirection不同，PanDirection没有角度限制。 64 65**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 66 67**系统能力：** SystemCapability.ArkUI.ArkUI.Full 68 69| 名称 | 值 | 说明 | 70| ---- | -- | ----- | 71| All | - | 所有方向。 | 72| Horizontal | - | 水平方向。 | 73| Vertical | - | 竖直方向。 | 74| Left | - | 向左滑动。 | 75| Right | - | 向右滑动。 | 76| Up | - | 向上滑动。 | 77| Down | - | 向下滑动。 | 78| None | - | 任何方向都不可触发滑动手势事件。 | 79 80 81## PanGestureOptions 82 83### constructor 84 85constructor(value?: { fingers?: number; direction?: PanDirection; distance?: number }) 86 87创建滑动手势配置参数对象。通过PanGestureOptions对象接口可以动态修改滑动手势的属性，从而避免通过状态变量修改属性（状态变量修改会导致UI刷新）。 88 89**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 90 91**系统能力：** SystemCapability.ArkUI.ArkUI.Full 92 93**参数：** 94 95| 参数名 | 类型 | 必填 | 说明 | 96| --------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 97| value | { fingers?: number; direction?: [PanDirection](#pandirection枚举说明); distance?: number } | 否 | 滑动手势配置参数对象。<br/>fingers用于指定触发滑动的最少手指数，最小为1指， 最大取值为10指。<br/>默认值：1 <br/>direction用于指定触发滑动的手势方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。<br/>默认值：PanDirection.All<br/>distance用于指定触发滑动手势事件的最小滑动距离，单位为vp。<br/>手写笔默认值：8，其余输入源默认值：5<br/>**说明：**<br/>[Tabs](ts-container-tabs.md)组件滑动与该滑动手势事件同时存在时，可将distance值设为1，使滑动更灵敏，避免造成事件错乱。<br/>当设定的值小于0时，按默认值处理。<br/>建议设置合理的滑动距离，滑动距离设置过大时会导致滑动不跟手（响应时延慢）的问题。| 98 99### constructor<sup>20+</sup> 100 101constructor(value?: PanGestureHandlerOptions) 102 103创建滑动手势配置参数对象。通过PanGestureOptions对象接口可以动态修改滑动手势识别器的属性，从而避免通过状态变量修改属性（状态变量修改会导致UI刷新）。 104 105**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 106 107**系统能力：** SystemCapability.ArkUI.ArkUI.Full 108 109**参数：** 110 111| 参数名 | 类型 | 必填 | 说明 | 112| --------- | ---------------------- | ---- | -------------------------------- | 113| value | [PanGestureHandlerOptions](./ts-gesturehandler.md#pangesturehandleroptions) | 否 | 滑动手势处理器配置参数。 | 114 115### setDirection 116 117setDirection(value: PanDirection) 118 119设置滑动方向。 120 121**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 122 123**系统能力：** SystemCapability.ArkUI.ArkUI.Full 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| ------ | ------------------------------------------ | ---- | ---------------------------- | 129| value | [PanDirection](#pandirection枚举说明) | 是 | 用于指定触发滑动的手势方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。<br/>默认值：PanDirection.All | 130 131### setDirection<sup>20+</sup> 132 133setDirection(value: PanDirection): void 134 135设置滑动方向。 136 137**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 138 139**系统能力：** SystemCapability.ArkUI.ArkUI.Full 140 141**参数：** 142 143| 参数名 | 类型 | 必填 | 说明 | 144| ------ | ------------------------------------------ | ---- | ---------------------------- | 145| value | [PanDirection](#pandirection枚举说明) | 是 | 用于指定触发滑动的手势方向，此枚举值支持逻辑与(&)和逻辑或（\|）运算。<br/>默认值：PanDirection.All | 146 147### setDistance 148 149setDistance(value: number) 150 151设置触发滑动手势事件的最小滑动距离，单位为vp。距离值不宜设置过大，避免因滑动脱手，响应时延过大等问题导致性能劣化，最佳实践请参考：[减小拖动识别距离](https://developer.huawei.com/consumer/cn/doc/best-practices-V5/bpta-application-latency-optimization-cases-V5#section1116134115286)。 152 153**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 154 155**系统能力：** SystemCapability.ArkUI.ArkUI.Full 156 157**参数：** 158 159| 参数名 | 类型 | 必填 | 说明 | 160| ------ | ------------------------------------------ | ---- | ---------------------------- | 161| value | number | 是 | 触发滑动手势事件的最小滑动距离，单位为vp。<br/>手写笔默认值：8，其余输入源默认值：5<br/>**说明：**<br/>[Tabs组件](ts-container-tabs.md)滑动与该滑动手势事件同时存在时，可将distance值设为1，使滑动更灵敏，避免造成事件错乱。<br/>当设定的值小于0时，按默认值处理。<br/>建议设置合理的滑动距离，滑动距离设置过大时会导致滑动不跟手（响应时延慢）的问题。 | 162 163### setDistance<sup>20+</sup> 164 165setDistance(value: number): void 166 167设置触发滑动手势事件的最小滑动距离，单位为vp。距离值不宜设置过大，避免因滑动脱手，响应时延过大等问题导致性能劣化，最佳实践请参考：[减小拖动识别距离](https://developer.huawei.com/consumer/cn/doc/best-practices-V5/bpta-application-latency-optimization-cases-V5#section1116134115286)。 168 169**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 170 171**系统能力：** SystemCapability.ArkUI.ArkUI.Full 172 173**参数：** 174 175| 参数名 | 类型 | 必填 | 说明 | 176| ------ | ------------------------------------------ | ---- | ---------------------------- | 177| value | number | 是 | 触发滑动手势事件的最小滑动距离，单位为vp。<br/>手写笔默认值：8，其余输入源默认值：5<br/>**说明：**<br/>[Tabs组件](ts-container-tabs.md)滑动与该滑动手势事件同时存在时，可将distance值设为1，使滑动更灵敏，避免造成事件错乱。<br/>当设定的值小于0时，按默认值处理。<br/>建议设置合理的滑动距离，滑动距离设置过大时会导致滑动不跟手（响应时延慢）的问题。 | 178 179### setFingers 180 181setFingers(value: number) 182 183设置触发滑动的最少手指数。 184 185**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 186 187**系统能力：** SystemCapability.ArkUI.ArkUI.Full 188 189**参数：** 190 191| 参数名 | 类型 | 必填 | 说明 | 192| ------ | ------------------------------------------ | ---- | ---------------------------- | 193| value | number | 是 | 触发滑动的最少手指数，最小为1指， 最大取值为10指。<br/>默认值：1 | 194 195### setFingers<sup>20+</sup> 196 197setFingers(value: number): void 198 199设置触发滑动的最少手指数。 200 201**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 202 203**系统能力：** SystemCapability.ArkUI.ArkUI.Full 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| ------ | ------------------------------------------ | ---- | ---------------------------- | 209| value | number | 是 | 触发滑动的最少手指数，最小为1指， 最大取值为10指。<br/>默认值：1 | 210 211 212### getDirection<sup>12+</sup> 213 214getDirection(): PanDirection 215 216获取滑动方向。 217 218**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 219 220**系统能力：** SystemCapability.ArkUI.ArkUI.Full 221 222**返回值：** 223 224| 类型 | 说明 | 225| ------ | --------- | 226| [PanDirection](#pandirection枚举说明) | 滑动方向。 | 227 228### getDistance<sup>18+</sup> 229 230getDistance(): number 231 232获取触发滑动手势事件的最小滑动距离。 233 234**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 235 236**系统能力：** SystemCapability.ArkUI.ArkUI.Full 237 238**返回值：** 239 240| 类型 | 说明 | 241| ------ | --------- | 242| number | 滑动手势事件的最小滑动距离。 | 243 244 245## 事件 246 247**系统能力：** SystemCapability.ArkUI.ArkUI.Full 248 249> **说明：** 250> 251> 在[GestureEvent](ts-gesture-common.md#gestureevent对象说明)的fingerList元素中，手指索引编号与位置相对应，即fingerList[index]的id为index。对于先按下但未参与当前手势触发的手指，fingerList中对应的位置为空。建议优先使用fingerInfos。 252 253### onActionStart 254 255onActionStart(event: (event: GestureEvent) => void) 256 257设置滑动手势识别成功回调。 258 259**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 260 261**系统能力：** SystemCapability.ArkUI.ArkUI.Full 262 263**参数：** 264 265| 参数名 | 类型 | 必填 | 说明 | 266| ------ | ------------------------------------------ | ---- | ---------------------------- | 267| event | (event: [GestureEvent](ts-gesture-common.md#gestureevent对象说明)) => void | 是 | 滑动手势识别成功回调。 | 268 269### onActionUpdate 270 271onActionUpdate(event: (event: GestureEvent) => void) 272 273设置滑动手势更新回调。fingerList为多根手指时，该回调监听每次只会更新一根手指的位置信息。 274 275**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 276 277**系统能力：** SystemCapability.ArkUI.ArkUI.Full 278 279**参数：** 280 281| 参数名 | 类型 | 必填 | 说明 | 282| ------ | ------------------------------------------ | ---- | ---------------------------- | 283| event | (event: [GestureEvent](ts-gesture-common.md#gestureevent对象说明)) => void | 是 | 滑动手势更新回调。 | 284 285### onActionEnd 286 287onActionEnd(event: (event: GestureEvent) => void) 288 289设置滑动手势结束回调。滑动手势识别成功后，手指抬起时触发回调。 290 291**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 292 293**系统能力：** SystemCapability.ArkUI.ArkUI.Full 294 295**参数：** 296 297| 参数名 | 类型 | 必填 | 说明 | 298| ------ | ------------------------------------------ | ---- | ---------------------------- | 299| event | (event: [GestureEvent](ts-gesture-common.md#gestureevent对象说明)) => void | 是 | 滑动手势结束回调。 | 300 301### onActionCancel 302 303onActionCancel(event: () => void) 304 305设置滑动手势取消回调。滑动手势识别成功后，接收到触摸取消事件时触发回调。不返回手势事件信息。 306 307**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 308 309**系统能力：** SystemCapability.ArkUI.ArkUI.Full 310 311**参数：** 312 313| 参数名 | 类型 | 必填 | 说明 | 314| ------ | ------------------------------------------ | ---- | ---------------------------- | 315| event | () => void | 是 | 滑动手势取消回调。 | 316 317### onActionCancel<sup>18+</sup> 318 319onActionCancel(event: Callback\<GestureEvent\>) 320 321设置滑动手势取消回调。滑动手势识别成功后，接收到触摸取消事件时触发回调。返回手势事件信息。 322 323**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 324 325**系统能力：** SystemCapability.ArkUI.ArkUI.Full 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| ------ | ------------------------------------------ | ---- | ---------------------------- | 331| event | Callback\<[GestureEvent](ts-gesture-common.md#gestureevent对象说明)> | 是 | 滑动手势取消回调。 | 332 333## 示例 334 335该示例通过PanGesture实现了单指/双指滑动手势的识别。 336 337```ts 338// xxx.ets 339@Entry 340@Component 341struct PanGestureExample { 342 @State offsetX: number = 0; 343 @State offsetY: number = 0; 344 @State positionX: number = 0; 345 @State positionY: number = 0; 346 private panOption: PanGestureOptions = new PanGestureOptions({ direction: PanDirection.Left | PanDirection.Right }); 347 348 build() { 349 Column() { 350 Column() { 351 Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) 352 } 353 .height(200) 354 .width(300) 355 .padding(20) 356 .border({ width: 3 }) 357 .margin(50) 358 .translate({ x: this.offsetX, y: this.offsetY, z: 0 }) // 以组件左上角为坐标原点进行移动 359 // 左右滑动触发该手势事件 360 .gesture( 361 PanGesture(this.panOption) 362 .onActionStart((event: GestureEvent) => { 363 console.info('Pan start'); 364 console.info('Pan start timeStamp is: ' + event.timestamp); 365 }) 366 .onActionUpdate((event: GestureEvent) => { 367 if (event) { 368 this.offsetX = this.positionX + event.offsetX; 369 this.offsetY = this.positionY + event.offsetY; 370 } 371 }) 372 .onActionEnd((event: GestureEvent) => { 373 this.positionX = this.offsetX; 374 this.positionY = this.offsetY; 375 console.info('Pan end'); 376 console.info('Pan end timeStamp is: ' + event.timestamp); 377 }) 378 ) 379 380 Button('修改PanGesture触发条件') 381 .onClick(() => { 382 // 将PanGesture手势事件触发条件改为双指以任意方向滑动 383 this.panOption.setDirection(PanDirection.All); 384 this.panOption.setFingers(2); 385 }) 386 } 387 } 388} 389``` 390 391示意图： 392 393向左滑动： 394 395 396 397点击按钮时，修改PanGesture触发条件为双指向左下方滑动： 398 399 
