Criar prompts do seletor de arquivos ou diretórios

  • Artigo

Os prompts de arquivo ou diretório são um mecanismo simples de interface do usuário para solicitar que o usuário selecione um caminho de arquivo ou diretório. Solicitar ao usuário com um prompt cria a caixa de diálogo de arquivo do sistema operacional nativo com opções de diálogo personalizadas para se ajustar ao cenário específico do usuário.

Trabalhar com prompts do seletor de arquivos ou diretórios

Este guia aborda os seguintes cenários para trabalhar com os prompts de seleção de arquivos ou diretórios:

Solicitar que o usuário selecione um único arquivo para abrir

Para criar um prompt de abertura de arquivo, chame o método ShowOpenFileDialogAsync do objeto ShellExtensibility.

ShellExtensibility.ShowOpenFileDialogAsync()

O método ShowOpenFileDialogAsync usa dois parâmetros:

Parâmetro Type Obrigatória Descrição
opções FileDialogOptions Yes Define as opções de prompt do seletor de arquivos para personalizar a caixa de diálogo.
cancellationToken CancellationToken Yes O CancellationToken para a operação assíncrona. Quando acionado, o prompt é fechado à força.

ShowOpenFileDialogAsync retornará null se o usuário fechar ou cancelar a caixa de diálogo.

Exemplo

O código a seguir dentro de um Command mostra um prompt de arquivo com opções de caixa de diálogo padrão.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    FileDialogOptions options = new();
    string? filePath = await this.Extensibility.Shell().ShowOpenFileDialogAsync(options, cancellationToken);
}

Solicitar que o usuário selecione um ou mais arquivos para abrir

Em alguns casos, é útil permitir que os usuários selecionem mais de um arquivo por vez, o que pode ser feito com o método ShowOpenMultipleFilesDialogAsync.

ShellExtensibility.ShowOpenMultipleFilesDialogAsync()

O método ShowOpenMultipleFilesDialogAsync usa dois parâmetros:

Parâmetro Type Obrigatória Descrição
opções FileDialogOptions Yes Define as opções de prompt do seletor de arquivos para personalizar a caixa de diálogo.
cancellationToken CancellationToken Yes O CancellationToken para a operação assíncrona. Quando acionado, o prompt é fechado à força.

ShowOpenMultipleFilesDialogAsync retornará null se o usuário fechar ou cancelar a caixa de diálogo.

Exemplo

O código a seguir dentro de um Command mostra um prompt de arquivo com opções de caixa de diálogo padrão.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    FileDialogOptions options = new();
    IReadOnlyList<string>? filePath = await this.Extensibility.Shell().ShowOpenMultipleFilesDialogAsync(options, cancellationToken);
}

Solicitar que o usuário selecione um arquivo para Salvar como

Solicitar ao usuário um nome de arquivo para Salvar como permite que ele especifique um nome de arquivo personalizado.

ShellExtensibility.ShowSaveAsFileDialogAsync()

O método ShowSaveAsFileDialogAsync usa dois parâmetros:

Parâmetro Type Obrigatória Descrição
opções FileDialogOptions Yes Define as opções de prompt do seletor de arquivos para personalizar a caixa de diálogo.
cancellationToken CancellationToken Yes O CancellationToken para a operação assíncrona. Quando acionado, o prompt é fechado à força.

ShowSaveAsFileDialogAsync retornará null se o usuário fechar ou cancelar a caixa de diálogo.

Exemplo

O código a seguir dentro de um Command mostra um prompt de arquivo com opções de caixa de diálogo padrão.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    FileDialogOptions options = new();
    string? filePath = await this.Extensibility.Shell().ShowSaveAsFileDialogAsync(options, cancellationToken);
}

Solicitar que o usuário selecione um diretório para abrir

Para criar um prompt de abertura de arquivo, chame o método ShowOpenFolderDialogAsync do objeto ShellExtensibility.

ShellExtensibility.ShowOpenFolderDialogAsync()

O método ShowOpenFolderDialogAsync usa dois parâmetros:

