Seletor de arquivos

  • Artigo

Procurar amostra. Procurar no exemplo

Este artigo descreve como você pode usar a interface do usuário do aplicativo .NET multiplataforma (.NET MAUI) IFilePicker. Com a interface IFilePicker, você pode solicitar que o usuário escolha um ou mais arquivos no dispositivo.

A implementação padrão da interface IFilePicker está disponível por meio da propriedade FilePicker.Default. A interface IFilePicker e a classe FilePicker estão contidas no namespace Microsoft.Maui.Storage.

Introdução

Para acessar a funcionalidade FilePicker, a configuração específica da plataforma a seguir é necessária.

Se o app for direcionado ao Android 12 ou versões anteriores, solicite a permissão READ_EXTERNAL_STORAGE. Se o app for destinado ao Android 13 ou versões mais recentes e precisar de acesso a arquivos criados por outros apps, solicite uma ou mais das seguintes permissões granulares em vez da permissão READ_EXTERNAL_STORAGE:

  • READ_MEDIA_IMAGES
  • READ_MEDIA_VIDEO
  • READ_MEDIA_AUDIO

Essas permissões podem ser adicionadas das seguintes maneiras:

  • Adicione a permissão baseada em assembly:

    Abra o arquivo Platforms/Android/MainApplication.cs e adicione os seguintes atributos de assembly após as diretivas using:

    [assembly: UsesPermission(Android.Manifest.Permission.ReadExternalStorage, MaxSdkVersion = 32)]
[assembly: UsesPermission(Android.Manifest.Permission.ReadMediaAudio)]
[assembly: UsesPermission(Android.Manifest.Permission.ReadMediaImages)]
[assembly: UsesPermission(Android.Manifest.Permission.ReadMediaVideo)]

    - ou -

  • Atualize o manifesto do Android:

    Abra o arquivo Platforms/Android/AndroidManifest.xml e adicione o seguinte no nó manifest:

    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
<!-- Required only if your app needs to access images or photos that other apps created -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<!-- Required only if your app needs to access videos that other apps created -->
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<!-- Required only if your app needs to access audio files that other apps created -->
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

    - ou -

  • Atualize o Manifesto do Android no editor de manifesto:

    No Visual Studio, clique duas vezes no arquivo Platforms/Android/AndroidManifest.xml para abrir o editor de manifesto do Android. Em seguida, em Permissões necessárias, verifique as permissões listadas acima. Isso atualizará automaticamente o arquivo AndroidManifest.xml.

Importante

Todos os métodos devem ser chamados no thread da IU porque as verificações de permissão e as solicitações são tratadas automaticamente pelo .NET MAUI.

Escolher um arquivo

O método PickAsync solicita que o usuário escolha um arquivo do dispositivo. Use o tipo PickOptions para especificar os tipos de título e arquivo permitidos com o seletor. O exemplo a seguir demonstra a abertura do seletor e o processamento da imagem selecionada:

public async Task<FileResult> PickAndShow(PickOptions options)
{
    try
    {
        var result = await FilePicker.Default.PickAsync(options);
        if (result != null)
        {
            if (result.FileName.EndsWith("jpg", StringComparison.OrdinalIgnoreCase) ||
                result.FileName.EndsWith("png", StringComparison.OrdinalIgnoreCase))
            {
                using var stream = await result.OpenReadAsync();
                var image = ImageSource.FromStream(() => stream);
            }
        }

        return result;
    }
    catch (Exception ex)
    {
        // The user canceled or something went wrong
    }

    return null;
}

Os tipos de arquivo padrão são fornecidos com FilePickerFileType.Images, FilePickerFileType.Png e FilePickerFilerType.Videos. Você pode especificar tipos de arquivo personalizados por plataforma criando uma instância da classe FilePickerFileType. O construtor dessa classe usa um dicionário que é codificado pelo tipo DevicePlatform para identificar a plataforma. O valor da chave do dicionário é uma coleção de cadeias de caracteres que representa os tipos de arquivo. Por exemplo, veja como você especificaria tipos específicos de arquivos de quadrinhos:

var customFileType = new FilePickerFileType(
                new Dictionary<DevicePlatform, IEnumerable<string>>
                {
                    { DevicePlatform.iOS, new[] { "public.my.comic.extension" } }, // UTType values
                    { DevicePlatform.Android, new[] { "application/comics" } }, // MIME type
                    { DevicePlatform.WinUI, new[] { ".cbr", ".cbz" } }, // file extension
                    { DevicePlatform.Tizen, new[] { "*/*" } },
                    { DevicePlatform.macOS, new[] { "cbr", "cbz" } }, // UTType values
                });

PickOptions options = new()
{
    PickerTitle = "Please select a comic file",
    FileTypes = customFileType,
};

A pesquisa de arquivos com base no tipo de arquivo pode ser diferente de uma plataforma para outra. Para mais informações, consulte Diferenças entre plataformas.

Selecionar vários arquivos

Se você quiser que o usuário escolha vários arquivos, chame o método FilePicker.PickMultipleAsync. Esse método também usa um parâmetro PickOptions para especificar informações adicionais. Os resultados são os mesmos que PickAsync, mas em vez do tipo FileResult retornado, um tipo IEnumerable<FileResult> é retornado com todos os arquivos selecionados.

Dica

A propriedade FullPath nem sempre retorna o caminho físico para o arquivo. Use o método OpenReadAsync para acessar o arquivo.

Diferenças de plataforma

Esta seção descreve as diferenças específicas de plataforma com o seletor de arquivos.

O PickOptions.PickerTitle é exibido no prompt inicial para o usuário, mas não na própria caixa de diálogo do seletor.

Ao filtrar arquivos por tipo, use o tipo MIME do arquivo. Para obter uma lista de tipos MIME, consulte Mozilla – Tipos MIME comuns.