Dodawanie poleceń do rozszerzenia

Poprzedni: Tworzenie rozszerzenia. Zaczniemy od projektu utworzonego w tym artykule.

Teraz, po utworzeniu rozszerzenia, nadszedł czas, aby dodać do niego polecenia.

Dodawanie poleceń

Możemy zacząć od nawigowania do /Pages/<ExtensionName>Page.cs pliku. Ten plik to ListPage, który będzie wyświetlany, gdy użytkownik wybierze rozszerzenie. W tym miejscu powinny zostać wyświetlone następujące informacje:

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" }
    ];
}

W tym miejscu widać, że ustawiliśmy ikonę strony, tytułu i nazwy wyświetlanej na najwyższym poziomie po wybraniu polecenia. Metoda GetItems to miejsce, w którym zostanie zwrócona lista poleceń, które mają być wyświetlane na tej stronie. W tej chwili po prostu zwraca pojedyncze polecenie, które nic nie robi. Zamiast tego spróbujmy otworzyć tę stronę w domyślnej przeglądarce internetowej użytkownika.

1. Zaktualizuj GetItems do następujących elementów:

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",
        }
    ];
}

Aby zaktualizować rozszerzenie w palecie poleceń, należy wykonać następujące kroki:

1. Wdrażanie rozszerzenia
2. W palecie poleceń wpisz polecenie "reload", aby odświeżyć rozszerzenia na palecie

1. Przewiń w dół do rozszerzenia i naciśnij Enter
2. Naciśnij enter na Open the Command Palette documentation
3. Powinieneś zobaczyć, że polecenie otwiera dokumentację Palety Poleceń.

OpenUrlCommand to pomocnik umożliwiający otwarcie adresu URL w domyślnej przeglądarce internetowej użytkownika.

Rozszerzenie debugowania

Podczas kompilowania rozszerzenia najprawdopodobniej zechcesz go debugować.

1. Dodaj komunikat debugowania do GetItems funkcji.

    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. Wdrażanie rozszerzenia
2. Upewnij się, że jesteś w konfiguracji debugowania

1. Uruchom aplikację w trybie debugowania, naciskając przycisk "Start" w kolorze zielonym ▶️ lub naciśnij F5
2. Upewnij się, że okno wyjściowe jest ustawione, aby wyświetlić Debug wynik (Ctrl + Alt + O)

1. W palecie poleceń uruchom reload
2. Przejdź do rozszerzenia i wybierz pozycję Open the Command Palette documentation.
3. W oknie Wyjście programu Visual Studio powinno zostać wyświetlone Debug message from GetItems

InvokableCommand, komenda

Kontynuujmy tworzenie nowego polecenia, które wyświetla MessageBox. W tym celu musimy utworzyć nową klasę, która implementuje InvokableCommand.

1. W programie Visual Studio dodaj nowy plik klasy do Pages katalogu
   • Skrót klawiaturowy: naciśnij Ctrl + Shift + A
   • Lub w Eksploratorze rozwiązań przejdź do pozycji Projekt > Dodaj nowy element...
2. W oknie dialogowym Dodawanie nowego elementu:
   1. Wybierz pozycję Klasa z listy.
   2. Nadaj nazwę plikowi klasy: ShowMessageCommand.cs
   3. Kliknij przycisk Dodaj.
3. Zastąp domyślny kod klasy:

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

Teraz możemy dodać to polecenie do listy poleceń w <ExtensionName>Page.cs pliku:

1. W pliku <ExtensionName>.cszaktualizuj element 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. Wdrażanie rozszerzenia
2. W palecie poleceń, Reload

I presto - polecenie, aby wyświetlić pole komunikatu!

Typy stron

Do tej pory pracowaliśmy tylko z poleceniami, które "coś robią". Można jednak również dodawać polecenia, które wyświetlają dodatkowe strony w palecie poleceń. W palecie istnieją dwa typy poleceń:

• InvokableCommand - Są to polecenia, które wykonują coś
• IPage - Są to polecenia, które pokazują coś

Ponieważ IPage są implementacjami ICommand, można ich używać w dowolnym miejscu, gdzie można używać poleceń. Oznacza to, że można dodać je do listy poleceń najwyższego poziomu lub do listy poleceń na stronie, menu kontekstowe w elemencie itp.

Istnieją dwa różne rodzaje stron, które można wyświetlić:

• ListPage — jest to strona zawierająca listę poleceń. To właśnie, z czym pracowaliśmy do tej pory.

• ContentPage — jest to strona zawierająca bogatą zawartość dla użytkownika. Dzięki temu można określić abstrakcyjną zawartość i pozwolić, aby paleta poleceń zajmowała się renderowaniem zawartości w środowisku natywnym. Do tej pory obsługiwane są dwa różne typy zawartości:
  • Zawartość języka Markdown — jest to zawartość napisana w języku Markdown i renderowana w palecie poleceń. Aby uzyskać szczegółowe informacje, zobacz MarkdownContent .

• Zawartość formularza — jest to zawartość, która wyświetla użytkownikowi formularz, a następnie zwraca wyniki tego formularza do rozszerzenia. Są one obsługiwane przez karty adaptacyjne Jest to przydatne do uzyskiwania danych wejściowych użytkownika lub wyświetlania bardziej złożonych układów informacji. Zobacz ZawartośćFormularza aby uzyskać szczegółowe informacje.

Dodawanie kolejnych poleceń

Zacznij od dodania nowej strony zawierającej listę poleceń. Utwórz nową klasę, która implementuje program ListPage.

1. W folderze Pages utwórz nową klasę o nazwie MySecondPage
2. Zaktualizuj kod do:

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.Zaktualizuj element , <ExtensionName>Page.cs aby uwzględnić tę nową stronę:

    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. Wdrażanie rozszerzenia
2. W palecie poleceń, Reload

W rozszerzeniu powinna się pojawić nowa strona zawierająca 100 poleceń, które kopiują liczbę do schowka.

Dalej: aktualizowanie listy poleceń

Treści powiązane

• PowerToys Narzędzie Paleta poleceń
• Omówienie rozszerzalności
• Przykłady rozszerzeń