harmony 鸿蒙@ohos.arkui.dragController (DragController)

2023-10-30
浏览 (334)

@ohos.arkui.dragController (DragController)

The dragController module provides APIs for initiating drag actions. When receiving a gesture event, such as a click or long-press event, an application can initiate a drag action and carry drag information therein.

NOTE

The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.

You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer.

excuteDrag and onDragStart cannot be configured at the same time.

Modules to Import

import dragController from "@ohos.arkui.dragController";

dragController.executeDrag

executeDrag(custom: CustomBuilder|DragItemInfo, dragInfo: DragInfo, callback: AsyncCallback<{event: DragEvent, extraParams: string}>): void

Initiates a drag action, with the object to be dragged and the drag information passed in. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
custom	CustomBuilder \|DragItemInfo	Yes	Object to be dragged.
dragInfo	DragInfo	Yes	Drag information.
callback	AsyncCallback<{event: DragEvent, extraParams: string}>	Yes	Callback used to return the result.

Example

import dragController from "@ohos.arkui.dragController"
import UDMF from '@ohos.data.unifiedDataChannel';

@Entry
@Component
struct DragControllerPage {
  @Builder DraggingBuilder() {
    Column() {
      Text("DraggingBuilder")
    }
    .width(100)
    .height(100)
    .backgroundColor(Color.Blue)
  }

  build() {
    Column() {
      Button('touch to execute drag')
        .onTouch((event?:TouchEvent) => {
          if(event){
            if (event.type == TouchType.Down) {
              let text = new UDMF.Text()
              let unifiedData = new UDMF.UnifiedData(text)

              let dragInfo: dragController.DragInfo = {
                pointerId: 0,
                data: unifiedData,
                extraParams: ''
              }
              class tmp{
                event:DragResult|undefined = undefined
                extraParams:string = ''
              }
              let eve:tmp = new tmp()
              dragController.executeDrag(this.DraggingBuilder(), dragInfo, (err, eve) => {
                if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
                // ...
                } else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
                // ...
                }
              })
            }
          }
        })
    }
  }
}

dragController.executeDrag

executeDrag(custom: CustomBuilder|DragItemInfo, dragInfo: DragInfo): Promise<{event: DragEvent, extraParams: string}>

Initiates a drag action, with the object to be dragged and the drag information passed in. This API uses a promise to return the result.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
custom	CustomBuilder \|DragItemInfo	Yes	Object to be dragged.
dragInfo	DragInfo	Yes	Drag information.

Return value

Type	Description
Promise<{event: DragEvent, extraParams: string}>	Promise used to return the result.

Example

import dragController from "@ohos.arkui.dragController"
import componentSnapshot from '@ohos.arkui.componentSnapshot';
import image from '@ohos.multimedia.image';
import UDMF from '@ohos.data.unifiedDataChannel';

@Entry
@Component
struct DragControllerPage {
  @State pixmap: image.PixelMap|null = null

  @Builder DraggingBuilder() {
    Column() {
      Text("DraggingBuilder")
    }
    .width(100)
    .height(100)
    .backgroundColor(Color.Blue)
  }

  @Builder PixmapBuilder() {
    Column() {
      Text("PixmapBuilder")
    }
    .width(100)
    .height(100)
    .backgroundColor(Color.Blue)
  }

  build() {
    Column() {
      Button('touch to execute drag')
        .onTouch((event?:TouchEvent) => {
          if(event){
            if (event.type == TouchType.Down) {
              let text = new UDMF.Text()
              let unifiedData = new UDMF.UnifiedData(text)

              let dragInfo: dragController.DragInfo = {
                pointerId: 0,
                data: unifiedData,
                extraParams: ''
              }
              componentSnapshot.createFromBuilder(this.PixmapBuilder()).then((pix: image.PixelMap) => {
                this.pixmap = pix;
                let dragItemInfo: DragItemInfo = {
                  pixelMap: this.pixmap,
                  builder: this.DraggingBuilder(),
                  extraInfo: "DragItemInfoTest"
                }

                class tmp{
                  event:DragResult|undefined = undefined
                  extraParams:string = ''
                }
                let eve:tmp = new tmp()
                dragController.executeDrag(dragItemInfo, dragInfo)
                  .then((eve) => {
                    if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
                      // ...
                    } else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
                      // ...
                    }
                  })
                  .catch((err:Error) => {
                  })
              })
            }
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

DragInfo

System capability: SystemCapability.ArkUI.ArkUI.Full

Defines the attributes required for initiating a drag action and information carried in the dragging process.

Name	Type	Mandatory	Description
pointerId	number	Yes	ID of the touch point on the screen when dragging is started.
data	unifiedDataChannel.UnifiedData	No	Data carried in the dragging process.
extraParams	string	No	Additional information about the drag action. Not supported currently.