使用 DropHelper 可簡化拖曳作業

DropHelper 類別可簡化 實作拖曳功能。DropHelper (隸屬於 Jetpack DragAndDrop 資源庫) 提供回溯至 API 級別 24 的相容性。

使用 DropHelper 來指定放置目標、自訂放置目標醒目顯示，以及定義系統如何處理放置的資料。

設定拖曳來源

如要開始使用，請建立DragStartHelper 可讓您變更原始碼檢視畫面 OnDragStartListener。

在OnDragStartListener， 覆寫方法 onDragStart()。建立 ClipData 物件 和 ClipData.Item 物件。做為 ClipData 的一部分， 提供儲存在 ClipDescription 物件 ClipData。對於不代表資料移動的拖曳作業 建議您使用 null 而非實際物件。

DragStartHelper(draggableView)
    { view: View, _: DragStartHelper ->
        val item = ClipData.Item(view.tag as? CharSequence)
        val dragData = ClipData(
            view.tag as? CharSequence,
            arrayOf(ClipDescription.MIMETYPE_TEXT_PLAIN),
            item
        )
        view.startDragAndDrop(
            dragData,
            View.DragShadowBuilder(view),
            null,
            0
        )
    }.attach()

new DragStartHelper(draggableView, new DragStartHelper.OnDragStartListener() {
    @Override
    public void onDragStart(View view, DragStartHelper helper) {
        CharSequence tag = (CharSequence) view.getTag();
        ClipData.Item item = new ClipData.Item(tag);
        ClipData dragData = new ClipData(
          tag, new String[]{ClipDescription.MIMETYPE_TEXT_PLAIN}, item);
        view.startDragAndDrop(
          dragData, new View.DragShadowBuilder(view), null, 0);
    }
});

指定放置目標

當使用者在檢視畫面上釋放投射陰影時，就需要設定該檢視區塊 才能接受資料並正確回應

DropHelper.configureView()敬上 是一種靜態的超載方法，可讓您指定放置目標。結果 參數包括：

• 目前的 Activity：用於 URI 權限。
  • 做為放置目標的 View。
    • MIME 類型 放置目標可接受捨棄的資料。
• 放置目標的設定選項，尤其是 內嵌 EditText 欄位。
• OnReceiveContentListener 處理捨棄的資料。

舉例來說，如要建立可接受圖片的放置目標，請使用下列任一方法呼叫：

configureView(
    myActivity,
    targetView,
    arrayOf("image/*"),
    options,
    onReceiveContentListener)

// or

configureView(
    myActivity,
    targetView,
    arrayOf("image/*"),
    onReceiveContentListener)

DropHelper.configureView(
    myActivity,
    targetView,
    new String[] {"image/*"},
    options,
    onReceiveContentlistener);

// or

DropHelper.configureView(
    myActivity,
    targetView,
    new String[] {"image/*"},
    onReceiveContentlistener);

第二個呼叫會省略放置目標設定選項，這時 放置目標醒目顯示顏色設為主題的次要 (或強調) 顏色 醒目顯示圓角半徑設為 16 dp，EditText 清單 元件為空白。詳情請參閱下節說明。

設定放置目標

DropHelper.Options 內部類別可讓您設定放置目標提供該類別的例項 DropHelper.configureView(Activity, View, String[], Options, OnReceiveContentListener) 方法。詳情請參閱上一節的說明。

自訂放置目標醒目顯示功能

DropHelper 會設定放置目標，在使用者拖曳時顯示醒目顯示 內容就會越過目標DropHelper 提供預設樣式，以及 DropHelper.Options 可讓您設定醒目顯示的顏色和 醒目顯示矩形的圓角半徑。

使用 DropHelper.Options.Builder敬上 建立 DropHelper.Options 執行個體並設定設定選項 如以下範例所示：

val options: DropHelper.Options = DropHelper.Options.Builder()
                                      .setHighlightColor(getColor(R.color.purple_300))
                                      .setHighlightCornerRadiusPx(resources.getDimensionPixelSize(R.dimen.drop_target_corner_radius))
                                      .build()

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 部分元件來處理文字資料。系統會根據 優先順序如下：

1. 捨棄 ClipData 的 EditText。
2. 包含文字遊標 (插入點) 的 EditText。
3. 提供給呼叫的第一個 EditText DropHelper.Options.Builder.addInnerEditTexts(EditText...)。

如要將 EditText 設為預設文字資料處理常式，請將 EditText 做為 呼叫 DropHelper.Options.Builder.addInnerEditTexts(EditText...)。舉例來說 您的放置目標會處理圖片，但包含可編輯的文字欄位 T1、T2、 和 T3，將 T2 設為預設值，如下所示：

val options: DropHelper.Options = DropHelper.Options.Builder()
                                      .addInnerEditTexts(T2, T1, T3)
                                      .build()

DropHelper.Options options = new DropHelper.Options.Builder()
                                     .addInnerEditTexts(T2, T1, T3)
                                     .build();

處理放置目標中的資料

DropHelper.configureView() 方法接受 OnReceiveContentListener 。ClipData拖曳資料 提供的是 ContentInfoCompat 物件。 物件中會顯示文字資料，圖片等媒體是以 URI。

OnReceiveContentListener 也會處理透過下列指標提供給放置目標的資料： 使用者進行互動 (例如複製和放置) 貼上，使用 DropHelper.configureView() 設定下列項目 檢視類型：

• 所有檢視畫面 (如果使用者搭載 Android 12 以上版本)。
• AppCompatEditText、 如果使用者執行的 Android 版本低於 Android 7.0。

MIME 類型、權限和內容驗證

DropHelper 的 MIME 類型檢查是根據拖曳設定 ClipDescription，也就是 。驗證 ClipDescription：確保 MIME 類型設定正確無誤。

DropHelper 要求叢集內包含的內容 URI 的所有存取權限 並直接拖曳 ClipData。若需更多資訊，請參閲 DragAndDropPermissions。 權限可讓您在處理拖曳方式時解析內容 URI 資料。

DropHelper 不會驗證內容供應器傳回的資料， 解析所放置資料中的 URI檢查空值並驗證 所有解析的資料。