cherryPick 3.1release

Signed-off-by: Ntianyu <tianyu55@h-partners.com>

zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-longpressgesture.md

@@ -32,24 +32,31 @@ LongPressGesture(value?: { fingers?: number, repeat?: boolean, duration?: number
 @Entry
 @Component
 struct LongPressGestureExample {
-  @State count: number = 0
+  @State count: number = 0;
 
   build() {
-    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
-      Text('LongPress onAction:' + this.count)
+    Column() {
+      Text('LongPress onAction:' + this.count).fontSize(28)
+        // 单指长按文本触发该手势事件
+        .gesture(
+        LongPressGesture({ repeat: true })
+          // 由于repeat设置为true，长按动作存在时会连续触发，触发间隔为duration（默认值500ms）
+          .onAction((event: GestureEvent) => {
+            if (event.repeat) {
+              this.count++;
+            }
+          })
+            // 长按动作一结束触发
+          .onActionEnd(() => {
+            this.count = 0;
+          })
+        )
     }
-    .height(200).width(300).padding(60).border({ width:1 }).margin(30)
-    .gesture(
-      LongPressGesture({ repeat: true })
-        //长按动作存在会连续触发
-        .onAction((event: GestureEvent) => {
-          if (event.repeat) { this.count++ }
-        })
-        //长按动作一结束触发
-        .onActionEnd(() => {
-          this.count = 0
-        })
-    )
+    .height(200)
+    .width(300)
+    .padding(20)
+    .border({ width: 3 })
+    .margin(30)
   }
 }
 ```

zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pangesture.md

@@ -20,16 +20,16 @@ PanGesture(value?: { fingers?: number, direction?: PanDirection, distance?: numb
 
 ## PanDirection枚举说明
 
-  | 名称 | 描述 |
-  | -------- | -------- |
-  | All | 所有方向。 |
-  | Horizontal | 水平方向。 |
-  | Vertical | 竖直方向。 |
-  | Left | 向左拖动。 |
-  | Right | 向右拖动。 |
-  | Up | 向上拖动。 |
-  | Down | 向下拖动。 |
-  | None | 任何方向都不可触发拖动手势事件。 |
+| 名称 | 描述 |
+| -------- | -------- |
+| All | 所有方向。 |
+| Horizontal | 水平方向。 |
+| Vertical | 竖直方向。 |
+| Left | 向左拖动。 |
+| Right | 向右拖动。 |
+| Up | 向上拖动。 |
+| Down | 向下拖动。 |
+| None | 任何方向都不可触发拖动手势事件。 |
 
 
 ## PanGestureOptions
@@ -44,11 +44,11 @@ PanGestureOptions(options?: { fingers?: number, direction?: PanDirection, distan
 
 **接口：**
 
-  | 名称 | 功能描述 |
-  | -------- | -------- |
-  | setDirection(value: PanDirection) | 设置direction属性。 |
-  | setDistance(value: number) | 设置distance属性。 |
-  | setFingers(value: number) | 设置fingers属性。 |
+| 名称 | 功能描述 |
+| -------- | -------- |
+| setDirection(value: PanDirection) | 设置direction属性。 |
+| setDistance(value: number) | 设置distance属性。 |
+| setFingers(value: number) | 设置fingers属性。 |
 
 
 ## 事件
@@ -68,30 +68,57 @@ PanGestureOptions(options?: { fingers?: number, direction?: PanDirection, distan
 @Entry
 @Component
 struct PanGestureExample {
-  @State offsetX: number = 0
-  @State offsetY: number = 0
+  @State offsetX: number = 0;
+  @State offsetY: number = 0;
+  @State positionX: number = 0;
+  @State positionY: number = 0;
+  private panOption: PanGestureOptions = new PanGestureOptions({ direction: PanDirection.Left | PanDirection.Right });
 
   build() {
-    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
-      Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY)
-    }
-    .height(100).width(200).padding(20).border({ width: 1 }).margin(80)
-    .translate({ x: this.offsetX, y: this.offsetY, z: 5 })
-    .gesture(
-      PanGesture({})
+    Column() {
+      Column() {
+        Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY)
+      }
+      .height(200)
+      .width(300)
+      .padding(20)
+      .border({ width: 3 })
+      .margin(50)
+      .translate({ x: this.offsetX, y: this.offsetY, z: 0 })
+      // 左右拖动触发该手势事件
+      .gesture(
+      PanGesture(this.panOption)
         .onActionStart((event: GestureEvent) => {
-          console.info('Pan start')
+          console.info('Pan start');
         })
         .onActionUpdate((event: GestureEvent) => {
-          this.offsetX = event.offsetX
-          this.offsetY = event.offsetY
+          this.offsetX = this.positionX + event.offsetX;
+          this.offsetY = this.positionY + event.offsetY;
         })
         .onActionEnd(() => {
-          console.info('Pan end')
+          this.positionX = this.offsetX;
+          this.positionY = this.offsetY;
+          console.info('Pan end');
+        })
+      )
+
+      Button('修改PanGesture触发条件')
+        .onClick(() => {
+          // 将PanGesture手势事件触发条件改为双指以任意方向拖动
+          this.panOption.setDirection(PanDirection.All);
+          this.panOption.setFingers(2);
         })
-    )
+    }
   }
 }
 ```
 
-![zh-cn_image_0000001174264374](figures/zh-cn_image_0000001174264374.gif)
+示意图：
+
+向左拖动：
+
+![zh-cn_image_0000001174264374](figures/zh-cn_image_0000001174264374.png) 
+
+点击按钮修改PanGesture触发条件，双指向左下方拖动：
+
+ ![zh-cn_image1_0000001174264374](figures/zh-cn_image1_0000001174264374.png) 
\ No newline at end of file

zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-pinchgesture.md

@@ -32,28 +32,42 @@ PinchGesture(value?: { fingers?: number, distance?: number })
 @Entry
 @Component
 struct PinchGestureExample {
-  @State scaleValue: number = 1
+  @State scaleValue: number = 1;
+  @State pinchValue: number = 1;
+  @State pinchX: number = 0;
+  @State pinchY: number = 0;
 
   build() {
-    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
-      Text('PinchGesture scale:' + this.scale)
-    }
-    .height(100).width(200).padding(20).border({ width: 1 }).margin(80)
-    .scale({ x: this.scaleValue, y: this.scaleValue, z: this.scaleValue })
-    .gesture(
-      PinchGesture()
+    Column() {
+      Column() {
+        Text('PinchGesture scale:\n' + this.scaleValue)
+        Text('PinchGesture center:\n(' + this.pinchX + ',' + this.pinchY + ')')
+      }
+      .height(200)
+      .width(300)
+      .padding(20)
+      .border({ width: 3 })
+      .margin({ top: 100 })
+      .scale({ x: this.scaleValue, y: this.scaleValue, z: 1 })
+      // 三指捏合触发该手势事件
+      .gesture(
+      PinchGesture({ fingers: 3 })
         .onActionStart((event: GestureEvent) => {
-          console.info('Pinch start')
+          console.info('Pinch start');
         })
         .onActionUpdate((event: GestureEvent) => {
-          this.scaleValue = event.scale
+          this.scaleValue = this.pinchValue * event.scale;
+          this.pinchX = event.pinchCenterX;
+          this.pinchY = event.pinchCenterY;
         })
         .onActionEnd(() => {
-          console.info('Pinch end')
+          this.pinchValue = this.scaleValue;
+          console.info('Pinch end');
         })
-    )
+      )
+    }.width('100%')
   }
 }
 ```
 
-![zh-cn_image_0000001174582848](figures/zh-cn_image_0000001174582848.gif)
+![zh-cn_image_0000001174582848](figures/zh-cn_image_0000001174582848.png)

zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-rotationgesture.md

@@ -32,28 +32,37 @@ RotationGesture(value?: { fingers?: number, angle?: number })
 @Entry
 @Component
 struct RotationGestureExample {
-  @State angle: number = 0
+  @State angle: number = 0;
+  @State rotateValue: number = 0;
 
   build() {
-    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
-      Text('RotationGesture angle:' + this.angle)
-    }
-    .height(100).width(200).padding(20).border({ width:1 })
-    .margin(80).rotate({ x:1, y:2, z:3, angle: this.angle })
-    .gesture(
+    Column() {
+      Column() {
+        Text('RotationGesture angle:' + this.angle)
+      }
+      .height(200)
+      .width(300)
+      .padding(20)
+      .border({ width: 3 })
+      .margin(80)
+      .rotate({ angle: this.angle })
+      // 双指旋转触发该手势事件
+      .gesture(
       RotationGesture()
         .onActionStart((event: GestureEvent) => {
-          console.log('Rotation start')
+          console.info('Rotation start');
         })
         .onActionUpdate((event: GestureEvent) => {
-          this.angle = event.angle
+          this.angle = this.rotateValue + event.angle;
         })
         .onActionEnd(() => {
-          console.log('Rotation end')
+          this.rotateValue = this.angle;
+          console.info('Rotation end');
         })
-    )
+      )
+    }.width('100%')
   }
 }
 ```
 
-![zh-cn_image_0000001174264372](figures/zh-cn_image_0000001174264372.gif)
+![zh-cn_image_0000001174264372](figures/zh-cn_image_0000001174264372.png)

zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-swipegesture.md

@@ -10,20 +10,20 @@ SwipeGesture(value?: { fingers?: number; direction?: SwipeDirection; speed?: num
 
 **参数：**
 
-  | 参数名称 | 参数类型 | 必填 | 默认值 | 参数描述 |
-  | -------- | -------- | -------- | -------- | -------- |
-  | fingers | number | 否 | 1 | 触发滑动的最少手指数，默认为1，最小为1指，最大为10指。 |
-  | direction | SwipeDirection | 否 | SwipeDirection.All | 触发滑动手势的滑动方向。 |
-  | speed | number | 否 | 100 | 识别滑动的最小速度（默认为100vp/秒）。 |
+| 参数名称 | 参数类型 | 必填 | 默认值 | 参数描述 |
+| -------- | -------- | -------- | -------- | -------- |
+| fingers | number | 否 | 1 | 触发滑动的最少手指数，默认为1，最小为1指，最大为10指。 |
+| direction | SwipeDirection | 否 | SwipeDirection.All | 触发滑动手势的滑动方向。 |
+| speed | number | 否 | 100 | 识别滑动的最小速度（默认为100vp/秒）。 |
 
 ## SwipeDirection枚举说明
 
-  | 名称 | 描述 |
-  | -------- | -------- |
-  | All | 所有方向。 |
-  | Horizontal | 水平方向。 |
-  | Vertical | 竖直方向。 |
-  | None | 任何方向均不可触发。 |
+| 名称 | 描述 |
+| -------- | -------- |
+| All | 所有方向。 |
+| Horizontal | 水平方向。 |
+| Vertical | 竖直方向。 |
+| None | 任何方向均不可触发。 |
 
 
 ## 事件
@@ -32,8 +32,6 @@ SwipeGesture(value?: { fingers?: number; direction?: SwipeDirection; speed?: num
 | -------- | -------- |
 | onAction(event:(event?: [GestureEvent](ts-gesture-settings.md)) => void) | 滑动手势识别成功回调。 |
 
-
-![zh-cn_image_0000001231374559](figures/zh-cn_image_0000001231374661.png)
 ## 示例
 
 ```ts
@@ -41,27 +39,31 @@ SwipeGesture(value?: { fingers?: number; direction?: SwipeDirection; speed?: num
 @Entry
 @Component
 struct SwipeGestureExample {
-  @State rotateAngle : number = 0
-  @State speed : number = 1
+  @State rotateAngle: number = 0;
+  @State speed: number = 1;
 
   build() {
     Column() {
-      Text("SwipGesture speed ： " + this.speed)
-      Text("SwipGesture angle ： " + this.rotateAngle)
-    }
-    .position({x: 80, y: 200})
-    .border({width:2})
-    .width(260).height(260)
-    .rotate({x: 0, y: 0, z: 1, angle: this.rotateAngle})
-    .gesture(
-      SwipeGesture({fingers: 1, direction: SwipeDirection.Vertical})
+      Column() {
+        Text("SwipeGesture speed\n" + this.speed)
+        Text("SwipeGesture angle\n" + this.rotateAngle)
+      }
+      .border({ width: 3 })
+      .width(300)
+      .height(200)
+      .margin(100)
+      .rotate({ angle: this.rotateAngle })
+      // 单指竖直方向滑动时触发该事件
+      .gesture(
+      SwipeGesture({ direction: SwipeDirection.Vertical })
         .onAction((event: GestureEvent) => {
-          this.speed = event.speed
-          this.rotateAngle = event.angle
-      })
-    )
+          this.speed = event.speed;
+          this.rotateAngle = event.angle;
+        })
+      )
+    }.width('100%')
   }
 }
 ```
 
-![zh-cn_image_0000001231374559](figures/zh-cn_image_0000001231374559.gif)
+![zh-cn_image_0000001231374559](figures/zh-cn_image_0000001231374559.png)

zh-cn/application-dev/reference/arkui-ts/ts-basic-gestures-tapgesture.md

@@ -29,20 +29,25 @@ TapGesture(value?: { count?: number, fingers?: number })
 @Entry
 @Component
 struct TapGestureExample {
-  @State value: string = ''
+  @State value: string = '';
 
   build() {
-    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
-      Text('Click twice')
+    Column() {
+      // 单指双击文本触发手势事件
+      Text('Click twice').fontSize(28)
+        .gesture(
+        TapGesture({ count: 2 })
+          .onAction((event: GestureEvent) => {
+            this.value = JSON.stringify(event.fingerList[0]);
+          })
+        )
       Text(this.value)
     }
-    .height(200).width(300).padding(60).border({ width: 1 }).margin(30)
-    .gesture(
-      TapGesture({ count: 2 })
-        .onAction(() => {
-          this.value = 'TapGesture onAction'
-        })
-    )
+    .height(200)
+    .width(300)
+    .padding(20)
+    .border({ width: 3 })
+    .margin(30)
   }
 }
 ```

zh-cn/application-dev/reference/arkui-ts/ts-combined-gestures.md

@@ -43,43 +43,67 @@ GestureGroup(mode: GestureMode, ...gesture: GestureType[])
 @Entry
 @Component
 struct GestureGroupExample {
-  @State count: number = 0
-  @State offsetX: number = 0
-  @State offsetY: number = 0
-  @State borderStyles: BorderStyle = BorderStyle.Solid
+  @State count: number = 0;
+  @State offsetX: number = 0;
+  @State offsetY: number = 0;
+  @State positionX: number = 0;
+  @State positionY: number = 0;
+  @State borderStyles: BorderStyle = BorderStyle.Solid;
 
   build() {
-    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
+    Column() {
       Text('sequence gesture\n' + 'LongPress onAction:' + this.count + '\nPanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY)
-    }.translate({ x: this.offsetX, y: this.offsetY, z: 5 })
-    .height(100).width(200).padding(10).margin(80).border({ width: 1, style: this.borderStyles })
+    }
+    .translate({ x: this.offsetX, y: this.offsetY, z: 0 })
+    .height(150)
+    .width(200)
+    .padding(20)
+    .margin(20)
+    .border({ width: 3, style: this.borderStyles })
     .gesture(
-      GestureGroup(GestureMode.Sequence,
-        LongPressGesture({ repeat: true })
-          .onAction((event: GestureEvent) => {
-            if (event.repeat) {this.count++}
-            console.log('LongPress onAction')
-          })
-          .onActionEnd(() => {
-            console.log('LongPress end')
-          }),
-        PanGesture({})
-          .onActionStart(() => {
-            this.borderStyles = BorderStyle.Dashed
-            console.log('pan start')
-          })
-          .onActionUpdate((event: GestureEvent) => {
-            this.offsetX = event.offsetX
-            this.offsetY = event.offsetY
-            console.log('pan update')
-          })
-      )
+      //以下组合手势为顺序识别，当长按手势事件未正常触发时则不会触发拖动手势事件
+    GestureGroup(GestureMode.Sequence,
+    LongPressGesture({ repeat: true })
+      .onAction((event: GestureEvent) => {
+        if (event.repeat) {
+          this.count++;
+        }
+        console.info('LongPress onAction');
+      })
+      .onActionEnd(() => {
+        console.info('LongPress end');
+      }),
+    PanGesture()
+      .onActionStart(() => {
+        this.borderStyles = BorderStyle.Dashed;
+        console.info('pan start');
+      })
+      .onActionUpdate((event: GestureEvent) => {
+        this.offsetX = this.positionX + event.offsetX;
+        this.offsetY = this.positionY + event.offsetY;
+        console.info('pan update');
+      })
+      .onActionEnd(() => {
+        this.positionX = this.offsetX;
+        this.positionY = this.offsetY;
+        this.borderStyles = BorderStyle.Solid;
+        console.info('pan end');
+      })
+    )
       .onCancel(() => {
-        console.log('sequence gesture canceled')
+        console.info('sequence gesture canceled');
       })
     )
   }
 }
 ```
 
-![zh-cn_image_0000001174104384](figures/zh-cn_image_0000001174104384.gif)
+示意图：
+
+按顺序首先触发长按事件：
+
+![zh-cn_image_0000001174104384](figures/zh-cn_image_0000001174104384.png)
+
+按顺序首先触发长按事件，长按事件识别结束之后，其次触发拖动事件，向右下方拖动：
+
+ ![zh-cn_image1_0000001174104384](figures/zh-cn_image1_0000001174104384.png) 
\ No newline at end of file

zh-cn/application-dev/reference/arkui-ts/ts-gesture-settings.md

@@ -43,7 +43,7 @@
 
 ## 响应手势事件
 
-组件通过gesture方法绑定手势对象，可以通过手势对象提供的事件相应响应手势操作。例如通过TapGesture对象的onAction事件响应点击事件。其余手势的事件定义见各个手势对象章节。
+组件通过gesture方法绑定手势对象，可以通过手势对象提供的事件相应响应手势操作。例如通过TapGesture对象的onAction事件响应点击事件。其余手势的事件定义见各个手势对象章节。若需绑定多种手势请使用 [组合手势](ts-combined-gestures.md)。
 
 - TapGesture事件说明
   | 名称 | 功能描述 |
@@ -77,8 +77,8 @@
   | 名称 | 类型 | 描述 |
   | -------- | -------- | -------- |
   | id | number | 手指的索引编号。 |
-  | globalX | number | 相对于设备屏幕左上角的x轴坐标。 |
-  | globalY | number | 相对于设备屏幕左上角的y轴坐标。 |
+  | globalX | number | 相对于应用窗口左上角的x轴坐标。 |
+  | globalY | number | 相对于应用窗口左上角的y轴坐标。 |
   | localX | number | 相对于当前组件元素左上角的x轴坐标。 |
   | localY | number | 相对于当前组件元素左上角的y轴坐标。 |
 
@@ -90,28 +90,51 @@
 @Entry
 @Component
 struct GestureSettingsExample {
-  @State value: string = ''
+  @State priorityTestValue: string = '';
+  @State parallelTestValue: string = '';
 
   build() {
-    Column(){
+    Column() {
       Column() {
-        Text('Click\n' + this.value)
+        Text('TapGesture:' + this.priorityTestValue).fontSize(28)
           .gesture(
           TapGesture()
             .onAction(() => {
-              this.value = 'gesture onAction'
+              this.priorityTestValue += '\nText';
             }))
-      }.height(200).width(300).padding(60).border({ width: 1 })
-      //设置为priorityGesture时，会优先识别该绑定手势忽略内部gesture手势
+      }
+      .height(200)
+      .width(250)
+      .padding(20)
+      .margin(20)
+      .border({ width: 3 })
+      // 设置为priorityGesture时，点击文本会忽略Text组件的TapGesture手势事件，优先识别父组件Column的TapGesture手势事件
       .priorityGesture(
       TapGesture()
         .onAction((event: GestureEvent) => {
-          this.value = 'priorityGesture onAction' + '\ncomponent globalPos:('
-          + event.target.area.globalPosition.x + ',' + event.target.area.globalPosition.y + ')\nwidth:'
-          + event.target.area.width + '\nheight:' + event.target.area.height
-        }), GestureMask.IgnoreInternal
-      )
-    }.padding(60)
+          this.priorityTestValue += '\nColumn';
+        }), GestureMask.IgnoreInternal)
+
+      Column() {
+        Text('TapGesture:' + this.parallelTestValue).fontSize(28)
+          .gesture(
+          TapGesture()
+            .onAction(() => {
+              this.parallelTestValue += '\nText';
+            }))
+      }
+      .height(200)
+      .width(250)
+      .padding(20)
+      .margin(20)
+      .border({ width: 3 })
+      // 设置为parallelGesture时，点击文本会同时触发子组件Text与父组件Column的TapGesture手势事件
+      .parallelGesture(
+      TapGesture()
+        .onAction((event: GestureEvent) => {
+          this.parallelTestValue += '\nColumn';
+        }), GestureMask.Normal)
+    }
   }
 }
 ```