DropHelper para ação de arrastar e soltar simplificado

A classe DropHelper simplifica a implementação de recursos de arrastar e soltar. Um membro da biblioteca DragAndDrop do Jetpack, o DropHelper, oferece compatibilidade com versões anteriores até o nível 24 da API.

Use o DropHelper para especificar destinos de soltar, personalizar o destaque do destino de soltar e definir como os dados descartados são processados.

Definir origem da ação de arrastar

Para começar, crie DragStartHelper com a visualização de origem de arrastar e OnDragStartListener.

Em OnDragStartListener, modifique o método onDragStart(). Crie um objeto ClipData e ClipData.Item para os dados que estão sendo movidos. Como parte do ClipData, forneça metadados armazenados em um objeto ClipDescription no ClipData. Para uma operação de arrastar e soltar que não representa movimento de dados, use null em vez de um objeto real.

Kotlin

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()

Java

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);
    }
});

Especificar destinos de soltar

Quando um usuário solta uma sombra projetada sobre uma visualização, a visualização precisa ser configurada adequadamente para aceitar os dados e responder corretamente.

DropHelper.configureView() é um método estático e sobrecarregado que permite especificar destinos de soltar. Os parâmetros incluem o seguinte:

Por exemplo, para criar um destino de soltar que aceite imagens, use uma das chamadas de método abaixo:

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);

A segunda chamada omite as opções de configuração do destino de soltar. Nesse caso, a cor de destaque do destino de soltar é definida como a cor secundária (ou de destaque) do tema, o raio do canto de destaque é definido como 16 dp e a lista de componentes EditText está vazia. Consulte a próxima seção para mais informações.

Configurar destinos de soltar

A classe interna DropHelper.Options permite configurar destinos de soltar. Forneça uma instância da classe ao método DropHelper.configureView(Activity, View, String[], Options, OnReceiveContentListener. Consulte a seção anterior para saber mais.

Personalizar o destaque do destino de soltar

O DropHelper configura destinos de soltar para exibir um destaque enquanto os usuários arrastam o conteúdo sobre os destinos. DropHelper oferece um estilo padrão, e DropHelper.Options permite definir a cor do destaque e especificar o raio do canto do retângulo do destaque.

Use a classe DropHelper.Options.Builder para criar uma instância de DropHelper.Options e definir opções de configuração, conforme mostrado no exemplo a seguir:

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();

Processar componentes EditText em destinos de soltar

DropHelper também controla o foco no destino de soltar quando o destino contém campos de texto editáveis.

Os destinos de soltar podem ser uma visualização única ou uma hierarquia de visualização. Se a hierarquia de visualização do destino de soltar contiver um ou mais componentes EditText, forneça uma lista dos componentes para DropHelper.Options.Builder.addInnerEditTexts(EditText...) para garantir que o destaque do destino de soltar e o processamento de dados de texto funcionem corretamente.

DropHelper impede que componentes EditText na hierarquia de visualização do destino de soltar roubem o foco da visualização contida durante interações de arrastar.

Além disso, se o ClipData de arrastar e soltar incluir dados de texto e URI, o DropHelper vai selecionar um dos componentes EditText no destino de soltar para processar os dados de texto. A seleção é baseada na seguinte ordem de precedência:

  1. O EditText em que o ClipData é inserido.
  2. O EditText que contém o cursor de texto (circunflexo).
  3. O primeiro EditText fornecido à chamada para DropHelper.Options.Builder.addInnerEditTexts(EditText...).

Para definir um EditText como o gerenciador de dados de texto padrão, transmita o EditText como o primeiro argumento da chamada para o DropHelper.Options.Builder.addInnerEditTexts(EditText...). Por exemplo, se o destino de soltar processar imagens, mas tiver campos de texto editáveis T1, T2 e T3, torne o T2 o padrão desta maneira:

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();

Processar dados em destinos de soltar

O método DropHelper.configureView() aceita um OnReceiveContentListener criado para processar o ClipData de arrastar e soltar. Os dados de arrastar e soltar são fornecidos ao listener em um objeto ContentInfoCompat. Dados de texto estão presentes no objeto. A mídia, como imagens, é representada por URIs.

O OnReceiveContentListener também processa dados fornecidos ao destino de soltar por interações do usuário que não sejam de arrastar e soltar, como copiar e colar, quando DropHelper.configureView() é usado para configurar estes tipos de visualizações:

  • Todas as visualizações, se o usuário estiver usando o Android 12 ou mais recente.
  • AppCompatEditText, se o usuário estiver executando uma versão do Android anterior à 7.0.

Tipos MIME, permissões e validação de conteúdo

A verificação de tipo MIME por DropHelper é baseada no ClipDescription de arrastar e soltar, que é criado pelo app que fornece os dados de arrastar e soltar. Valide o ClipDescription para garantir que os tipos MIME estejam definidos corretamente.

DropHelper solicita todas as permissões de acesso para URIs de conteúdo contidos no ClipData de arrastar e soltar. Para mais informações, consulte DragAndDropPermissions. As permissões permitem resolver os URIs de conteúdo ao processar os dados de arrastar e soltar.

DropHelper não valida os dados retornados pelos provedores de conteúdo ao resolver URIs nos dados descartados. Verifique se há valores nulos e confira a exatidão dos dados resolvidos.