Adicionando comandos à sua extensão

Anterior: criando uma extensão. Começaremos com o projeto criado nesse artigo.

Agora que você criou sua extensão, é hora de adicionar comandos a ela.

Adicionar comandos

Podemos começar navegando até o /Pages/<ExtensionName>Page.cs arquivo. Esse arquivo é o ListPage que será exibido quando o usuário selecionar sua extensão. Lá, você deverá ver:

public <ExtensionName>Page()
{
    Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
    Title = "My sample extension";
    Name = "Open";
}
public override IListItem[] GetItems()
{
    return [
        new ListItem(new NoOpCommand()) { Title = "TODO: Implement your extension here" }
    ];
}

Aqui você pode ver que definimos o ícone para a página, o título e o nome mostrado no nível superior quando você tiver o comando selecionado. O GetItems método é onde você retornará a lista de comandos que deseja mostrar nesta página. No momento, ele está apenas retornando um único comando que não faz nada. Em vez disso, vamos tentar fazer com que esse comando abra esta página no navegador da Web padrão do usuário.

1. Atualize GetItems para o seguinte:

public override IListItem[] GetItems()
{
    var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/adding-commands");
    return [
        new ListItem(command)
        {
            Title = "Open the Command Palette documentation",
        }
    ];
}

Para atualizar a extensão na Paleta de Comandos, você precisa:

1. Implantar sua extensão
2. Na Paleta de Comandos, digite o comando "recarregar" para atualizar as extensões na paleta

1. Navegue até sua extensão e pressione Enter
2. Pressione enter em Open the Command Palette documentation
3. Você deve ver que o comando abre a documentação da Paleta de Comandos

O OpenUrlCommand é um auxiliar para abrir uma URL no navegador da Web padrão do usuário.

Extensão de Debug

Ao criar sua extensão, você provavelmente desejará depurá-la.

1. Adicione uma mensagem de depuração à GetItems função.

    public override IListItem[] GetItems()
    {
        var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/adding-commands");
    
+       Debug.Write("Debug message from GetItems");
    
        return [
            new ListItem(command)
            {
                Title = "Open the Command Palette documentation",
            }
        ];
    }

1. Implantar sua extensão
2. Confirme se você está na configuração de Depuração

1. Execute o aplicativo em modo de depuração pressionando o botão verde "Iniciar" ▶️ ou pressione F5
2. Verifique se a janela de saída está definida para mostrar Debug (Ctrl + Alt + O)

1. Na Paleta de Comandos, execute reload
2. Vá para sua extensão e selecione Open the Command Palette documentation.
3. Na janela de saída do Visual Studio, você deverá ver Debug message from GetItems

Comando InvokableCommand

Vamos continuar criando um novo comando, que mostra um MessageBox. Para fazer isso, precisamos criar uma nova classe que implemente InvokableCommand.

1. No Visual Studio, adicione um novo arquivo de classe ao diretório Pages
   • Atalho de Teclado: Pressione Ctrl + Shift + A
   • Ou, no Gerenciador de Soluções, vá para o Project > Add New Item...
2. Na caixa de diálogo Adicionar Novo Item:
   1. Selecione Classe na lista.
   2. Nomeie seu arquivo de classe: ShowMessageCommand.cs
   3. Clique em Adicionar.
3. Substitua o código de classe padrão por:

using System.Runtime.InteropServices;

namespace <ExtensionName>;

internal sealed partial class ShowMessageCommand : InvokableCommand
{
    public override string Name => "Show message";
    public override IconInfo Icon => new("\uE8A7");

    public override CommandResult Invoke()
    {
        // 0x00001000 is MB_SYSTEMMODAL, which will display the message box on top of other windows.
        _ = MessageBox(0, "I came from the Command Palette", "What's up?", 0x00001000);
        return CommandResult.KeepOpen();
    }


