顯示 Markdown 內容

上一個： 命令結果

命令面板支援豐富的內容顯示，而不僅僅是簡單的命令清單。 您可以使用 Markdown 建立顯示格式化文字、文件和互動式內容的擴充功能。 此功能特別適用於：

• 顯示說明文件或使用者指南
• 顯示檔案預覽或摘要
• 提供格式化的說明或教學課程
• 使用內嵌指令建立互動式內容

本文說明如何建立在命令面板延伸模組中顯示 Markdown 內容的頁面。

到目前為止，我們只示範如何在 ListPage 中顯示命令清單。 不過，您也可以在延伸模塊中顯示豐富的內容，例如 Markdown。 這可以用來顯示文件資料或文件預覽。

與 Markdown 內容互動

IContentPage （及其工具組實作 ContentPage）是用來在命令選擇區中顯示所有類型的豐富內容的基礎。 若要顯示 Markdown 內容，您可以使用 MarkdownContent 類別。

1. 在 Pages 目錄中，新增類別
2. 為類別命名 MarkdownPage.cs
3. 將檔案更新為：

using Microsoft.CommandPalette.Extensions;
using Microsoft.CommandPalette.Extensions.Toolkit;
using System.Text.Json.Nodes;

internal sealed partial class MarkdownPage : ContentPage
{
    public MarkdownPage()
    {
        Icon = new("\uE8A5"); // Document icon
        Title = "Markdown page";
        Name = "Preview file";
    }

    public override IContent[] GetContent()
    {
        return [
            new MarkdownContent("# Hello, world!\n This is a **markdown** page."),
        ];
    }
}

1. 開啟<ExtensionName>CommandsProvider.cs
2. 用CommandItem取代MarkdownPages：

public <ExtensionName>CommandsProvider()
{
    DisplayName = "My sample extension";
    Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.png");
    _commands = [
+       new CommandItem(new MarkdownPage()) { Title = DisplayName },
    ];
}

1. 部署擴充功能
2. 在指令面板中， Reload

在這個範例中，會建立顯示簡單 Markdown 字串的新 ContentPage。 'MarkdownContent' 類別會採用 Markdown 內容的字串，並在命令選擇區中轉譯它。

您也可以將多個內容區塊新增至頁面。 例如，您可以新增兩個 Markdown 內容區塊。

1. 更新 GetContent：

public override IContent[] GetContent()
{
    return [
        new MarkdownContent("# Hello, world!\n This is a **markdown** page."),
+       new MarkdownContent("## Second block\n This is another block of content."),
    ];
}

1. 部署擴充功能
2. 在命令選擇區中， Reload

這可讓您在單一頁面上混合並比對不同類型的內容。

新增 CommandContextItem

您也可以將命令新增至 ContentPage。 這可讓您在內容的內容中新增使用者叫用的其他命令。 例如，如果您有顯示文件的頁面，您可以新增命令以在檔案總管中開啟檔：

1. 在您的 <ExtensionName>Page.cs中，新增 doc_path、 Commands 和 MarkdownContent：

public class <ExtensionName>Page : ContentPage
{
+   private string doc_path = "C:\\Path\\to\\file.txt";
    public <ExtensionName>Page()
    {
        Icon = new("\uE8A5"); // Document icon
        Title = "Markdown page";
        Name = "Preview file";

+       Commands = [
+           new CommandContextItem(new OpenUrlCommand(doc_path)) { Title = "Open in File Explorer" },
+       ];
    }
    public override IContent[] GetContent()
    {
        return [
            new MarkdownContent("# Hello, world!\n This is a **markdown** document."),
            new MarkdownContent("## Second block\n This is another block of content."),
+           new MarkdownContent($"## Press enter to open `{doc_path}`"),
        ];
    }
}

1. 將中的 doc_path 路徑更新為本機電腦上的 .txt 檔案
2. 部署擴充功能
3. 在指令面板中， Reload
4. 選取 <ExtensionName>
5. 按下 Enter 按鍵，文件應該會開啟

將影像新增至 Markdown 內容

使用 0.95 和更新版本的 PowerToys 命令面板，您可以使用下列其中一個配置，從其他來源將影像新增至 Markdown 內容：

• 檔案協議：啟用使用 file: 協議載入影像。
  • 此方案刻意將檔案 URI 限制為絕對路徑，以確保在通過 Command Palette 擴充模組與主機邊界時能正確解析。 在大多數情況下，第三方擴充功能會提供路徑。 不過，命令面板主機負責執行實際的載入，否則會就自身來解析路徑。
• 資料方案：允許從 URI 使用 data: 方案載入影像（包含 Base64 和 URL 編碼形式）。
  • 附註： 在 0.95 及更新版本引 PowerToys 進的變更之前，Markdown 控制項在處理非常大的輸入時可能會停止回應或變得無回應，例如大於 5 MB 或尺寸超過 4000×4000 像素的影像，或大小超過 1 MB 的 Markdown 檔案。 即使進行了更改，建議將圖像文件大小保持在 5 MB 以下，並在嵌入之前將圖像大小調整為合理的尺寸。 為獲得最佳結果，請壓縮圖像並儘可能將非常大的 Markdown 內容拆分為較小的部分。
• ms-appx 協議：現在支援此協議載入圖片。
  • 註：由於「命令面板」主機會執行載入，ms-appx: 因此解析會套用至主機，而不是擴充功能，這限制了其實用性。
• ms-appdata 協議：現在支援此協議用於載入影像。
  • 與 ms-appx:類似， ms-appdata: 解析會套用至主機，而不是延伸模組。 這限制了它對第三方擴展的有用性。

此外，0.95 和更新版本中的 PowerToys 指令調色盤引入了圖像源提示的概念，作為附加在原始 URI 的查詢字符串參數實現。

這些提示可讓擴充功能開發人員影響 Markdown 內容中影像的行為。

• --x-cmdpal-fit
  • none：沒有自動縮放，按原樣提供圖像（默認）
  • fit：縮放以符合可用空間
• --x-cmdpal-upscale
  • true：允許升級
  • false：僅降級 （預設）
• --x-cmdpal-width：所需的寬度（以像素為單位）
• --x-cmdpal-height：所需高度（以像素為單位）
• --x-cmdpal-maxwidth：最大寬度（以像素為單位）
• --x-cmdpal-maxheight：最大高度（以像素為單位）

如需在延伸模組的 Markdown 內容中使用影像的範例，請參閱 GitHub 存放庫中 SamplePagesExtension 一般範例專案中的 PowerToys 頁面。

下一步： 使用表單取得用戶輸入

相關內容

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