Resultados do comando

Anterior: Adicionar comandos de nível superior à sua extensão

Um IInvokableCommand representa um único item acionável na Paleta de Comandos — é o que é acionado quando um usuário seleciona um comando.

Quando o comando é selecionado, o método Invoke é chamado. É aqui que você implementa a lógica para o que sua extensão deve fazer. O método Invoke deve retornar um CommandResult, que informa à Paleta de Comandos como responder após a execução do comando — por exemplo, se deve mostrar uma mensagem, abrir um arquivo ou não fazer nada.

Esta página explica os 7 tipos diferentes de CommandResult que podem ser retornados e o que cada um faz.

Resultado do comando KeepOpen

O resultado do comando KeepOpen não faz nada. Ele deixa a paleta em seu estado atual, com a pilha de páginas e a consulta atuais. Isso pode ser útil para comandos que desejam manter o usuário na Paleta de Comandos, para continuar trabalhando com a página atual.

Ocultar resultado do comando

Este resultado de comando mantém a página atual aberta, mas oculta a Paleta de Comandos. Isso pode ser útil para comandos que desejam tirar o usuário brevemente da Paleta de Comandos, mas depois voltar a esse contexto.

Resultado do comando GoBack

Esse resultado leva o usuário de volta uma página na Paleta de Comandos e mantém a janela visível. Isso é perfeito para páginas de formulário, onde fazer o comando deve levar o usuário de volta ao contexto anterior.

Resultado do comando GoHome

Esse resultado leva o usuário de volta à página principal da Paleta de Comandos. Ele deixará a Paleta visível (a menos que a paleta perca o foco). Considere usar isso para cenários em que você alterou seus comandos de nível superior.

Ignorar resultado do comando

Esse resultado oculta a Paleta de Comandos depois que a ação é executada e a leva de volta à página inicial. Na próxima inicialização, a Paleta de Comandos começará na página principal com uma consulta em branco. Isso é útil para comandos que são ações pontuais ou que não precisam manter a Paleta de Comandos aberta.

Se você não sabe mais o que usar, esse deve ser o seu padrão. O ideal é que os usuários entrem na paleta, encontrem o que precisam e façam isso.

Resultado do comando ShowToast

Esse resultado exibe uma mensagem transitória no nível da área de trabalho para o usuário. Isso é especialmente útil para exibir a confirmação de que uma ação ocorreu quando a paleta será fechada.

Considere o CopyTextCommand nos auxiliares - este comando mostrará uma notificação tipo toast com o texto "Copiado para a área de transferência" e, em seguida, fechará a paleta.

Por padrão, o auxiliar CommandResult.ShowToast(string) terá um resultado de CommandResult.Dismiss. No entanto, você pode, em vez disso, alterar o resultado para qualquer um dos outros resultados, se desejar. Isso permite que você exiba uma notificação do sistema e mantenha a paleta aberta, se desejar.

Confirmar resultado do comando

Esse resultado exibe uma caixa de diálogo de confirmação para o usuário. Se o utilizador confirmar a caixa de diálogo, o PrimaryCommand de ConfirmationArgs será executado.

Isso é útil para comandos que podem ter ações destrutivas ou que precisam confirmar a intenção do usuário.

Exemplo

Abaixo está uma página com um comando para cada tipo de CommandResult:

1. Abrir /Pages/<ExtensionName>Page.cs
2. Substitua GetItems pelo GetItems seguinte:

using Microsoft.CommandPalette.Extensions;
using Microsoft.CommandPalette.Extensions.Toolkit;

internal sealed partial class <ExtensionName>Page : ListPage
{
    public <ExtensionName>Page()
    {
        Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
        Title = "Example command results";
        Name = "Open";
    }

    public override IListItem[] GetItems()
    {
        ConfirmationArgs confirmArgs = new()
        {
            PrimaryCommand = new AnonymousCommand(
                () =>
                {
                    ToastStatusMessage t = new("The dialog was confirmed");
                    t.Show();
                })
            {
                Name = "Confirm",
                Result = CommandResult.KeepOpen(),
            },
            Title = "You can set a title for the dialog",
            Description = "Are you really sure you want to do the thing?",
        };

        return
        [
            new ListItem(new AnonymousCommand(null) { Result = CommandResult.KeepOpen() }) { Title = "Keep the palette open" },
            new ListItem(new AnonymousCommand(null) { Result = CommandResult.Hide() }) { Title = "Hide the palette" },
            new ListItem(new AnonymousCommand(null) { Result = CommandResult.GoBack() }) { Title = "Go back" },
            new ListItem(new AnonymousCommand(null) { Result = CommandResult.GoHome() }) { Title = "Go home" },
            new ListItem(new AnonymousCommand(null) { Result = CommandResult.Dismiss() }) { Title = "Dismiss the palette" },
            new ListItem(new AnonymousCommand(null) { Result = CommandResult.ShowToast("What's up") }) { Title = "Show a toast" },
            new ListItem(new AnonymousCommand(null) { Result = CommandResult.Confirm(confirmArgs) }) { Title = "Confirm something" },
        ];
    }
}

1. Implante sua extensão
2. Na Paleta de Comandos, Reload

Próximo: Exibir conteúdo de marcação

Conteúdo relacionado

• PowerToys Utilitário Paleta de Comandos
• Visão geral da extensibilidade
• Amostras de extensão