!20701 拖拽文档更新

Merge pull request !20701 from tsj_2020/master

zh-cn/application-dev/reference/arkui-ts/ts-types.md

@@ -226,7 +226,7 @@
 
 | 名称            | 类型定义                   | 描述                                       |
 | ------------- | ---------------------- | ---------------------------------------- |
-| CustomBuilder | () => any | 该方法类型必须使用@Builder装饰器修饰。具体用法见[@Builder](../../quick-start/arkts-builder.md#builder)。 |
+| CustomBuilder | () => any | 生成用户自定义组件，在使用时结合@Builder使用。具体用法见[@Builder](../../quick-start/arkts-builder.md#builder)。 |
 
 ## PixelStretchEffectOptions<sup>10+</sup>
 

zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-drag-drop.md

@@ -16,7 +16,7 @@
 
 | 名称 | 参数类型 | 描述 |
 | -------- | -------- | -------- |
-| allowDrop | Array\<UnifiedData> | 设置该组件上允许落入的数据类型。<br/>默认值：空<br/> |
+| allowDrop | Array\<[UnifiedDataType](../apis/js-apis-data-udmf.md#unifieddatatype)> | 设置该组件上允许落入的数据类型。<br/>默认值：空<br/> |
 | draggable | boolean | 设置该组件是否允许进行拖拽。<br/>默认值：false<br/> |
 
 

zh-cn/application-dev/reference/arkui-ts/ts-universal-events-drag-drop.md

@@ -5,12 +5,16 @@
 >  **说明：**
 >
 >  从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
+>
+>  已实现默认拖拽效果组件：
+>
+>[Image](../arkui-ts/ts-basic-components-image.md), [Text](../arkui-ts/ts-basic-components-text.md), [TextArea](../arkui-ts/ts-basic-components-textarea.md),[Search](../arkui-ts/ts-basic-components-search.md)
 
 ## 事件
 
 | 名称                                                         | 支持冒泡 | 功能描述                                                     |
 | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ |
-| onDragStart(event:&nbsp;(event?:&nbsp;[DragEvent](#dragevent说明),&nbsp;extraParams?:&nbsp;string)&nbsp;=&gt;&nbsp;&nbsp;[CustomBuilder](ts-types.md#custombuilder8) \| [DragItemInfo](#dragiteminfo说明)) | 否       | 第一次拖拽此事件绑定的组件时，触发回调。<br/>- event：拖拽事件信息，包括拖拽点坐标。<br/>- extraParams：拖拽事件额外信息，详见[extraParams](#extraparams说明)说明。<br/>返回值：当前跟手效果所拖拽的对象，用于显示拖拽时的提示组件。<br/>长按500ms可触发拖拽事件。优先级：长按手势配置时间小于等于500ms时，长按手势优先触发，否则拖拽事件优先触发。 |
+| onDragStart(event:&nbsp;(event?:&nbsp;[DragEvent](#dragevent说明),&nbsp;extraParams?:&nbsp;string)&nbsp;=&gt;&nbsp;&nbsp;[CustomBuilder](ts-types.md#custombuilder8) \| [DragItemInfo](#dragiteminfo说明)) | 否       | 第一次拖拽此事件绑定的组件时，触发回调。<br/>- event：拖拽事件信息，详见[DragEvent](#dragevent说明)。<br/>- extraParams：拖拽事件额外信息，详见[extraParams](#extraparams说明)说明。<br/> 返回值：拖拽过程中显示的组件信息。<br/>触发条件：长按时间 >= 500ms。<br> 事件优先级：长安触发时间 < 500ms，长按事件 > 拖拽事件<br> 其他： 拖拽事件 > 长按事件。 |
 | onDragEnter(event:&nbsp;(event?:&nbsp;[DragEvent](#dragevent说明),&nbsp;extraParams?:&nbsp;string)&nbsp;=&gt;&nbsp;void) | 否       | 拖拽进入组件范围内时，触发回调。<br/>- event：拖拽事件信息，包括拖拽点坐标。<br/>- extraParams：拖拽事件额外信息，详见[extraParams](#extraparams说明)说明。<br/>当监听了onDrop事件时，此事件才有效。 |
 | onDragMove(event:&nbsp;(event?:&nbsp;[DragEvent](#dragevent说明),&nbsp;extraParams?:&nbsp;string)&nbsp;=&gt;&nbsp;void) | 否       | 拖拽在组件范围内移动时，触发回调。<br/>- event：拖拽事件信息，包括拖拽点坐标。<br/>- extraParams：拖拽事件额外信息，详见[extraParams](#extraparams说明)说明。<br/>当监听了onDrop事件时，此事件才有效。 |
 | onDragLeave(event:&nbsp;(event?:&nbsp;[DragEvent](#dragevent说明),&nbsp;extraParams?:&nbsp;string)&nbsp;=&gt;&nbsp;void) | 否       | 拖拽离开组件范围内时，触发回调。<br/>- event：拖拽事件信息，包括拖拽点坐标。<br/>- extraParams：拖拽事件额外信息，详见[extraParams](#extraparams说明)说明。<br/>当监听了onDrop事件时，此事件才有效。 |
@@ -44,21 +48,13 @@
 | getX() | number | 当前拖拽点相对于屏幕左上角的x轴坐标，单位为vp。 |
 | getY() | number | 当前拖拽点相对于屏幕左上角的y轴坐标，单位为vp。 |
 | useCustomDropAnimation<sup>10+</sup> | boolean | 当拖拽结束时，是否使用系统默认落入动画。 |
-| dragBehavior<sup>10+</sup> | [DragBehavior](#dragbehavior10枚举说明) | DrgaEvent对应的组件树行为。 |
-| setData(unifiedData: UnifiedData)<sup>10+</sup> | void | 向DragEvent中设置拖拽相关数据。 |
-| getData()<sup>10+</sup> | UnifiedData | 从DragEvent中获取拖拽相关数据。 |
-| getSummary()<sup>10+</sup> | Summary | 从DragEvent中获取拖拽相关数据的简介。 |
+| setData(unifiedData: [UnifiedData](../apis/js-apis-data-udmf.md#unifieddata))<sup>10+</sup> | void | 向DragEvent中设置拖拽相关数据。 |
+| getData()<sup>10+</sup> | [UnifiedData](../apis/js-apis-data-udmf.md#unifieddata) | 从DragEvent中获取拖拽相关数据。 |
+| getSummary()<sup>10+</sup> | [Summary](../apis/js-apis-data-udmf.md#summary) | 从DragEvent中获取拖拽相关数据的简介。 |
 | setResult(dragRect: [DragRet](#dragret10枚举说明))<sup>10+</sup> | void | 向DragEvent中设置拖拽结果。 |
 | getResult()<sup>10+</sup> | [DragRet](#dragret10枚举说明) | 从DragEvent中获取拖拽结果。 |
 | getPrviewRect()<sup>10+</sup> | [Rectangle](ts-universal-attributes-touch-target.md#rectangle对象说明) | 获取预览图所在的Rectangle。 |
 
-## DragBehavior<sup>10+</sup>枚举说明
-
-| 名称 | 描述 |
-| ------ | ------ |
-| COPY | 在组件树上，对发起拖拽的组件进行拷贝，将拷贝结果复制到拖拽结束的位置。 |
-| MOVE | 在组件树上，对发起拖拽的组件进行裁剪，移动至拖拽结束的位置。 |
-
 ## DragRet<sup>10+</sup>枚举说明
 
 | 名称 | 描述 |
@@ -71,266 +67,165 @@
 
 ## 示例
 
-### 示例1
-
 ```ts
-import UDMF from '@ohos.data.UDMF';
-
-@Observed
-class ClassA {
-  public name: string
-  public bol: boolean
-
-  constructor(name: string, bol: boolean) {
-    this.name = name
-    this.bol = bol
-  }
-}
-
-@Extend(Text) function textStyle() {
-  .width('25%')
-  .height(35)
-  .fontSize(16)
-  .textAlign(TextAlign.Center)
-  .backgroundColor(0xAFEEEE)
-}
-
+import udmf from '@ohos.data.UDMF';
+import promptAction from '@ohos.promptAction';
 @Entry
 @Component
-struct DragExample {
-  @State arr: ClassA[] = [new ClassA('A', true), new ClassA('B', true), new ClassA('C', true)]
-  @State dragIndex: number = 0
-  @State mTextNew: string = ''
-  @State mBool: boolean = false
-
-  changeIndex(index1: number, index2: number) { // 交换数组位置
-    [this.arr[index1], this.arr[index2]] = [this.arr[index2], this.arr[index1]];
-  }
-
-  public getDataFromUDMFWithRetry(event: DragEvent) {
-    let records = event.getData().getRecords();
-    if (records) {
-      let plainText = <UDMF.PlainText> (records[0])
-      this.mTextNew = plainText.textContent
-      this.mBool = false
+struct Index {
+  @State targetImage: string = '';
+  @State targetText: string = 'Drag Text';
+  @State hyperLinkText: string = 'HyperLink';
+  @State hyperLinkContent: string = 'HyperLink';
+  @State imageWidth: number = 100;
+  @State imageHeight: number = 100;
+  @State imgState: Visibility = Visibility.Visible;
+  @State videoSrc: string = 'resource://RAWFILE/02.mp4';
+  @State abstractContent: string = "abstract";
+  @State textContent: string = "";
+
+  getDataFromUdmfRetry(event: DragEvent, callback: (data: DragEvent)=>void)
+  {
+    let records: Array<udmf.UnifiedRecord> = event.getData().getRecords();
+    if (records.length !== 0) {
+      callback(event);
       return;
     }
-    // 获取失败延时 1.5s 再次获取
-    setTimeout(() => {
-        this.getDataFromUDMFWithRetry(event)
-    }, 1500)
+    setTimeout(()=>{
+      this.getDataFromUdmfRetry(event, callback);
+    }, 1500);
   }
 
   build() {
-    Column() {
-      Row({ space: 15 }) {
-        List({ space: 20 }) {
-          ForEach(this.arr, (item, index) => {
-            ListItem() {
-              Column() {
-                Child({ a: this.arr[index] })
-              }
-              .onTouch((event: TouchEvent) => {
-                if (event.type === TouchType.Down) {
-                  this.dragIndex = index // 获取当前拖拽子组件的索引
-                  console.info('onTouch' + this.dragIndex)
-                }
-              })
-            }
-          })
-        }
-        .listDirection(Axis.Horizontal)
-        .onDrop((event: DragEvent, extraParams: string) => { // 绑定此事件的组件可作为拖拽释放目标，当在本组件范围内停止拖拽行为时，触发回调。
-          this.getDataFromUDMFWithRetry(event);
+    Row() {
+      Column() {
+        Text('start Drag')
+          .fontSize(18)
+          .width('100%')
+          .height(40)
+          .margin(10)
+          .backgroundColor('#008888')
+        Image($r('app.media.icon'))
+          .width(100)
+          .height(100)
+          .draggable(true)
+          .margin({left: 15})
+          .visibility(this.imgState)
+          .onDragEnd((event)=>{
+          if (event.getResult() === DragRet.DRAG_SUCCESS) {
+            promptAction.showToast({duration: 100, message: 'Drag Success'});
+          } else if (event.getResult() === DragRet.DRAG_FAILED) {
+            promptAction.showToast({duration: 100, message: 'Drag failed'});
+          }
         })
-      }.padding({ top: 10, bottom: 10 }).margin(10)
-
-    }.width('100%').height('100%').padding({ top: 20 }).margin({ top: 20 })
-  }
-}
-
-@Component
-struct Child {
-  @ObjectLink a: ClassA
-
-  @Builder pixelMapBuilder() {
-    Column() {
-      Text(this.a.name)
-        .width('50%')
-        .height(60)
-        .fontSize(16)
-        .borderRadius(10)
-        .textAlign(TextAlign.Center)
-        .backgroundColor(Color.Yellow)
-    }
-  }
-
-  build() {
-    Column() {
-      Text(this.a.name)
-        .textStyle()
-        .visibility(this.a.bol ? Visibility.Visible : Visibility.None)
-        .onDragStart(() => { // 第一次拖拽此事件绑定的组件时，触发回调。
-          this.a.bol = false // 控制显隐
-          return this.pixelMapBuilder() // 设置拖拽过程中显示的图片。
+        Text('test drag event')
+          .width('100%')
+          .height(100)
+          .draggable(true)
+          .margin({left: 15})
+          .copyOption(CopyOptions.InApp)
+        TextArea({placeholder: 'please input words'})
+          .copyOption(CopyOptions.InApp)
+          .width('100%')
+          .height(50)
+          .draggable(true)
+        Search({placeholder: 'please input you word'})
+          .searchButton('Search')
+          .width('100%')
+          .height(80)
+          .textFont({size: 20})
+        Column() {
+          Text('change video source')
+        }.draggable(true)
+        .onDragStart((event)=>{
+          let video: udmf.Video = new udmf.Video();
+          video.videoUri = 'resource://RAWFILE/01.mp4';
+          let data: udmf.UnifiedData = new udmf.UnifiedData(video);
+          event.setData(data);
         })
-        .onTouch((event: TouchEvent) => {
-          if (event.type === TouchType.Up) {
-            this.a.bol = true
-          }
+        Column() {
+          Text('this is abstract')
+            .fontSize(20)
+            .width('100%')
+        }.margin({left: 40, top: 20})
+        .width('100%')
+        .height(100)
+        .onDragStart((event)=>{
+          let data: udmf.PlainText = new udmf.PlainText();
+          data.abstract = 'this is abstract';
+          data.textContent = 'this is content this is content';
+          event.setData(new udmf.UnifiedData(data));
         })
-      Text('')
-        .width('25%')
-        .height(35)
-        .fontSize(16)
-        .textAlign(TextAlign.Center)
-        .border({ width: 5, color: 'red' })
-        .visibility(!this.a.bol ? Visibility.Visible : Visibility.None)
-    }
-  }
-}
-```
-
-![drag-drop](figures/drag-drop.gif)
-
-### 示例2
-
-```ts
-// xxx.ets
-import UDMF from '@ohos.data.UDMF';
-
-@Extend(Text) function textStyle () {
-  .width('25%')
-  .height(35)
-  .fontSize(16)
-  .textAlign(TextAlign.Center)
-  .backgroundColor(0xAFEEEE)
-}
-
-@Entry
-@Component
-struct DragExample {
-  @State numbers: string[] = ['one', 'two', 'three', 'four', 'five', 'six']
-  @State text: string = ''
-  @State bool: boolean = true
-  @State mBool: boolean = false
-  @State mTextNew: string = ''
-  @State eventType: string = ''
-  @State appleVisible: Visibility = Visibility.Visible
-  @State orangeVisible: Visibility = Visibility.Visible
-  @State bananaVisible: Visibility = Visibility.Visible
-  private dragList: string[] = ['apple', 'orange', 'banana']
-  @State fruitVisible: Visibility[] = [Visibility.Visible, Visibility.Visible, Visibility.Visible]
-  @State idx: number = 0
-
-  // 自定义拖拽过程中显示的内容
-  @Builder pixelMapBuilder() {
-    Column() {
-      Text(this.text)
-        .width('50%')
-        .height(60)
-        .fontSize(16)
-        .borderRadius(10)
-        .textAlign(TextAlign.Center)
-        .backgroundColor(Color.Yellow)
-    }
-  }
-
-  public getDataFromUDMFWithRetry(event: DragEvent) {
-    let records = event.getData().getRecords()
-    if (records) {
-      let plainText = <UDMF.PlainText> (records[0])
-      this.mTextNew = plainText.textContent
-      this.mBool = false
-      return;
-    }
-    // 获取失败延时 1.5s 再次获取
-    setTimeout(() => {
-        this.getDataFromUDMFWithRetry(event)
-    }, 1500)
-  }
-
-  build() {
-    Column() {
-      Text('There are three Text elements here')
-        .fontSize(12)
-        .fontColor(0xCCCCCC)
-        .width('90%')
-        .textAlign(TextAlign.Start)
-        .margin(5)
-      Row({ space: 15 }) {
-        ForEach(this.dragList, (item, index) => {
-          Text(item)
-            .textStyle()
-            .visibility(this.fruitVisible[index])
-            .onDragStart(() => {
-              this.bool = true
-              this.text = item
-              this.fruitVisible[index] = Visibility.None
-              return this.pixelMapBuilder
+      }.width('45%')
+      .height('100%')
+      Column() {
+        Text('Drag Target Area')
+          .fontSize(20)
+          .width('100%')
+          .height(40)
+          .margin(10)
+          .backgroundColor('#008888')
+        Image(this.targetImage)
+          .width(this.imageWidth)
+          .height(this.imageHeight)
+          .draggable(true)
+          .margin({left: 15})
+          .border({color: Color.Black, width: 1})
+          .allowDrop([udmf.UnifiedDataType.IMAGE])
+          .onDrop((dragEvent: DragEvent)=> {
+            this.getDataFromUdmfRetry(dragEvent, (event)=>{
+              let records: Array<udmf.UnifiedRecord> = event.getData().getRecords();
+              let rect: Rectangle = event.getPreviewRect();
+              this.imageWidth = Number(rect.width);
+              this.imageHeight = Number(rect.height);
+              this.targetImage = (<udmf.Image>(records[0])).imageUri;
+              event.useCustomDropAnimation = false;
+              animateTo({duration: 1000}, ()=>{
+                this.imageWidth = 100;
+                this.imageHeight = 100;
+                this.imgState = Visibility.None;
+              })
+              event.setResult(DragRet.DRAG_SUCCESS);
             })
-            .onTouch((event: TouchEvent) => {
-              if (event.type === TouchType.Down) {
-                this.eventType = 'Down'
-                this.idx = index
-              }
-              if (event.type === TouchType.Up) {
-                this.eventType = 'Up'
-                if (this.bool) {
-                  this.fruitVisible[index] = Visibility.Visible
-                }
-              }
+          })
+
+        Text(this.targetText)
+          .width('100%')
+          .height(100)
+          .border({color: Color.Black, width: 1})
+          .margin(15)
+          .allowDrop([udmf.UnifiedDataType.TEXT])
+          .onDrop((dragEvent: DragEvent)=>{
+            this.getDataFromUdmfRetry(dragEvent, event => {
+              let records:Array<udmf.UnifiedRecord> = event.getData().getRecords();
+              this.targetText = (<udmf.Text>(records[0])).details['value'];
             })
-        })
-      }.padding({ top: 10, bottom: 10 }).margin(10)
+          })
 
-      Text('This is a List element')
-        .fontSize(12)
-        .fontColor(0xCCCCCC)
-        .width('90%')
-        .textAlign(TextAlign.Start)
-        .margin(15)
-      List({ space: 20 }) {
-        ForEach(this.numbers, (item) => {
-          ListItem() {
-            Text(item)
-              .width('100%')
-              .height(80)
-              .fontSize(16)
-              .borderRadius(10)
-              .textAlign(TextAlign.Center)
-              .backgroundColor(0xAFEEEE)
-          }
-        }, item => item)
-      }
-      .editMode(true)
-      .height('50%')
-      .width('90%')
-      .border({ width: 1 })
-      .padding(15)
-      .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 })
-      .onDragEnter((event: DragEvent, extraParams: string) => {
-        console.log('List onDragEnter, ' + extraParams + 'X:' + event.getX() + 'Y:' + event.getY())
-      })
-      .onDragMove((event: DragEvent, extraParams: string) => {
-        console.log('List onDragMove, ' + extraParams + 'X:' + event.getX() + 'Y:' + event.getY())
-      })
-      .onDragLeave((event: DragEvent, extraParams: string) => {
-        console.log('List onDragLeave, ' + extraParams + 'X:' + event.getX() + 'Y:' + event.getY())
-      })
-      .onDrop((event: DragEvent, extraParams: string) => {
-        let jsonString = JSON.parse(extraParams);
-        if (this.bool) {
-          // 通过splice方法插入元素
-          this.numbers.splice(jsonString.insertIndex, 0, this.text)
-          this.bool = false
-        }
-        this.fruitVisible[this.idx] = Visibility.None
-        this.getDataFromUDMFWithRetry(event);
-      })
-    }.width('100%').height('100%').padding({ top: 20 }).margin({ top: 20 })
+        Video({src: this.videoSrc, previewUri: $r('app.media.icon')})
+          .width('100%')
+          .height(200)
+          .controls(true)
+          .allowDrop([udmf.UnifiedDataType.VIDEO])
+
+        Column() {
+          Text(this.abstractContent).fontSize(20).width('100%')
+          Text(this.textContent).fontSize(15).width('100%')
+        }.width('100%').height(100).margin(20).border({color: Color.Black, width: 1})
+        .allowDrop([udmf.UnifiedDataType.PLAIN_TEXT])
+        .onDrop((dragEvent)=>{
+          this.getDataFromUdmfRetry(dragEvent, event=>{
+            let records: Array<udmf.UnifiedRecord> = event.getData().getRecords();
+            let plainText: udmf.PlainText = <udmf.PlainText>(records[0]);
+            this.abstractContent = plainText.abstract;
+            this.textContent = plainText.textContent;
+          })
+        })
+      }.width('45%')
+      .height('100%')
+      .margin({left: '5%'})
+    }
+    .height('100%')
   }
 }
 ```
-
-![zh-cn_image_0000001252667389](figures/zh-cn_image_0000001252667389.gif)