Creare richieste di selezione file o directory

  • Articolo

Le richieste di file o directory sono un semplice meccanismo dell'interfaccia utente per richiedere all'utente di selezionare un file o un percorso di directory. La richiesta all'utente crea la finestra di dialogo file dal sistema operativo nativo con opzioni di dialogo personalizzate per adattarsi allo scenario specifico dell'utente.

Usare richieste di selezione file o directory

Questa guida illustra gli scenari seguenti per l'uso dei prompt di selezione file o directory:

Chiedere all'utente di selezionare un singolo file da aprire

Per creare un prompt di apertura file, chiamare il ShowOpenFileDialogAsync metodo dall'oggetto ShellExtensibility .

ShellExtensibility.ShowOpenFileDialogAsync()

Il metodo ShowOpenFileDialogAsync accetta due parametri:

Parametro Type Obbligatorio Descrizione
opzioni FileDialogOptions Sì Definisce le opzioni di richiesta di selezione file per personalizzare la finestra di dialogo.
cancellationToken CancellationToken Sì Oggetto CancellationToken per l'operazione asincrona. Quando viene attivato, il prompt viene chiuso forzatamente.

ShowOpenFileDialogAsync restituisce null se l'utente chiude o annulla la finestra di dialogo.

Esempio

Il codice seguente all'interno di mostra Command una richiesta di file con le opzioni predefinite della finestra di dialogo.

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

Chiedere all'utente di selezionare uno o più file da aprire

In alcuni casi, è utile consentire agli utenti di selezionare più file alla volta, operazione che può essere eseguita con il ShowOpenMultipleFilesDialogAsync metodo .

ShellExtensibility.ShowOpenMultipleFilesDialogAsync()

Il metodo ShowOpenMultipleFilesDialogAsync accetta due parametri:

Parametro Type Obbligatorio Descrizione
opzioni FileDialogOptions Sì Definisce le opzioni di richiesta di selezione file per personalizzare la finestra di dialogo.
cancellationToken CancellationToken Sì Oggetto CancellationToken per l'operazione asincrona. Quando viene attivato, il prompt viene chiuso forzatamente.

ShowOpenMultipleFilesDialogAsync restituisce null se l'utente chiude o annulla la finestra di dialogo.

Esempio

Il codice seguente all'interno di mostra Command una richiesta di file con le opzioni predefinite della finestra di dialogo.

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

Chiedere all'utente di selezionare un file con nome

Richiedendo all'utente un nome file su Salva con nome, è possibile specificare un nome di file personalizzato.

ShellExtensibility.ShowSaveAsFileDialogAsync()

Il metodo ShowSaveAsFileDialogAsync accetta due parametri:

Parametro Type Obbligatorio Descrizione
opzioni FileDialogOptions Sì Definisce le opzioni di richiesta di selezione file per personalizzare la finestra di dialogo.
cancellationToken CancellationToken Sì Oggetto CancellationToken per l'operazione asincrona. Quando viene attivato, il prompt viene chiuso forzatamente.

ShowSaveAsFileDialogAsync restituisce null se l'utente chiude o annulla la finestra di dialogo.

Esempio

Il codice seguente all'interno di mostra Command una richiesta di file con le opzioni predefinite della finestra di dialogo.

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

Chiedere all'utente di selezionare una directory da aprire

Per creare un prompt di apertura file, chiamare il ShowOpenFolderDialogAsync metodo dall'oggetto ShellExtensibility .

ShellExtensibility.ShowOpenFolderDialogAsync()

Il metodo ShowOpenFolderDialogAsync accetta due parametri:

Parametro Type Obbligatorio Descrizione
opzioni FolderDialogOptions Sì Definisce le opzioni di richiesta di selezione file per personalizzare la finestra di dialogo.
cancellationToken CancellationToken Sì Oggetto CancellationToken per l'operazione asincrona. Quando viene attivato, il prompt viene chiuso forzatamente.

ShowOpenFolderDialogAsync restituisce null se l'utente chiude o annulla la finestra di dialogo.

Esempio

Il codice seguente all'interno di mostra Command una richiesta di file con le opzioni predefinite della finestra di dialogo.

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

Usare le opzioni per personalizzare le richieste di file o directory

I FileDialogOptionstipi , DialogFilterse FolderDialogOptions possono essere usati per personalizzare le richieste:

FileDialogOptions

Proprietà Type Obbligatorio Descrizione Esempio
title string No Titolo del dialogo. Se il titolo è una stringa vuota, il sistema usa un titolo predefinito, ovvero "Salva con nome" o "Apri". L'impostazione predefinita è string.Empty "Apri un file"
initialFileName string No Nome del file nella casella di input della finestra di dialogo. Per la finestra di dialogo apri file, il nome file deve esistere o la finestra di dialogo restituisce un errore. Se viene passato un nome file non valido, viene usato il valore predefinito. Il valore predefinito è string.Empty. "filename.ext"
filtri DialogFilters No Filtri utilizzati per la finestra di dialogo. Vedere Esempi di richieste con opzioni personalizzate

DialogFilters

Termine Type Obbligatorio Descrizione Esempio
Filtri IReadOnlyCollection<DialogFilter> Sì Filtri per la selezione o il salvataggio di un file. Vedere Esempi di richieste con opzioni personalizzate
DefaultFilterIndex int No Consente di impostare l'indice di filtro predefinito del filtro selezionato per impostazione predefinita. Il valore predefinito è 0. L'indice minimo è 0 e il valore massimo è .number of filters - 1

FolderDialogOptions

Proprietà Type Obbligatorio Descrizione Esempio
title string No Titolo del dialogo. Se il titolo è una stringa vuota, il sistema usa un titolo predefinito, ovvero "Salva con nome" o "Apri". Il valore predefinito è string.Empty. "Apri un file"
initialDirectory string No La directory in cui deve essere aperta la finestra di dialogo, che deve essere un percorso assoluto. Se initialDirectory è una stringa vuota, per impostazione predefinita la directory iniziale corrisponde all'ultima directory aperta. Se non esiste alcuna directory aperta in precedenza, per impostazione predefinita la directory iniziale sarà la cartella radice. Se si specifica un oggetto initialDirectory, viene passato un flag alla finestra di dialogo per aprire la directory specificata anziché l'ultima directory aperta. Se viene passata una directory non valida, viene usata l'impostazione predefinita. Il valore predefinito è string.Empty. "path/to/folder"

Esempi di richieste con opzioni personalizzate

Richiesta selezione file

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

Richiesta di selezione directory

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

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

Passaggi successivi

Vedere quindi FilePickerSample.