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:
- O
Activity
atual, usado para permissões de URI.- Um
View
que serve como destino de soltar.- Os tipos MIME dos dados soltos que o destino de soltar pode aceitar.
- Um
- Opções de configuração do destino de soltar, principalmente uma lista de
campos
EditText
incorporados. - Um
OnReceiveContentListener
para processar dados descartados.
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:
- O
EditText
em que oClipData
é inserido. - O
EditText
que contém o cursor de texto (circunflexo). - O primeiro
EditText
fornecido à chamada paraDropHelper.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 o 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.