Parâmetro Type Obrigatória Descrição
opções FolderDialogOptions Yes Define as opções de prompt do seletor de arquivos para personalizar a caixa de diálogo.
cancellationToken CancellationToken Yes O CancellationToken para a operação assíncrona. Quando acionado, o prompt é fechado à força.

ShowOpenFolderDialogAsync retornará null se o usuário fechar ou cancelar a caixa de diálogo.

Exemplo

O código a seguir dentro de um Command mostra um prompt de arquivo com opções de caixa de diálogo padrão.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
{
    FolderDialogOptions options = new();
    string? folderPath = await this.Extensibility.Shell().ShowOpenFolderDialogAsync(options, cancellationToken);
}

Usar opções para personalizar prompts de arquivo ou diretório

Os tipos FileDialogOptions, DialogFilters e FolderDialogOptions podem ser usados para personalizar seus prompts:

FileDialogOptions

Propriedade Tipo Obrigatório Descrição Amostra
title string Não O título da caixa de diálogo. Se o título for uma sequência vazia, o sistema usará um título padrão, que é "Salvar como" ou "Abrir". O padrão é string.Empty "Abra um arquivo"
initialFileName string Não O nome do arquivo na caixa de entrada da caixa de diálogo. Para a caixa de diálogo de arquivo aberta, o nome do arquivo deverá existir. Caso contrário, a caixa de diálogo retornará um erro. Se um nome de arquivo inválido for passado, usaremos o padrão. O padrão é string.Empty. "filename.ext"
filters DialogFilters Não Os filtros usados para a caixa de diálogo. Consulte Exemplos de prompts com opções personalizadas

DialogFilters

Termo Tipo Obrigatório Descrição Exemplo
Filtros IReadOnlyCollection<DialogFilter> Yes Os filtros para selecionar ou salvar um arquivo. Consulte Exemplos de prompts com opções personalizadas
DefaultFilterIndex int Não Usado para definir o índice de filtro padrão do filtro selecionado por padrão. O padrão é 0. O índice mínimo é 0 e o máximo é number of filters - 1.

FolderDialogOptions

Propriedade Tipo Obrigatório Descrição Amostra
title string Não O título da caixa de diálogo. Se o título for uma sequência vazia, o sistema usará um título padrão, que é "Salvar como" ou "Abrir". O padrão é string.Empty. "Abra um arquivo"
initialDirectory string Não O diretório que a caixa de diálogo deve ter aberto, que deve ser um caminho absoluto. Se o initialDirectory for uma sequência vazia, o diretório inicial assumirá como padrão o último diretório aberto. Se não houver nenhum diretório aberto anteriormente, o diretório inicial será padrão para a pasta raiz. Se um initialDirectory for especificado, passaremos um sinalizador para a caixa de diálogo para abrir no diretório especificado em vez do último diretório aberto. Se um diretório inválido for passado, o diretório padrão será usado. O padrão é string.Empty. "path/to/folder"

Exemplos de prompts com opções personalizadas

Prompt do seletor de arquivos

DialogFilter[] filters = new DialogFilter[]
{
    new DialogFilter("Word Files", ".doc", ".docx"),
    new DialogFilter("Excel Files", ".xls", ".xlsx"),
    new DialogFilter("All Files", ".*"),
};

FileDialogOptions options = new FileDialogOptions()
{
    Title = "Choose a File To Open".
    InitialDirectory = "absolute/path/to/file",
    InitialFileName = "file.txt",
    Filters = new DialogFilters(filters)
    {
        DefaultFilterIndex = 1,
    },
};

string? filePath = await Extensibilty.Shell().ShowOpenFileDialogAsync(options, cancellationToken);

Prompts do seletor de diretórios

FolderDialogOptions options = new FolderDialogOptions()
{
    Title = "Choose a Folder",
    InitialDirectory = "absolute/path/to/folder"
};

string? folderPath = await Extensibilty.Shell().ShowOpenFolderDialogAsync(options, cancellationToken);

Próximas etapas

Em seguida, consulte o FilePickerSample.