O que é o Android Photo Picker e que acesso concede

Android Photo Picker é uma interface integrada que apresenta uma biblioteca multimédia para que uma pessoa escolha as fotografias ou os vídeos que pretende partilhar com uma aplicação. O Android descreve este mecanismo como uma forma de conceder acesso aos ficheiros selecionados, em vez de à biblioteca inteira. Pode, por exemplo, ser usado para anexar uma imagem a uma mensagem ou escolher um vídeo para uma publicação.

A distinção essencial está entre entregar elementos específicos e autorizar o acesso geral à biblioteca. O acesso concedido pelo Photo Picker diz respeito aos conteúdos selecionados no seletor; não descreve outras permissões que a aplicação possa ter separadamente. Por isso, o fluxo do seletor não deve ser confundido com um pedido de acesso amplo ao armazenamento.

Nos contratos de resultado de atividade documentados pelo Android, a aplicação recebe um ou mais URI associados aos elementos escolhidos. O acesso a esses ficheiros não deve ser considerado necessariamente permanente: o Android indica que, por predefinição, se mantém até o dispositivo ser reiniciado ou a aplicação ser parada. Para uma tarefa prolongada, como carregar um ficheiro em segundo plano, a aplicação pode preservar o acesso com takePersistableUriPermission() quando necessário.

Como abrir o seletor a partir de uma aplicação

O Android documenta contratos Jetpack Activity para iniciar o Photo Picker. PickVisualMedia permite escolher uma fotografia ou um vídeo; PickMultipleVisualMedia permite selecionar vários elementos. A recomendação do Android para simplificar esta integração é incluir a versão 1.7.0 ou posterior da biblioteca androidx.activity; isso não significa que seja a única forma de usar o seletor.

O fluxo habitual com estes contratos consiste em iniciar o seletor, deixar a pessoa escolher conteúdo e processar o resultado recebido. Se o seletor for fechado sem a escolha de um conteúdo, os exemplos do Android mostram que o resultado pode ser nulo numa seleção individual ou uma lista vazia numa seleção múltipla. A aplicação deve prever ambos os casos e não presumir que será sempre devolvido um ficheiro.

Se o Photo Picker não estiver disponível num dispositivo, a biblioteca invoca automaticamente a ação ACTION_OPEN_DOCUMENT como alternativa. O Android indica que esta ação é compatível com dispositivos a partir do Android 4.4, nível de API 19. A alternativa não garante uma interface idêntica em todos os dispositivos: trata-se de um fluxo diferente de seleção de documentos.

Photo Picker e Selected Photos Access: dois mecanismos diferentes

Selected Photos Access é o modelo de acesso parcial do Android 14 para aplicações que pedem permissões de leitura de fotografias ou vídeos. Permite que a pessoa autorize conteúdos específicos em vez de todos os conteúdos de um determinado tipo. De acordo com o Android, esta alteração aplica-se quando a aplicação tem como destino o Android 14, nível de API 34, ou posterior.

O Photo Picker é diferente: permite selecionar conteúdos para partilhar através da sua interface, sem que esse fluxo exija permissões de armazenamento. O Android recomenda o seletor às aplicações que ainda não o utilizam e precisam de selecionar imagens ou vídeos. Assim, usar o Photo Picker não significa que a aplicação esteja a implementar o modelo de permissões de uma galeria própria.

A permissão READ_MEDIA_VISUAL_USER_SELECTED é relevante para aplicações que mantêm o seu próprio seletor de galeria baseado em permissões e precisam de gerir o acesso parcial e a nova seleção. O Android recomenda adaptar essa implementação quando é necessário controlar a galeria. Se uma aplicação mantiver o seu próprio seletor com permissões sem incluir a nova permissão, o sistema poderá executá-la em modo de compatibilidade; esse comportamento diz respeito a esse caso, e não a todas as aplicações que não usam o Photo Picker.

Que abordagem escolher para cada função

A escolha depende da tarefa. Para receber uma ou várias imagens ou vídeos escolhidos por uma pessoa, o Photo Picker oferece um fluxo limitado. Uma galeria integrada pode ser adequada quando a aplicação precisa de controlar a apresentação ou a consulta da biblioteca; em contrapartida, tem de gerir as permissões e refletir alterações no acesso autorizado.

Nos contratos Jetpack Activity descritos pelo Android, o resultado inclui os URI dos elementos selecionados. Numa galeria própria com permissões, a aplicação pode consultar o MediaStore dentro do âmbito concedido. O acesso parcial não equivale ao acesso total: a interface e os resultados devem corresponder às permissões autorizadas pela pessoa.

Comparação prática

Abordagem O que a aplicação recebe O que tem de gerir
Photo Picker com contratos Jetpack Activity URI dos conteúdos selecionados nesse fluxo Resultado vazio ou nulo, processamento dos URI e duração do acesso
Galeria própria com permissões Consulta de conteúdos dentro do âmbito autorizado, que pode ser parcial ou total Pedido e verificação de permissões, atualização de resultados e nova seleção

A tabela resume a diferença funcional, não todos os requisitos de implementação. Para decidir, convém começar pelas necessidades da funcionalidade: se bastar que o utilizador forneça determinados ficheiros, o seletor costuma ser adequado; se for necessária uma galeria integrada na aplicação, também é preciso planear a gestão das permissões.

Conteúdo remoto e seleção no dispositivo

O Photo Picker pode permitir selecionar fotografias e vídeos armazenados remotamente quando existem no dispositivo fornecedores de conteúdos multimédia na nuvem elegíveis. A disponibilidade depende do fornecedor: o Android não afirma que todos os serviços na nuvem aparecem em todos os seletores.

O Android indica também que a ferramenta é atualizada automaticamente e pode disponibilizar funcionalidades alargadas sem alterações ao código da aplicação. Isto não garante que um determinado fornecedor ou ficheiro remoto esteja disponível num dispositivo específico. A pessoa pode abrir o seletor e consultar os conteúdos que lhe são apresentados.

O que verificar ao partilhar ou desenvolver

Quando são selecionados vários conteúdos, o guia de ajuda do Android descreve uma pré-visualização dos elementos escolhidos e a possibilidade de remover ficheiros antes de os adicionar. Também avisa que o máximo selecionável pode chegar a 100 fotografias ou vídeos, ou ser inferior consoante a configuração da aplicação. É possível rever a seleção antes de concluir o fluxo descrito nesse guia.

Quem desenvolve uma aplicação deve escolher entre o seletor e uma galeria própria de acordo com a funcionalidade e tratar cuidadosamente os resultados do seletor. Se uma tarefa em segundo plano precisar de continuar a aceder a um URI, deve considerar a duração predefinida da permissão e pedir persistência quando for apropriado. Não se deve presumir que o acesso a um elemento continuará indefinidamente.

Para uma galeria própria no Android 14, a aplicação deve verificar o estado real das permissões e permitir que a pessoa altere os conteúdos autorizados. O Android avisa que o acesso parcial pode mudar e recomenda atualizar os resultados quando a aplicação regressa ao primeiro plano. A interface deve refletir o acesso atual, e não uma autorização presumida ou guardada como permanente.