    [DllImport("user32.dll", CharSet = CharSet.Unicode)]
    public static extern int MessageBox(IntPtr hWnd, string text, string caption, uint type);
}

Agora podemos adicionar esse comando à lista de comandos no <ExtensionName>Page.cs arquivo:

1. No <ExtensionName>.cs, atualize o GetItems:

public override IListItem[] GetItems()
{
    var command = new OpenUrlCommand("https://learn.microsoft.com/windows/powertoys/command-palette/creating-an-extension");
    var showMessageCommand = new ShowMessageCommand();
    return [
        new ListItem(command)
        {
            Title = "Open the Command Palette documentation",
        },
        new ListItem(showMessageCommand),
    ];
}

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

E presto - um comando para mostrar uma caixa de mensagem!

Tipos de páginas

Até agora, só trabalhamos com comandos que "fazem alguma coisa". No entanto, você também pode adicionar comandos que mostram páginas adicionais na Paleta de Comandos. Há dois tipos de "Comandos" na Paleta:

• InvokableCommand - Estes são comandos que fazem algo
• IPage - Estes são comandos que mostram algo

Como as implementações IPage são ICommand, você pode usá-las em qualquer lugar onde possa usar comandos. Isso significa que você pode adicioná-los à lista de nível superior de comandos ou a uma lista de comandos em uma página, ao menu de contexto em um item etc.

Há dois tipos diferentes de páginas que você pode mostrar:

• ListPage – Esta é uma página que mostra uma lista de comandos. É com isso que temos trabalhado até agora.

• ContentPage – Esta é uma página que mostra conteúdo avançado para o usuário. Isso permite especificar conteúdo abstrato e permitir que a Paleta de Comandos se preocupe em renderizar o conteúdo em uma experiência nativa. Há dois tipos diferentes de conteúdo com suporte até agora:
  • Conteúdo de Markdown – esse é o conteúdo escrito em Markdown e é renderizado na Paleta de Comandos. Consulte MarkdownContent para obter detalhes.

• Conteúdo do formulário – esse é o conteúdo que mostra um formulário para o usuário e retorna os resultados desse formulário para a extensão. Eles são alimentados por Cartões Adaptáveis Isso é útil para obter a entrada do usuário ou exibir layouts de informações mais complexos. Consulte FormContent para obter detalhes.

Adicionar mais comandos

Comece adicionando uma nova página que mostra uma lista de comandos. Crie uma nova classe que implemente ListPage.

1. Pages Na pasta, crie uma nova classe chamadaMySecondPage
2. Atualize o código para:

using Microsoft.CommandPalette.Extensions.Toolkit;
using System.Linq;

namespace <ExtensionName>;

internal sealed partial class MySecondPage : ListPage
{
    public MySecondPage()
    {
        Icon = new("\uF147"); // Dial2
        Title = "My second page";
        Name = "Open";
    }

    public override IListItem[] GetItems()
    {
        // Return 100 CopyText commands
        return Enumerable
            .Range(0, 100)
            .Select(i => new ListItem(new CopyTextCommand($"{i}")) 
            {
                Title = $"Copy text {i}" 
            }).ToArray();
    }
}

1.Atualize a <ExtensionName>Page.cs página para incluir esta nova página:

    public override IListItem[] GetItems()
    {
        OpenUrlCommand command = new("https://learn.microsoft.com/windows/powertoys/command-palette/creating-an-extension");
        return [
            new ListItem(command)
            {
                Title = "Open the Command Palette documentation",
            },
            new ListItem(new ShowMessageCommand()),
+           new ListItem(new MySecondPage()) { Title = "My second page", Subtitle = "A second page of commands" },
        ];
    }

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

Agora você poderá ver uma nova página em sua extensão que mostra cem comandos para copiar um número para a área de transferência.

Avançar: atualizar uma lista de comandos

Conteúdo relacionado

• PowerToys Utilitário paleta de comandos
• Visão geral da extensibilidade
• Exemplos de extensão