命令結果

上一個： 將最上層命令新增至延伸模組

IInvokableCommand 代表命令面板中的單一可執行項目，當用戶選取命令時會觸發該項目。

選取命令時，會呼叫 Invoke 方法。 這是您用來實作您的擴充套件應執行邏輯的地方。 Invoke 方法必須傳回 CommandResult，它會告訴命令選擇區如何在命令執行之後回應，例如，是否要顯示訊息、開啟檔案或不執行任何動作。

此頁面說明您可以傳回的 CommandResult 7 種不同類型，以及每個類型的功能：

KeepOpen 命令結果

命令 KeepOpen 結果不會執行任何動作。 它會讓調色盤保持在當前的狀態，並具有目前的頁面堆疊和查詢。 這對於想要將使用者保留在命令選擇區中的命令很有用，以便繼續使用目前的頁面。

隱藏命令結果

此命令結果會讓目前的頁面保持開啟狀態，但會隱藏命令選擇區。 這對於想要將用戶短暫從命令選擇區中帶走的命令很有用，但接著回到此內容。

GoBack 命令結果

此結果會將使用者帶回命令選擇區中的頁面，並讓視窗保持可見。 這非常適合表單頁面，執行 命令時應該會帶您回到先前的內容。

GoHome 命令結果

此結果會將使用者帶回命令選擇區的主頁面。 它會讓調色盤保持可見（除非調色盤否則失去焦點）。 針對您已變更最上層命令的案例，請考慮使用此選項。

忽略命令結果

此結果會在執行動作之後隱藏命令選擇區，並將它帶回首頁。 在下一次啟動時，命令選擇區會從主頁面開始，並顯示空白查詢。 這適用於單次動作的命令，或不需要讓命令選擇區保持開啟。

如果您不知道要使用什麼，這應該是您的預設值。 在理想情況下，用戶應該進入調色盤，找到所需的東西，並完成工作。

ShowToast 命令結果

此結果會顯示暫時性桌面層級訊息給使用者。 這特別適用於顯示當調色盤關閉時所發生的動作確認。

請考慮輔助工具中的 CopyTextCommand - 此命令會顯示提示訊息，其中文字為「複製到剪貼簿」，然後關閉顯示面板。

根據預設，CommandResult.ShowToast(string) 輔助工具會有一個 Result 的 CommandResult.Dismiss。 不過，如果您願意，可以將結果更改為其他任意一個。 這可讓您顯示快顯通知，並讓調色盤保持開啟，如果您想要的話。

確認命令結果

此結果會向使用者顯示確認對話方塊。 如果使用者確認對話框，則會執行 PrimaryCommand 的 ConfirmationArgs。

這適用於可能有破壞性動作的命令，或需要確認使用者意圖的命令。

範例

以下是一個頁面，其中包含每一種類型的 CommandResult 的一個命令：

1. 開啟/Pages/<ExtensionName>Page.cs
2. 將 GetItems 替換成以下的 GetItems:

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. 部署擴充功能
2. 在命令選擇區中， Reload

下一步： 顯示 Markdown 內容

相關內容

• PowerToys 命令面板實用工具
• 擴充性概觀
• 擴充功能範例