Exibir conteúdo de markdown

Anterior: resultados do comando

A Paleta de Comandos dá suporte à exibição de conteúdo avançado além de listas de comandos simples. Você pode criar extensões que mostram texto formatado, documentação e conteúdo interativo usando markdown. Essa funcionalidade é particularmente útil para:

• Exibindo a documentação de ajuda ou manuais do usuário
• Mostrando versões prévias de arquivo ou resumos
• Fornecendo instruções ou tutoriais formatados
• Criando conteúdo interativo com comandos inseridos

Este artigo mostra como criar páginas que exibem conteúdo markdown na extensão Command Palette.

Até agora, mostramos apenas como exibir uma lista de comandos em um ListPage. No entanto, você também pode exibir conteúdo avançado em sua extensão, como markdown. Isso pode ser útil para mostrar a documentação ou uma visualização de um documento.

Trabalhando com conteúdo em formato markdown

IContentPage (e sua implementação de kit de ferramentas, ContentPage) é a base para exibir todos os tipos de conteúdo avançado na Paleta de Comandos. Para exibir o conteúdo de markdown, você pode usar a classe MarkdownContent .

1. Pages No diretório, adicione uma nova classe
2. Nomeie a classe MarkdownPage.cs
3. Atualize o arquivo para:

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. Abrir <ExtensionName>CommandsProvider.cs
2. Substitua os CommandItems para :MarkdownPage

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

1. Implantar sua extensão
2. Na paleta de comandos, Reload

Neste exemplo, uma nova ContentPage que exibe uma cadeia de caracteres de markdown simples é criada. A classe 'MarkdownContent' usa uma cadeia de caracteres de conteúdo markdown e a renderiza na Paleta de Comandos.

Você também pode adicionar vários blocos de conteúdo a uma página. Por exemplo, você pode adicionar dois blocos de conteúdo de markdown.

1. Atualizar 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. Implantar sua extensão
2. Na paleta de comandos, Reload

Isso permite que você combine diferentes tipos de conteúdo em uma única página.

Adicionando Item do Contexto de Comando

Você também pode adicionar comandos a um ContentPage. Isso permite que você adicione comandos adicionais para serem invocados pelo usuário no contexto do conteúdo. Por exemplo, se você tivesse uma página que exibisse um documento, poderia adicionar um comando para abrir o documento no Explorador de Arquivos:

1. No Page.cs <ExtensionName>, adicione doc_path, Commands e 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. Atualize o caminho em doc_path para um arquivo .txt no seu computador local
2. Implantar sua extensão
3. Na paleta de comandos, Reload
4. Selecionar <ExtensionName>
5. Pressione a tecla Enter, os documentos devem ser abertos

Adicionar imagens ao conteúdo de markdown

Com a Paleta de Comandos na versão PowerToys 0.95 e posteriores, você pode adicionar imagens ao conteúdo de Markdown de fontes adicionais usando um dos esquemas a seguir:

• Esquema de arquivos: habilita o carregamento de imagens usando o file: esquema.
  • Esse esquema restringe intencionalmente URIs de arquivo a caminhos absolutos para garantir a resolução correta quando passado pelo limite de extensão/host da Paleta de Comandos. Na maioria dos casos, extensões de terceiros fornecem os caminhos. No entanto, o host da Paleta de Comandos executa o carregamento real e, de outra forma, resolveria caminhos relativos a si mesmo.
• Esquema de dados: habilita o carregamento de imagens de URIs com o esquema data: (formatos em Base64 e codificados em URL).
  • Observação: antes das alterações introduzidas na PowerToys versão 0,95 e posterior, o controle de markdown pode travar ou ficar sem resposta ao processar entradas muito grandes, como imagens maiores que 5 MB ou com dimensões superiores a 4.000×4.000 pixels ou arquivos de markdown que excedem 1 MB de tamanho. Mesmo com as alterações, é recomendável manter os tamanhos de arquivo de imagem abaixo de 5 MB e redimensionar imagens para dimensões razoáveis antes da inserção. Para obter melhores resultados, compacte imagens e divida conteúdo de markdown muito grande em seções menores sempre que possível.
• ms-appx esquema: agora há suporte para esse esquema para carregar imagens.
  • Observação: como o host da Paleta de Comandos executa o carregamento, ms-appx: a resolução se aplica ao host e não às extensões, o que limita sua utilidade.
• ms-appdata esquema: agora há suporte para esse esquema para carregar imagens.
  • Semelhante a ms-appx:, a resolução ms-appdata: se aplica ao host, não às extensões. Isso limita sua utilidade para extensões de terceiros.

Além disso, a Paleta de Comandos nas versões 0.95 e posteriores introduz o conceito de indicadores de origem de imagem, implementados como parâmetros de consulta de string acoplados ao URI original.

Essas dicas permitem que os desenvolvedores de extensão influenciem o comportamento das imagens dentro do conteúdo de markdown.

• --x-cmdpal-fit
  • none: sem dimensionamento automático, fornece imagem como está (padrão)
  • fit: dimensionar para ajustar o espaço disponível
• --x-cmdpal-upscale
  • true: Permitir upscaling
  • false: Somente redução de escala (padrão)
• --x-cmdpal-width: largura desejada em pixels
• --x-cmdpal-height: altura desejada em pixels
• --x-cmdpal-maxwidth: largura máxima em pixels
• --x-cmdpal-maxheight: altura máxima em pixels

Consulte a página SampleMarkdownImages no projeto de exemplo genérico SamplePagesExtension no PowerToys repositório GitHub para obter exemplos de como usar imagens no conteúdo de markdown da sua extensão.

Próximo passo: Obter a entrada do usuário com formulários

Conteúdo relacionado

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