借助 Android 拖放框架，您可以向应用中添加交互式拖放功能。通过拖放，用户可以在应用中的 View 之间复制或拖动文本、图片、对象（可以通过 URI 表示的任何内容），也可以使用多窗口模式在应用之间拖动这些内容。
|
|
|
|
|
该框架包括拖动事件类、拖动监听器，以及帮助程序类和方法。虽然该框架主要用于实现数据传输，但也可用于实现其他界面操作。例如，您可以创建一个应用，用于在用户将一个颜色图标拖到另一个颜色图标上时进行颜色混合。不过，本指南的其余部分将介绍在数据传输上下文中的拖放框架。
概览
当用户做出某种界面手势，而您的应用将该手势识别为开始拖动数据的信号时，拖放操作便会开始。作为响应，应用要通知系统，让系统知道拖放操作要开始了。系统会回调您的应用，以获取用户正在拖动的数据的表示（拖动阴影）。当用户将拖动阴影移动到应用的布局上时，系统会向与布局中的 View 对象关联的拖动事件监听器和回调方法发送拖动事件。如果用户将拖动阴影释放到可以接受数据的视图（拖放目标）上，系统会将数据发送到拖放目标。用户释放拖动阴影时，无论拖动阴影是否在拖放目标上，拖放操作都会结束。
您要通过实现 View.OnDragListener 来创建拖动事件监听器，并使用 View 对象的 setOnDragListener() 方法为拖放目标设置监听器。布局中的每个视图也有一个 onDragEvent() 回调方法。
您的应用要通过调用 startDragAndDrop() 方法（用于通知系统开始发送拖动事件），通知系统开始执行拖放操作。该方法还会向系统提供用户正在拖动的数据以及描述这些数据的元数据。您可以对当前布局中的任何 View 调用 startDragAndDrop()。系统将仅使用 View 对象来获取对布局中的全局设置的访问权限。
在拖放操作期间，系统会向布局中 View 对象的拖动事件监听器或回调方法发送拖动事件。监听器或回调方法会根据元数据来确定是否要在用户放下数据时接受这些数据。如果用户将数据放到拖放目标（将接受数据的 View）上，系统会将包含相应数据的拖动事件对象发送到拖放目标的拖动事件监听器或回调方法。
拖动事件监听器和回调方法
View 使用可实现 View.OnDragListener 的拖动事件监听器或视图的 onDragEvent() 回调方法来接收拖动事件。当系统调用相应方法或监听器时，会提供一个 DragEvent 参数。
在大多数情况下，使用监听器比使用回调方法更可取。设计界面时，您通常不需要为 View 类创建子类，但使用回调方法时，您必须创建子类来替换回调方法。相比之下，您可以实现一个监听器类，然后将其与多个不同的 View 对象配合使用。您也可以将其实现为匿名内联类或 lambda 表达式。如需为 View 对象设置监听器，请调用 setOnDragListener()。
或者，您可以更改 onDragEvent() 的默认实现，而不替换相应方法。如果您为某个视图设置了 OnReceiveContentListener（请参阅 setOnReceiveContentListener()），默认情况下，onDragEvent() 方法会执行以下操作：
- 返回 true 以响应对
startDragAndDrop()的调用 如果用户将拖放数据放到该视图上，则调用
performReceiveContent()数据会作为
ContentInfo对象传递给该方法。该方法会调用OnReceiveContentListener。如果用户将拖放数据放到该视图上，并且
OnReceiveContentListener使用了其中的任何内容，则返回 true
您需要定义 OnReceiveContentListener 来处理专门用于您的应用的数据。为了向后兼容到 API 级别 24，请使用 OnReceiveContentListener 的 Jetpack 版本。
您可以为 View 对象同时使用拖动事件监听器和回调方法，在这种情况下，系统会首先调用监听器。除非监听器返回 false，否则系统不会调用回调方法。
onDragEvent() 方法和 View.OnDragListener 的组合与用于触摸事件的 onTouchEvent() 和 View.OnTouchListener 的组合类似。
拖放过程
拖放过程基本包含四个步骤或状态：已开始、正在继续、已放下和已结束。
- 已开始
为了响应用户的拖动手势，您的应用要调用
startDragAndDrop()，以便通知系统开始执行拖放操作。该方法的参数用于提供以下内容：- 拖动的数据
- 用于绘制拖动阴影的回调
- 用于描述所拖动数据的元数据
系统会首先回调您的应用来进行响应，以便获取拖动阴影。然后，系统会在设备上显示拖动阴影。
接下来，系统会向当前布局中所有
View的拖动事件监听器发送一个操作类型为ACTION_DRAG_STARTED的拖动事件。如要继续接收拖动事件（包括可能的放下事件），拖动事件监听器必须返回true。这样便可在系统中注册该监听器。只有已注册的监听器才能继续接收拖动事件。此时，监听器也可更改其拖放目标View对象的外观，以表明该视图可以接受放下事件。如果拖动事件监听器返回
false，则在系统发送操作类型为ACTION_DRAG_ENDED的拖动事件之前，拖动事件监听器将不会收到当前操作的拖动事件。通过返回false，监听器会通知系统它对拖放操作不感兴趣，不想接受用户拖动的数据。- 正在继续
用户在继续拖动数据。当拖动阴影与拖动目标的边界框相交时，系统会向拖放目标的拖动事件监听器发送一个或多个拖动事件。监听器可以选择更改拖放目标
View的外观，以响应该事件。例如，如果该事件表明拖动阴影已进入拖放目标的边界框（操作类型为ACTION_DRAG_ENTERED），监听器可通过突出显示View来做出反应。- 已放下
用户在拖放目标的边界框内释放拖动阴影。系统会向拖放目标的监听器发送一个操作类型为
ACTION_DROP的拖动事件。该拖动事件对象中包含已在启动操作的startDragAndDrop()调用中传递给系统的数据。如果监听器成功处理了用户放下的数据，应向系统返回布尔值true。请注意，如果用户将拖动阴影放到
View的边界框内，那么仅当该视图的监听器已注册为可接收拖动事件时（即该视图为拖放目标时），才会出现此步骤。如果用户在任何其他情况下释放拖动阴影，系统都不会发送任何ACTION_DROP拖动事件。- 已结束
在用户释放拖动阴影且系统发出（如有必要）操作类型为
ACTION_DROP的拖动事件后，系统会发出一个操作类型为ACTION_DRAG_ENDED的拖动事件，以指明拖放操作已结束。无论用户在何处释放拖动阴影，系统都会执行此操作。系统会将该事件发送到每个已注册为可接收拖动事件的监听器，包括已收到ACTION_DROP事件的监听器。
拖放操作部分对以上四个步骤分别进行了更详细的说明。
拖动事件
系统会以 DragEvent 对象的形式发出拖动事件，其中包含一个用于描述拖放过程中发生的情况的操作类型。该对象还可能包含其他数据，具体取决于操作类型。
拖动事件监听器可接收 DragEvent 对象。为了获取操作类型，监听器会调用 DragEvent#getAction()。可能的值有六个，由 DragEvent 类中的常量定义。
表 1. DragEvent 操作类型
| 操作类型 | 含义 |
|---|---|
ACTION_DRAG_STARTED |
应用已调用
startDragAndDrop() 并获得拖动阴影。如果监听器想要继续接收此操作的拖动事件，必须向系统返回布尔值 true。
|
ACTION_DRAG_ENTERED |
拖动阴影刚刚进入拖动事件监听器的 View 的边界框。这是在拖动阴影进入边界框时，监听器收到的第一个事件操作类型。
|
ACTION_DRAG_LOCATION |
在 ACTION_DRAG_ENTERED 事件后，拖动阴影仍在拖动事件监听器的 View 的边界框内。
|
ACTION_DRAG_EXITED |
在 ACTION_DRAG_ENTERED 以及至少一个 ACTION_DRAG_LOCATION 事件发生后，拖动阴影已移动到拖动事件监听器的 View 的边界框之外。
|
ACTION_DROP |
用户已在拖动事件监听器的 View 上释放拖动阴影。仅当 View 对象的监听器返回布尔值 true 作为对 ACTION_DRAG_STARTED 拖动事件的响应时，系统才会将此操作类型发送至监听器。如果用户将拖动阴影释放到监听器未注册的 View 上，或释放到不属于当前布局的任何对象上，系统都不会发送此操作类型。
如果成功处理了放下操作，监听器应返回布尔值 |
ACTION_DRAG_ENDED |
系统即将结束拖放操作。此操作类型不一定在 ACTION_DROP 事件之后。如果系统发送了 ACTION_DROP，收到 ACTION_DRAG_ENDED 操作类型并不表示放下操作已成功。监听器必须调用 getResult()（请参阅表 2）来获取在响应 ACTION_DROP 时返回的值。如果系统未发送 ACTION_DROP 事件，getResult() 将返回 false。
|
DragEvent 对象还包含应用在调用 startDragAndDrop() 时向系统提供的数据和元数据。如表 2 中汇总，部分数据仅对某些操作类型有效。如需详细了解事件及其关联的数据，请参阅拖放操作。
表 2. 按操作类型列出的有效 DragEvent 数据
getAction()值 |
getClipDescription()值 |
getLocalState()值 |
getX()值 |
getY()值 |
getClipData()值 |
getResult()值 |
|---|---|---|---|---|---|---|
ACTION_DRAG_STARTED |
✓ | ✓ | ✓ | ✓ | ||
ACTION_DRAG_ENTERED |
✓ | ✓ | ||||
ACTION_DRAG_LOCATION |
✓ | ✓ | ✓ | ✓ | ||
ACTION_DRAG_EXITED |
✓ | ✓ | ||||
ACTION_DROP |
✓ | ✓ | ✓ | ✓ | ✓ | |
ACTION_DRAG_ENDED |
✓ | ✓ |
DragEvent getAction()、describeContents()、writeToParcel() 和 toString() 方法始终会返回有效数据。
如果某个方法不包含对特定操作类型来说有效的数据，该方法将返回 null 或 0，具体取决于结果类型。
拖动阴影
在执行拖放操作期间，系统会显示用户正在拖动的图片。对于数据移动操作，此图片表示用户正在拖动的数据。对于其他操作，此图片表示拖动操作的某个方面。
此图片称为拖动阴影。您可以使用为 View.DragShadowBuilder 对象声明的方法来创建此图片。使用 startDragAndDrop() 开始拖放操作时，您会将构建器传递给系统。作为对 startDragAndDrop() 进行响应的一部分，系统会调用您在 View.DragShadowBuilder 中定义的回调方法来获取拖动阴影。
View.DragShadowBuilder 类有两个构造函数：
View.DragShadowBuilder(View)该构造函数可接受您的应用的任何
View对象。该构造函数会将View对象存储在View.DragShadowBuilder对象中，以便回调可以获取视图对象来构造拖动阴影。该视图不必是用户为启动拖动操作而选择的View（如有）。如果您使用该构造函数，则无需扩展
View.DragShadowBuilder，也无需替换其方法。默认情况下，您获取的拖动阴影与您作为参数传递的View具有相同的外观，并且中心点位于用户接触屏幕的位置。View.DragShadowBuilder()如果您使用该构造函数，
View.DragShadowBuilder对象（该字段会被设为null）中将没有任何可用的View对象。您必须扩展View.DragShadowBuilder并替换其方法，否则您将会获得不可见的拖动阴影。系统不会抛出错误。
View.DragShadowBuilder 类有两个方法，您可以一起使用这两个方法来创建拖动阴影：
onProvideShadowMetrics()在您调用
startDragAndDrop()后，系统会立即调用该方法。使用该方法可以向系统发送拖动阴影的尺寸和接触点。该方法有两个参数：onDrawShadow()调用
onProvideShadowMetrics()后，系统会立即调用onDrawShadow()来创建拖动阴影。该方法只有一个参数，即系统根据您在onProvideShadowMetrics()中提供的参数构造的Canvas对象。该方法用于在收到的Canvas中绘制拖动阴影。
为了提高性能，您应使拖动阴影保持较小的尺寸。对于单项内容，您可能希望使用图标。如果用户选择了多项内容，您可能希望使用堆栈中的图标，而非在屏幕上展开的完整图片。
拖放操作
本部分介绍了关于如何开始拖动、如何在拖动期间响应事件、如何响应放下事件以及如何结束拖放操作的分步说明。
开始拖动
用户使用拖动手势（通常是轻触并按住 View 对象）开始拖动。作为响应，您的应用应执行以下操作：
为用户正在移动的数据创建
ClipData对象和ClipData.Item对象。作为ClipData的一部分，提供存储在ClipData内的ClipDescription对象中的元数据。对于不表示数据移动的拖放操作，您可能需要使用null，而非实际对象。例如，以下代码段展示了，如何通过创建包含
ImageView的标记（或标签）的ClipData对象，来响应ImageView上的轻触并按住手势：Kotlin
// Create a string for the ImageView label. val IMAGEVIEW_TAG = "icon bitmap" ... val imageView = ImageView(this).apply { // Sets the bitmap for the ImageView from an icon bit map (defined elsewhere). setImageBitmap(iconBitmap) tag = IMAGEVIEW_TAG setOnLongClickListener { v -> // Create a new ClipData. // This is done in two steps to provide clarity. The convenience method // ClipData.newPlainText() can create a plain text ClipData in one step. // Create a new ClipData.Item from the ImageView object's tag. val item = ClipData.Item(v.tag as? CharSequence) // Create a new ClipData using the tag as a label, the plain text MIME type, and // the already-created item. This creates a new ClipDescription object within the // ClipData and sets its MIME type to "text/plain". val dragData = ClipData( v.tag as? CharSequence, arrayOf(ClipDescription.MIMETYPE_TEXT_PLAIN), item) // Instantiate the drag shadow builder. val myShadow = MyDragShadowBuilder(this) // Start the drag. v.startDragAndDrop(dragData, // The data to be dragged myShadow, // The drag shadow builder null, // No need to use local data 0 // Flags (not currently used, set to 0) ) // Indicate that the long-click was handled. true } }Java
// Create a string for the ImageView label. private static final String IMAGEVIEW_TAG = "icon bitmap"; ... // Create a new ImageView. ImageView imageView = new ImageView(this); // Set the bitmap for the ImageView from an icon bit map (defined elsewhere). imageView.setImageBitmap(iconBitmap); // Set the tag. imageView.setTag(IMAGEVIEW_TAG); // Sets a long click listener for the ImageView using an anonymous listener object that // implements the OnLongClickListener interface. imageView.setOnLongClickListener( v -> { // Create a new ClipData. // This is done in two steps to provide clarity. The convenience method // ClipData.newPlainText() can create a plain text ClipData in one step. // Create a new ClipData.Item from the ImageView object's tag. ClipData.Item item = new ClipData.Item((CharSequence) v.getTag()); // Create a new ClipData using the tag as a label, the plain text MIME type, and // the already-created item. This creates a new ClipDescription object within the // ClipData and sets its MIME type to "text/plain". ClipData dragData = new ClipData( (CharSequence) v.getTag(), new String[] { ClipDescription.MIMETYPE_TEXT_PLAIN }, item); // Instantiate the drag shadow builder. View.DragShadowBuilder myShadow = new MyDragShadowBuilder(imageView); // Start the drag. v.startDragAndDrop(dragData, // The data to be dragged myShadow, // The drag shadow builder null, // No need to use local data 0 // Flags (not currently used, set to 0) ); // Indicate that the long-click was handled. return true; });以下代码段通过替换
View.DragShadowBuilder中的方法来定义myDragShadowBuilder。这段代码会为TextView创建一个小小的灰色矩形拖动阴影：Kotlin
private class MyDragShadowBuilder(v: View) : View.DragShadowBuilder(v) { private val shadow = ColorDrawable(Color.LTGRAY) // Defines a callback that sends the drag shadow dimensions and touch point // back to the system. override fun onProvideShadowMetrics(size: Point, touch: Point) { // Set the width of the shadow to half the width of the original View. val width: Int = view.width / 2 // Set the height of the shadow to half the height of the original View. val height: Int = view.height / 2 // The drag shadow is a ColorDrawable. This sets its dimensions to be the // same as the Canvas that the system provides. As a result, the drag shadow // fills the Canvas. shadow.setBounds(0, 0, width, height) // Set the size parameter's width and height values. These get back to // the system through the size parameter. size.set(width, height) // Set the touch point's position to be in the middle of the drag shadow. touch.set(width / 2, height / 2) } // Defines a callback that draws the drag shadow in a Canvas that the system // constructs from the dimensions passed to onProvideShadowMetrics(). override fun onDrawShadow(canvas: Canvas) { // Draw the ColorDrawable on the Canvas passed in from the system. shadow.draw(canvas) } }Java
private static class MyDragShadowBuilder extends View.DragShadowBuilder { // The drag shadow image, defined as a drawable object. private static Drawable shadow; // Constructor public MyDragShadowBuilder(View v) { // Stores the View parameter. super(v); // Creates a draggable image that fills the Canvas provided by the system. shadow = new ColorDrawable(Color.LTGRAY); } // Defines a callback that sends the drag shadow dimensions and touch point // back to the system. @Override public void onProvideShadowMetrics (Point size, Point touch) { // Defines local variables int width, height; // Set the width of the shadow to half the width of the original View. width = getView().getWidth() / 2; // Set the height of the shadow to half the height of the original View. height = getView().getHeight() / 2; // The drag shadow is a ColorDrawable. This sets its dimensions to be the // same as the Canvas that the system provides. As a result, the drag shadow // fills the Canvas. shadow.setBounds(0, 0, width, height); // Set the size parameter's width and height values. These get back to the // system through the size parameter. size.set(width, height); // Set the touch point's position to be in the middle of the drag shadow. touch.set(width / 2, height / 2); } // Defines a callback that draws the drag shadow in a Canvas that the system // constructs from the dimensions passed to onProvideShadowMetrics(). @Override public void onDrawShadow(Canvas canvas) { // Draw the ColorDrawable on the Canvas passed in from the system. shadow.draw(canvas); } }
响应拖动开始事件
在拖动操作期间，系统会向当前布局中 View 对象的拖动事件监听器发送拖动事件。监听器应通过调用 DragEvent#getAction() 做出反应，以获取操作类型。拖动开始时，该方法将返回 ACTION_DRAG_STARTED。
为了响应操作类型为 ACTION_DRAG_STARTED 的事件，拖动事件监听器应执行以下操作：
调用
DragEvent#getClipDescription()并使用返回的ClipDescription中的 MIME 类型方法，查看监听器能否接受用户正在拖动的数据。如果拖放操作不表示数据移动，可能就没必要这样做。
如果拖动事件监听器可以接受放下事件，则应返回
true，以通知系统继续向该监听器发送拖动事件。如果该监听器无法接受放下事件，则应返回false，届时系统将停止向该监听器发送拖动事件，直到系统发送ACTION_DRAG_ENDED结束拖放操作为止。
请注意，对于 ACTION_DRAG_STARTED 事件，以下 DragEvent 方法全部无效：getClipData()、getX()、getY() 和 getResult()。
处理拖动期间的事件
在拖动操作期间，返回 true 以响应 ACTION_DRAG_STARTED 拖动事件的拖动事件监听器会继续接收拖动事件。监听器在拖动操作期间收到的拖动事件的类型取决于拖动阴影的位置，以及监听器的 View 的可见性。监听器主要使用拖动事件来确定是否应更改其 View 的外观。
在拖动操作期间，DragEvent#getAction() 会返回以下三个值之一：
ACTION_DRAG_ENTERED：当接触点（用户手指或鼠标在屏幕上指向的点）已进入监听器的View的边界框时，监听器会收到该事件操作类型。ACTION_DRAG_LOCATION：如果监听器收到了ACTION_DRAG_ENTERED事件，但没有收到ACTION_DRAG_EXITED事件，监听器会在接触点每次移动时收到新的ACTION_DRAG_LOCATION事件。getX()和getY()方法会返回接触点的 X 坐标和 Y 坐标。ACTION_DRAG_EXITED：系统会将该事件操作类型发送给先前收到ACTION_DRAG_ENTERED的监听器。当拖动阴影的接触点从监听器的View的边界框内移到边界框外时，系统会发送该事件。
拖动事件监听器不需要对以上任何操作类型做出反应。如果监听器向系统返回值，该值将被忽略。
以下是响应以上各种操作类型的一些准则：
- 在响应
ACTION_DRAG_ENTERED或ACTION_DRAG_LOCATION时，监听器可更改View的外观，以表明该视图是可能的拖放目标。 - 操作类型为
ACTION_DRAG_LOCATION的事件包含getX()和getY()的有效数据，对应于接触点的位置。监听器可以根据这些信息来更改View在接触点处的外观，或根据这些信息来确定用户可以释放拖动阴影（即放下数据）的确切位置。 - 在响应
ACTION_DRAG_EXITED时，监听器应重置在响应ACTION_DRAG_ENTERED或ACTION_DRAG_LOCATION时应用的所有外观更改，以便向用户表明，View已不再是当下的拖放目标。
响应放下事件
如果用户将拖动阴影释放到 View 上，并且 View 之前报告它可以接受用户正在拖动的内容，系统会向 View 发送一个操作类型为 ACTION_DROP 的拖动事件。
拖动事件监听器应执行以下操作：
调用
getClipData()以获取最初在startDragAndDrop()调用中提供的ClipData对象，并处理相应数据。如果拖放操作不表示数据移动，则没必要这样做。
返回布尔值
true，以表明已成功处理放下事件；如果处理失败，则返回false。返回的值将成为getResult()针对最终ACTION_DRAG_ENDED事件返回的值。请注意，如果系统未发出
ACTION_DROP事件，getResult()会针对ACTION_DRAG_ENDED事件返回值false。
对于 ACTION_DROP 事件，getX() 和 getY() 会使用已收到放下事件的 View 的坐标系，以返回接触点在放下时刻的 X 和 Y 位置。
系统允许用户将拖动阴影释放到拖动事件监听器不接收拖动事件的 View 上，而且允许用户将拖动阴影释放到应用界面的空白区域或应用以外的区域。在所有这些情况下，系统均不会发送操作类型为 ACTION_DRAG_ENDED 的事件，不过它会发送 ACTION_DROP 事件。
响应拖动结束事件
在用户释放拖动阴影后，系统会立即向应用中的所有拖动事件监听器发送操作类型为 ACTION_DRAG_ENDED 的拖动事件。这表示拖放操作已结束。
每个拖动事件监听器都应执行以下操作：
- 如果监听器在操作期间更改了
View对象的外观，监听器应将View重置为默认外观。这是一种视觉指示，旨在向用户表明操作已结束。 - 监听器可以选择调用
getResult()，以了解关于该操作的更多信息。如果监听器在响应操作类型为ACTION_DROP的事件时返回了true，那么getResult()会返回布尔值true。在所有其他情况下，getResult()会返回布尔值false，包括系统未发送ACTION_DROP事件的情况。 - 若要表明拖放操作已成功完成，监听器应向系统返回布尔值
true。
响应拖动事件：示例
所有拖动事件均由拖动事件方法或监听器接收。以下代码段是一个关于响应拖动事件的简单示例：
Kotlin
val imageView = ImageView(this)
// Set the drag event listener for the View.
imageView.setOnDragListener { v, e ->
// Handles each of the expected events.
when (e.action) {
DragEvent.ACTION_DRAG_STARTED -> {
// Determines if this View can accept the dragged data.
if (e.clipDescription.hasMimeType(ClipDescription.MIMETYPE_TEXT_PLAIN)) {
// As an example of what your application might do, applies a blue color tint
// to the View to indicate that it can accept data.
(v as? ImageView)?.setColorFilter(Color.BLUE)
// Invalidate the view to force a redraw in the new tint.
v.invalidate()
// Returns true to indicate that the View can accept the dragged data.
true
} else {
// Returns false to indicate that, during the current drag and drop operation,
// this View will not receive events again until ACTION_DRAG_ENDED is sent.
false
}
}
DragEvent.ACTION_DRAG_ENTERED -> {
// Applies a green tint to the View.
(v as? ImageView)?.setColorFilter(Color.GREEN)
// Invalidates the view to force a redraw in the new tint.
v.invalidate()
// Returns true; the value is ignored.
true
}
DragEvent.ACTION_DRAG_LOCATION ->
// Ignore the event.
true
DragEvent.ACTION_DRAG_EXITED -> {
// Resets the color tint to blue.
(v as? ImageView)?.setColorFilter(Color.BLUE)
// Invalidates the view to force a redraw in the new tint.
v.invalidate()
// Returns true; the value is ignored.
true
}
DragEvent.ACTION_DROP -> {
// Gets the item containing the dragged data.
val item: ClipData.Item = e.clipData.getItemAt(0)
// Gets the text data from the item.
val dragData = item.text
// Displays a message containing the dragged data.
Toast.makeText(this, "Dragged data is $dragData", Toast.LENGTH_LONG).show()
// Turns off any color tints.
(v as? ImageView)?.clearColorFilter()
// Invalidates the view to force a redraw.
v.invalidate()
// Returns true. DragEvent.getResult() will return true.
true
}
DragEvent.ACTION_DRAG_ENDED -> {
// Turns off any color tinting.
(v as? ImageView)?.clearColorFilter()
// Invalidates the view to force a redraw.
v.invalidate()
// Does a getResult(), and displays what happened.
when(e.result) {
true ->
Toast.makeText(this, "The drop was handled.", Toast.LENGTH_LONG)
else ->
Toast.makeText(this, "The drop didn't work.", Toast.LENGTH_LONG)
}.show()
// Returns true; the value is ignored.
true
}
else -> {
// An unknown action type was received.
Log.e("DragDrop Example", "Unknown action type received by View.OnDragListener.")
false
}
}
}
Java
View imageView = new ImageView(this);
// Set the drag event listener for the View.
imageView.setOnDragListener( (v, e) -> {
// Handles each of the expected events.
switch(e.getAction()) {
case DragEvent.ACTION_DRAG_STARTED:
// Determines if this View can accept the dragged data.
if (e.getClipDescription().hasMimeType(ClipDescription.MIMETYPE_TEXT_PLAIN)) {
// As an example of what your application might do, applies a blue color tint
// to the View to indicate that it can accept data.
((ImageView)v).setColorFilter(Color.BLUE);
// Invalidate the view to force a redraw in the new tint.
v.invalidate();
// Returns true to indicate that the View can accept the dragged data.
return true;
}
// Returns false to indicate that, during the current drag and drop operation,
// this View will not receive events again until ACTION_DRAG_ENDED is sent.
return false;
case DragEvent.ACTION_DRAG_ENTERED:
// Applies a green tint to the View.
((ImageView)v).setColorFilter(Color.GREEN);
// Invalidates the view to force a redraw in the new tint.
v.invalidate();
// Returns true; the value is ignored.
return true;
case DragEvent.ACTION_DRAG_LOCATION:
// Ignore the event.
return true;
case DragEvent.ACTION_DRAG_EXITED:
// Resets the color tint to blue.
((ImageView)v).setColorFilter(Color.BLUE);
// Invalidates the view to force a redraw in the new tint.
v.invalidate();
// Returns true; the value is ignored.
return true;
case DragEvent.ACTION_DROP:
// Gets the item containing the dragged data.
ClipData.Item item = e.getClipData().getItemAt(0);
// Gets the text data from the item.
CharSequence dragData = item.getText();
// Displays a message containing the dragged data.
Toast.makeText(this, "Dragged data is " + dragData, Toast.LENGTH_LONG).show();
// Turns off any color tints.
((ImageView)v).clearColorFilter();
// Invalidates the view to force a redraw.
v.invalidate();
// Returns true. DragEvent.getResult() will return true.
return true;
case DragEvent.ACTION_DRAG_ENDED:
// Turns off any color tinting.
((ImageView)v).clearColorFilter();
// Invalidates the view to force a redraw.
v.invalidate();
// Does a getResult(), and displays what happened.
if (e.getResult()) {
Toast.makeText(this, "The drop was handled.", Toast.LENGTH_LONG).show();
} else {
Toast.makeText(this, "The drop didn't work.", Toast.LENGTH_LONG).show();
}
// Returns true; the value is ignored.
return true;
// An unknown action type was received.
default:
Log.e("DragDrop Example","Unknown action type received by View.OnDragListener.");
break;
}
return false;
});
在多窗口模式下拖放
搭载 Android 7.0（API 级别 24）或更高版本的设备支持多窗口模式，可让用户通过拖放操作将数据从一个应用移动到另一个应用（请参阅多窗口支持）。
来源应用提供数据。拖放操作始于来源应用。目标应用接收数据。拖放操作结束于目标应用。
开始执行拖放操作时，来源应用必须设置 DRAG_FLAG_GLOBAL 标志，以指明用户可以将数据拖动到其他应用。
由于数据是跨应用边界移动，因此这些应用需要使用内容 URI 共享对数据的访问权限：
- 来源应用必须设置
DRAG_FLAG_GLOBAL_URI_READ和/或DRAG_FLAG_GLOBAL_URI_WRITE标志，具体取决于来源应用要授予目标应用的数据读/写权限。 - 目标应用必须在马上要处理用户拖入应用的数据之前调用
requestDragAndDropPermissions()。如果目标应用不再需要访问拖放数据，则可以针对从requestDragAndDropPermissions()返回的对象调用release()。否则，系统会在销毁容器 activity 时释放相应权限。
以下代码段展示了如何在拖放操作发生后立即释放对拖动数据的只读权限。如需查看更完整的示例，请参见 GitHub 上的 DragAndDrop 示例。
来源拖放 activity
Kotlin
// Drag a file stored in internal storage. The file is in an "images/" directory.
val internalImagesDir = File(context.filesDir, "images")
val imageFile = File(internalImagesDir, imageFilename)
val uri = FileProvider.getUriForFile(context, contentAuthority, imageFile)
val listener = OnDragStartListener@{ view: View, _: DragStartHelper ->
val clipData = ClipData(ClipDescription("Image Description",
arrayOf("image/*")),
ClipData.Item(uri))
// Must include DRAG_FLAG_GLOBAL to allow for dragging data between apps.
// This example provides read-only access to the data.
val flags = View.DRAG_FLAG_GLOBAL or View.DRAG_FLAG_GLOBAL_URI_READ
return@OnDragStartListener view.startDragAndDrop(clipData,
View.DragShadowBuilder(view),
null,
flags)
}
// Container where the image originally appears in the source app.
val srcImageView = findViewById<ImageView>(R.id.imageView)
// Detect and start the drag event.
DragStartHelper(srcImageView, listener).apply {
attach()
}
Java
// Drag a file stored under an "images/" directory in internal storage.
File internalImagesDir = new File(context.getFilesDir(), "images");
File imageFile = new File(internalImagesDir, imageFilename);
final Uri uri = FileProvider.getUriForFile(context, contentAuthority, imageFile);
// Container where the image originally appears in the source app.
ImageView srcImageView = findViewById(R.id.imageView);
// Enable the view to detect and start the drag event.
new DragStartHelper(srcImageView, (view, helper) -> {
ClipData clipData = new ClipData(new ClipDescription("Image Description",
new String[] {"image/*"}),
new ClipData.Item(uri));
// Must include DRAG_FLAG_GLOBAL to allow for dragging data between apps.
// This example provides read-only access to the data.
int flags = View.DRAG_FLAG_GLOBAL | View.DRAG_FLAG_GLOBAL_URI_READ;
return view.startDragAndDrop(clipData,
new View.DragShadowBuilder(view),
null,
flags);
}).attach();
目标拖放 activity
Kotlin
// Container for where the image is to be dropped in the target app.
val targetImageView = findViewById<ImageView>(R.id.imageView)
targetImageView.setOnDragListener { view, event ->
when (event.action) {
ACTION_DROP -> {
val imageItem: ClipData.Item = event.clipData.getItemAt(0)
val uri = imageItem.uri
// Request permission to access the image data being dragged into
// the target activity's ImageView element.
val dropPermissions = requestDragAndDropPermissions(event)
(view as ImageView).setImageURI(uri)
// Release the permission immediately afterwards because it's
// no longer needed.
dropPermissions.release()
return@setOnDragListener true
}
// Implement logic for other DragEvent cases here.
// An unknown action type was received.
else -> {
Log.e("DragDrop Example", "Unknown action type received by View.OnDragListener.")
return@setOnDragListener false
}
}
}
Java
// Container where the image is to be dropped in the target app.
ImageView targetImageView = findViewById(R.id.imageView);
targetImageView.setOnDragListener( (view, event) -> {
switch (event.getAction()) {
case ACTION_DROP:
ClipData.Item imageItem = event.getClipData().getItemAt(0);
Uri uri = imageItem.getUri();
// Request permission to access the image data being
// dragged into the target activity's ImageView element.
DragAndDropPermissions dropPermissions =
requestDragAndDropPermissions(event);
((ImageView)view).setImageURI(uri);
// Release the permission immediately afterwards because
// it's no longer needed.
dropPermissions.release();
return true;
// Implement logic for other DragEvent cases here.
// An unknown action type was received.
default:
Log.e("DragDrop Example","Unknown action type received by View.OnDragListener.");
break;
}
return false;
});
用于简化拖放的 DropHelper
DropHelper 类可简化拖放功能的实现。DropHelper 是 Jetpack DragAndDrop 库的成员，可向后兼容至 API 级别 24。
您可以使用 DropHelper 来指定拖放目标、自定义拖放目标突出显示，以及定义如何处理用户放下的数据。
拖放目标
DropHelper#configureView() 是一种静态的过载方法，可让您指定拖放目标。参数包括：
- 当前
Activity（用于 URI 权限） - 充当拖放目标的
View - 用户放下的数据中，拖放目标可以接受的 MIME 类型
- 拖放目标的配置选项（具体来说，是一个嵌入式 EditText 字段列表）
- 一个
OnReceiveContentListener，用于处理用户放下的数据
例如，若要创建能够接受图片的拖放目标，请使用以下方法调用之一：
Kotlin
configureView(
myActivity,
targetView,
arrayOf("image/*"),
options,
onReceiveContentListener)
// or
configureView(
myActivity,
targetView,
arrayOf("image/*"),
onReceiveContentListener)
Java
DropHelper.configureView(
myActivity,
targetView,
new String[] {"image/*"},
options,
onReceiveContentlistener);
// or
DropHelper.configureView(
myActivity,
targetView,
new String[] {"image/*"},
onReceiveContentlistener);
第二个调用省略了拖放目标配置选项，在这种情况下，拖放目标突出显示颜色会设为主题辅助颜色（或强调色），突出显示圆角半径会设为 16dp，并且 EditText 列表为空（请参阅下文中的拖放目标配置）。
拖放目标配置
借助 DropHelper.Options 内部类，您可以配置拖放目标。您需要向
DropHelper.configureView(Activity, View, String[], Options,
OnReceiveContentListener) 方法提供该类的实例（请参阅上面的拖放目标）。
拖放目标突出显示
DropHelper 用于配置拖放目标，以便在用户将内容拖动到目标上时突出显示。DropHelper 用于提供默认样式，但 DropHelper.Options 可让您设置突出显示颜色，以及指定突出显示矩形的圆角半径。
您可以使用 DropHelper.Options.Builder 类来创建 DropHelper.Options 实例并设定配置选项，例如：
Kotlin
val options: DropHelper.Options = DropHelper.Options.Builder()
.setHighlightColor(getColor(R.color.purple_300))
.setHighlightCornerRadiusPx(resources.getDimensionPixelSize(R.dimen.drop_target_corner_radius))
.build()
Java
DropHelper.Options options = new DropHelper.Options.Builder()
.setHighlightColor(getColor(R.color.purple_300))
.setHighlightCornerRadiusPx(getResources().getDimensionPixelSize(R.dimen.drop_target_corner_radius))
.build();
拖放目标中的 EditText 组件
当拖放目标包含可修改的文本字段时，DropHelper 还会控制拖放目标中的焦点。
拖放目标可以是单个视图，也可以是视图层次结构。如果拖放目标视图层次结构包含一个或多个 EditText 组件，您必须为 DropHelper.Options.Builder#addInnerEditTexts(EditText...) 提供一个组件列表，以确保拖放目标突出显示和文本数据处理能够正常进行。
DropHelper 可防止拖放目标视图层次结构中的 EditText 组件在拖动目标相交期间从容器视图窃取焦点。
此外，如果拖放 ClipData 包含文本和 URI 数据，DropHelper 会选择拖放目标中的一个 EditText 组件来处理文本数据。选择时遵循以下优先顺序：
ClipData被放到的EditText- 包含文本光标的
EditText - 向
DropHelper.Options.Builder#addInnerEditTexts(EditText...)调用提供的第一个EditText
如需将 EditText 设为默认的文本数据处理程序，请将 EditText 作为调用 DropHelper.Options.Builder#addInnerEditTexts(EditText...) 时使用的第一个参数进行传递。例如，如果拖放目标可处理图片，但包含可修改的文本字段 T1、T2 和 T3，则请按如下所示将 T2 设为默认值：
Kotlin
val options: DropHelper.Options = DropHelper.Options.Builder()
.addInnerEditTexts(T2, T1, T3)
.build()
Java
DropHelper.Options options = new DropHelper.Options.Builder()
.addInnerEditTexts(T2, T1, T3)
.build();
拖放目标数据处理
DropHelper#configureView() 方法用于接受您为了处理拖放 ClipData 而创建的 OnReceiveContentListener。拖放数据在 ContentInfoCompat 对象中提供给监听器。该对象中存在文本数据；媒体（如图片）以 URI 表示。
当使用 DropHelper#configureView() 配置以下类型的视图时，OnReceiveContentListener 还会处理拖放（如复制和粘贴）以外的用户互动提供给拖放目标的数据：
- 所有视图（如果用户的设备搭载的是 Android 12 或更高版本）
AppCompatEditText（最低 Android 7.0）
MIME 类型、权限和内容验证
DropHelper 的 MIME 类型检查是根据提供拖放数据的应用创建的拖放 ClipDescription 进行的。您应验证 ClipDescription，以确保 MIME 类型已正确设置。
DropHelper 用于请求获取对拖放 ClipData 中包含的内容 URI 的所有访问权限（请参阅 DragAndDropPermissions）。借助这些权限，您可以在处理拖放数据时解析内容 URI。
DropHelper 在解析用户放下的数据中的 URI 时，不会验证 content provider 返回的数据。您应检查这些数据是否为 null，并验证所有已解析数据的正确性。