@ohos.arkui.dragController (DragController)
本模块提供发起主动拖拽的能力，当应用接收到触摸或长按等事件时可以主动发起拖拽的动作，并在其中携带拖拽信息。
说明：
本模块首批接口从 API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用，参见UIContext说明。 示例效果请以真机运行为准，当前 DevEco Studio预览器不支持。
导入模块
import { dragController } from '@kit.ArkUI';
dragController.executeDrag(deprecated)
executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo,callback:AsyncCallback<DragEventParam>): void
主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。通过回调返回结果。
说明：
从API version 18开始废弃，建议使用UIContext中的getDragController获取DragController实例，再通过此实例调用替代方法executeDrag。
从API version 11开始，可以通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| custom | CustomBuilder | DragItemInfo | 是 | 拖拽发起后跟手效果所拖拽的对象。 说明： 不支持全局builder。如果builder中使用了Image组件，应尽量开启同步加载，即配置Image的syncLoad为true。该builder只用于生成当次拖拽中显示的图片。builder的根组件宽高为0时，无法生成拖拽显示的图片导致拖拽失败。builder的修改不会同步到当前正在拖拽的图片，对builder的修改需要在下一次拖拽时生效。 |
| dragInfo | DragInfo | 是 | 拖拽信息。 |
| callback | AsyncCallback<DragEventParam> | 是 | 拖拽结束返回结果的回调。 |
错误码：
以下错误码的详细介绍请参见通用错误码错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. |
| 100001 | Internal handling failed. |
示例：
说明：
推荐通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
import { dragController } from '@kit.ArkUI';
import { unifiedDataChannel } from '@kit.ArkData';
@Entry
@Component
struct DragControllerPage {
@State text: string = ''
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
.fontColor(Color.White)
.fontSize(12)
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
build() {
Column() {
Button('touch to execute drag')
.margin(10)
.onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
let text = new unifiedDataChannel.PlainText()
text.textContent = 'drag text'
text.abstract = 'abstract'
let unifiedData = new unifiedDataChannel.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
class tmp{
event:DragEvent|undefined = undefined
extraParams:string = ''
}
let eve:tmp = new tmp()
this.getUIContext().getDragController().executeDrag(()=>{this.DraggingBuilder()}, dragInfo, (err, eve) => { // 建议使用 this.getUIContext().getDragController().executeDrag()接口
if(eve.event){
if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
// ...
} else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
// ...
}
}
})
}
}
})
Text(this.text)
.height(100)
.width(150)
.margin({top:20})
.border({color:Color.Black,width:1})
.onDrop((dragEvent?:DragEvent)=>{
if(dragEvent){
let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords();
let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText;
this.text = plainText.textContent;
}
})
}
.width('100%')
.height('100%')
}
}
dragController.executeDrag(deprecated)
executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo): Promise<DragEventParam>
主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。通过Promise返回结果。
说明：
从API version 18开始废弃，建议使用UIContext中的getDragController获取DragController实例，再通过此实例调用替代方法executeDrag。
从API version 11开始，可以通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| custom | CustomBuilder | DragItemInfo | 是 | 拖拽发起后跟手效果所拖拽的对象。 |
| dragInfo | DragInfo | 是 | 拖拽信息。 |
返回值：
| 类型 | 说明 |
|---|---|
| Promise<DragEventParam> | 拖拽结束返回结果的回调。 |
错误码： 以下错误码的详细介绍请参见通用错误码错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. |
| 100001 | Internal handling failed. |
示例：
说明：
推荐通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
import { dragController } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';
import { unifiedDataChannel } from '@kit.ArkData';
@Entry
@Component
struct DragControllerPage {
@State pixmap: image.PixelMap|undefined = undefined
@State text: string = ''
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
.fontColor(Color.White)
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
@Builder PixmapBuilder() {
Column() {
Text("PixmapBuilder")
.fontColor(Color.White)
.fontSize(15)
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
aboutToAppear() {
let pb: CustomBuilder = (): void => {
this.PixmapBuilder()
}
this.getUIContext().getComponentSnapshot().createFromBuilder(pb).then((pix: image.PixelMap) => {
this.pixmap = pix;
})
}
build() {
Column() {
Button('touch to execute drag')
.margin(10)
.onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
let text = new unifiedDataChannel.PlainText()
text.textContent = 'drag text'
text.abstract = 'abstract'
let unifiedData = new unifiedDataChannel.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
let dragItemInfo: DragItemInfo = {
pixelMap: this.pixmap,
builder: ()=>{this.DraggingBuilder()},
extraInfo: "DragItemInfoTest"
}
class tmp{
event:DragResult|undefined = undefined
extraParams:string = ''
}
let eve:tmp = new tmp()
this.getUIContext().getDragController().executeDrag(dragItemInfo, dragInfo) // 建议使用 this.getUIContext().getDragController().executeDrag()接口
.then((eve) => {
if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
// ...
} else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
// ...
}
})
.catch((err:Error) => {
})
}
}
})
Text(this.text)
.height(100)
.width(150)
.margin({top:20})
.border({color:Color.Black,width:1})
.onDrop((dragEvent?:DragEvent)=>{
if(dragEvent){
let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords();
let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText;
this.text = plainText.textContent;
}
})
}
.width('100%')
.height('100%')
}
}
DragInfo
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
发起拖拽所需要的属性和拖拽时携带的信息。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| pointerId | number | 是 | 设置启动拖拽时屏幕上触摸点的Id。取值范围为0-9的整数。 |
| data | unifiedDataChannel.UnifiedData | 否 | 设置拖拽过程中携带的数据。 |
| extraParams | string | 否 | 设置拖拽事件额外信息，具体功能暂未实现。默认值为空。 |
| touchPoint11+ | TouchPoint | 否 | 配置跟手点坐标。不配置时，左右居中，顶部向下偏移20%。 |
| previewOptions11+ | DragPreviewOptions | 否 | 设置拖拽过程中背板图处理模式及数量角标的显示。 |
dragController.createDragAction(deprecated)
createDragAction(customArray: Array<CustomBuilder | DragItemInfo>, dragInfo: DragInfo): DragAction
创建拖拽的Action对象，需要显式指定拖拽背板图(可多个)，以及拖拽的数据，跟手点等信息；当通过一个已创建的 Action 对象发起的拖拽未结束时，无法再次创建新的 Action 对象，接口会抛出异常；当Action对象的生命周期结束后，注册在该对象上的回调函数会失效，因此需要在一个尽量长的作用域下持有该对象，并在每次发起拖拽前通过createDragAction返回新的对象覆盖旧值。
说明： 从API version 11开始支持，从API version 18开始废弃，建议使用UIContext中的getDragController获取DragController实例，再通过此实例调用替代方法createDragAction。
从API version 11开始，可以通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
建议控制传递的拖拽背板数量，传递过多容易导致拖起的效率问题。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| customArray | Array<CustomBuilder | DragItemInfo> | 是 | 拖拽发起后跟手效果所拖拽的对象。 |
| dragInfo | DragInfo | 是 | 拖拽信息。 |
返回值：
| 类型 | 说明 |
|---|---|
| DragAction | 创建拖拽Action对象，主要用于后面实现注册监听拖拽状态改变事件和启动拖拽服务。 |
错误码：
以下错误码的详细介绍请参见通用错误码错误码。
| 错误码ID | 错误信息 |
|---|---|
| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. |
| 100001 | Internal handling failed. |
示例：
说明：
推荐通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
import { dragController } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';
import { unifiedDataChannel } from '@kit.ArkData';
@Entry
@Component
struct DragControllerPage {
@State pixmap: image.PixelMap | null = null
@State text: string = ''
private dragAction: dragController.DragAction | null = null;
customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>();
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
.fontColor(Color.White)
.fontSize(12)
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
build() {
Column() {
Column() {
Text(this.text)
.width('100%')
.height('100%')
.fontColor(Color.White)
.fontSize(18)
.onDrop((dragEvent?:DragEvent)=>{
if(dragEvent){
let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords();
let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText;
this.text = plainText.textContent;
}
})
}
.width(100)
.height(100)
.backgroundColor(Color.Red)
.margin(10)
Button('多对象dragAction customBuilder拖拽').onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
console.info("multi drag Down by listener");
this.customBuilders.splice(0, this.customBuilders.length);
this.customBuilders.push(()=>{this.DraggingBuilder()});
this.customBuilders.push(()=>{this.DraggingBuilder()});
this.customBuilders.push(()=>{this.DraggingBuilder()});
let text = new unifiedDataChannel.PlainText()
text.textContent = 'drag text'
let unifiedData = new unifiedDataChannel.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
try{
this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // 建议使用 this.getUIContext().getDragController().createDragAction()接口
if(!this.dragAction){
console.info("listener dragAction is null");
return
}
this.dragAction.on('statusChange', (dragAndDropInfo: dragController.DragAndDropInfo)=>{
if (dragAndDropInfo.status == dragController.DragStatus.STARTED) {
console.info("drag has start");
} else if (dragAndDropInfo.status == dragController.DragStatus.ENDED){
console.info("drag has end");
if (!this.dragAction) {
return
}
this.dragAction.off('statusChange')
}
})
this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{
console.info("start drag Error:" + err.message);
})
} catch(err) {
console.info("create dragAction Error:" + err.message);
}
}
}
}).margin({top:20})
}
}
}
DragAction11+
监听状态改变，启动拖拽服务的对象。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
startDrag11+
startDrag(): Promise<void>
启动拖拽服务，返回Promise对象，回调启动成功和失败的结果。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
返回值：
| 类型 | 说明 |
|---|---|
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
错误码：
| 错误码ID | 错误信息 |
|---|---|
| 100001 | Internal handling failed. |
示例：
说明：
推荐通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
import { dragController } from '@kit.ArkUI';
import { unifiedDataChannel } from '@kit.ArkData';
@Entry
@Component
struct DragControllerPage {
private dragAction: dragController.DragAction | null = null;
customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>();
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
.fontColor(Color.White)
.fontSize(12)
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
build() {
Column() {
Button('touch to execute drag').onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
this.customBuilders.splice(0, this.customBuilders.length);
this.customBuilders.push(()=>{this.DraggingBuilder()});
let text = new unifiedDataChannel.PlainText()
text.textContent = 'drag text'
let unifiedData = new unifiedDataChannel.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
try{
this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // 建议使用 this.getUIContext().getDragController().createDragAction()接口
if(!this.dragAction){
console.info("listener dragAction is null");
return;
}
this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{
console.info("start drag Error:" + err.message);
})
} catch(err) {
console.info("create dragAction Error:" + err.message);
}
}
}
}).margin({top:20})
}
}
}
on('statusChange')11+
on(type: 'statusChange', callback: Callback<DragAndDropInfo>): void
注册监听拖拽状态改变事件。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 监听事件，固定为'statusChange'，即注册监听拖拽状态改变事件。 |
| callback | Callback<DragAndDropInfo> | 是 | 回调函数，返回当前的DragAndDropInfo组件状态。 |
示例：
说明：
推荐通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
import { dragController } from '@kit.ArkUI';
import { unifiedDataChannel } from '@kit.ArkData';
@Entry
@Component
struct DragControllerPage {
private dragAction: dragController.DragAction | null = null;
customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>();
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
.fontColor(Color.White)
.fontSize(12)
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
build() {
Column() {
Button('touch to execute drag').onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
this.customBuilders.splice(0, this.customBuilders.length);
this.customBuilders.push(()=>{this.DraggingBuilder()});
let text = new unifiedDataChannel.PlainText()
text.textContent = 'drag text'
let unifiedData = new unifiedDataChannel.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
let func = (dragAndDropInfo: dragController.DragAndDropInfo) => {
console.info("Register to listen on drag status", JSON.stringify(dragAndDropInfo));
}
try{
this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // 建议使用 this.getUIContext().getDragController().createDragAction()接口
if(!this.dragAction){
console.info("listener dragAction is null");
return;
}
// 监听状态改变，触发后打印func中的日志
this.dragAction.on('statusChange', func);
this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{
console.info("start drag Error:" + err.message);
})
} catch(err) {
console.info("create dragAction Error:" + err.message);
}
}
}
}).margin({top:20})
}
}
}
off('statusChange')11+
off(type: 'statusChange', callback?: Callback<DragAndDropInfo>): void
取消注册监听拖拽状态改变事件。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 监听事件，固定为'statusChange'，即取消监听拖拽状态改变事件。 |
| callback | Callback<DragAndDropInfo> | 否 | 回调函数，取消注册了该回调函数的事件， 不设置取消所有监听。 |
示例：
说明：
推荐通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
import { dragController } from '@kit.ArkUI';
import { unifiedDataChannel } from '@kit.ArkData';
@Entry
@Component
struct DragControllerPage {
private dragAction: dragController.DragAction | null = null;
customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>();
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
.fontColor(Color.White)
.fontSize(12)
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
build() {
Column() {
Button('touch to execute drag').onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
this.customBuilders.splice(0, this.customBuilders.length);
this.customBuilders.push(()=>{this.DraggingBuilder()});
let text = new unifiedDataChannel.PlainText()
text.textContent = 'drag text'
let unifiedData = new unifiedDataChannel.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
let func = (dragAndDropInfo: dragController.DragAndDropInfo) => {
console.info("Register to listen on drag status", JSON.stringify(dragAndDropInfo));
}
try{
this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // 建议使用 this.getUIContext().getDragController().createDragAction()接口
if(!this.dragAction){
console.info("listener dragAction is null");
return;
}
this.dragAction.on('statusChange', func);
// 取消监听，发起拖拽后不会打印func中的日志
this.dragAction.off('statusChange', func);
this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{
console.info("start drag Error:" + err.message);
})
} catch(err) {
console.info("create dragAction Error:" + err.message);
}
}
}
}).margin({top:20})
}
}
}
DragAndDropInfo11+
拖拽过程中监听到status改变时上报的数据。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| status | DragStatus | 是 | 当前拖拽状态（启动和结束）。 |
| event | DragEvent | 是 | 当前状态所对应的拖拽事件。通过dragController发起的dragEvent仅支持获取result和behavior，且用于拖拽结束状态。 |
| extraParams | string | 否 | 设置拖拽事件额外信息，具体功能暂未实现。默认值为空。 |
DragStatus11+
拖拽开始和结束状态。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 值 | 说明 |
|---|---|---|
| STARTED | 0 | 拖拽已成功发起。 |
| ENDED | 1 | 拖拽结束。 |
AnimationOptions11+
拖拽相关的动效参数。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| duration | number | 否 | 动画持续时间，单位为毫秒。 默认值：1000 说明： - 设置小于0的值时按0处理。 - 设置浮点型类型的值时，向下取整。例如，设置值为1.2，按照1处理。 |
| curve | Curve | ICurve | 否 | 设置动画曲线。 默认值：Curve.EaseInOut |
DragEventParam12+
拖拽结束返回结果的回调。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| event10+ | DragEvent | 是 | 拖拽事件信息，仅包括拖拽结果。 |
| extraParams10+ | string | 是 | 拖拽事件额外信息。 |
dragController.getDragPreview(deprecated)
getDragPreview(): DragPreview
返回一个代表拖拽背板的对象。
说明：
从API version 11开始支持，从API version 18开始废弃，建议使用UIContext中的getDragController获取DragController实例，再通过此实例调用替代方法getDragPreview。
从API version 11开始，可以通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
返回值：
| 类型 | 说明 |
|---|---|
| DragPreview | 一个代表拖拽背板的对象，提供背板样式设置的接口，在OnDrop和OnDragEnd回调中使用不生效。 |
示例：
请参考animate
DragPreview11+
拖拽背板的对象，在OnDrop和OnDragEnd回调中使用不生效。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
setForegroundColor11+
setForegroundColor(color: ResourceColor): void
设置背板蒙版颜色，在OnDrop和OnDragEnd回调中使用不生效，仅支持通过 getDragPreview() 方法获取到的对象上使用。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| color | ResourceColor | 是 | 背板蒙版颜色。 |
示例：
请参考animate
animate11+
animate(options: AnimationOptions, handler: () => void): void
设置背板蒙版颜色变化动效，在OnDrop和OnDragEnd回调中使用不生效，仅支持通过 getDragPreview() 方法获取到的对象上使用。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| options | AnimationOptions | 是 | 动效参数。 |
| handler | () => void | 是 | 用于修改背板蒙版颜色等属性的回调方法。 |
示例：
说明：
推荐通过使用UIContext中的getDragController方法获取当前UI上下文关联的DragController对象。
1.在EntryAbility.ets中获取UI上下文并保存至LocalStorage中。
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window, UIContext } from '@kit.ArkUI';
let uiContext: UIContext;
let localStorage: LocalStorage = new LocalStorage('uiContext');
export default class EntryAbility extends UIAbility {
storage: LocalStorage = localStorage;
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
}
onDestroy(): void {
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy');
}
onWindowStageCreate(windowStage: window.WindowStage): void {
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', this.storage, (err, data) => {
if (err.code) {
hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', `Code is ${err.code}, message is ${err.message}`);
return;
}
hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', `Code is ${err.code}, message is ${err.message}`);
windowStage.getMainWindow((err, data) => {
if (err.code) {
hilog.error(0x0000, `Failed to abtain the main window. Cause: ${err.message}`, '');
return;
}
let windowClass: window.Window = data;
uiContext = windowClass.getUIContext();
this.storage.setOrCreate<UIContext>('uiContext', uiContext);
})
});
}
}
2.在Index.ets中通过this.getUIContext().getSharedLocalStorage()获取UI上下文，进而获取DragController对象实施后续操作。
import { unifiedDataChannel } from '@kit.ArkData';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { dragController, curves, promptAction, UIContext } from '@kit.ArkUI';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry()
@Component
struct DragControllerPage {
@State pixmap: image.PixelMap|null = null;
storages = this.getUIContext().getSharedLocalStorage();
@Builder DraggingBuilder() {
Column() {
Text("DraggingBuilder")
.fontColor(Color.White)
.fontSize(12)
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
@Builder PixmapBuilder() {
Column() {
Text("PixmapBuilder")
}
.width(100)
.height(100)
.backgroundColor(Color.Blue)
}
build() {
Column() {
Button('拖拽至此处')
.margin(10)
.onDragEnter(() => {
try {
let uiContext: UIContext = this.storages?.get<UIContext>('uiContext') as UIContext;
let previewObj: dragController.DragPreview = uiContext.getDragController().getDragPreview();
let foregroundColor: ResourceColor = Color.Green;
let previewAnimation: dragController.AnimationOptions = {
curve: curves.cubicBezierCurve(0.2,0,0,1),
}
previewObj.animate(previewAnimation, () => {
previewObj.setForegroundColor(foregroundColor);
});
} catch (error) {
let msg = (error as BusinessError).message;
let code = (error as BusinessError).code;
hilog.error(0x0000, `show error code is ${code}, message is ${msg}`, '');
}
})
.onDrop(() => {
this.getUIContext().getPromptAction().showToast({duration: 100, message: 'Drag Success', bottom: 400})
})
Button('拖起').onTouch((event?:TouchEvent) => {
if(event){
if (event.type == TouchType.Down) {
let text = new unifiedDataChannel.Text()
let unifiedData = new unifiedDataChannel.UnifiedData(text)
let dragInfo: dragController.DragInfo = {
pointerId: 0,
data: unifiedData,
extraParams: ''
}
class tmp{
event:DragEvent|undefined = undefined
extraParams:string = ''
}
let eve:tmp = new tmp()
this.getUIContext().getDragController().executeDrag(() => { // 建议使用 this.getUIContext().getDragController().executeDrag()接口
this.DraggingBuilder()
}, dragInfo, (err , eve) => {
hilog.info(0x0000, `${JSON.stringify(err)}`, '')
if (eve && eve.event) {
if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
hilog.info(0x0000, 'success', '');
} else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
hilog.info(0x0000, 'failed', '');
}
}
})
}
}
}).margin({top:100})
}
.width('100%')
.height('100%')
}
}
DragStartRequestStatus18+
定义应用是否可以发起拖拽的枚举类型。
原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 值 | 说明 |
|---|---|---|
| WAITING | 0 | 应用准备数据中，无法发起拖拽。 |
| READY | 1 | 应用数据准备完成，可以发起拖拽。 |