Exibir conteúdo de marcação

Anterior: Resultados do Comando

A Paleta de Comandos suporta a 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. Esta capacidade é particularmente útil para:

• Exibindo documentação de ajuda ou guias do usuário
• Mostrando visualizações ou resumos de arquivos
• Fornecer instruções formatadas ou tutoriais
• Criação de conteúdo interativo com comandos incorporados

Este artigo mostra como criar páginas que exibem conteúdo de marcação na extensão Paleta de comandos.

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

Trabalhando com conteúdo de 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 conteúdo de marcação, 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 por MarkdownPage:

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

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

Neste exemplo, um novo ContentPage que exibe uma cadeia de caracteres de marcação simples é criado. A classe 'MarkdownContent' recebe uma sequência de texto em formato Markdown e a exibe na Paleta de Comandos.

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

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

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

Adicionando CommandContextItem

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

1. No seu <ExtensionName>Page.cs, 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 no doc_path para um ficheiro .txt na sua máquina local
2. Implante sua extensão
3. Na Paleta de Comandos, Reload
4. Selecione <ExtensionName>
5. Pressione a tecla Enter e os documentos devem abrir.

Adicionar imagens ao conteúdo de marcação

Com a Paleta de Comandos na versão PowerToys 0.95 e posteriores, poderá adicionar imagens ao seu conteúdo em Markdown a partir de fontes adicionais usando um dos seguintes esquemas:

• Esquema de arquivos: Permite carregar imagens usando o file: esquema.
  • Esse esquema restringe intencionalmente os URIs de arquivo a caminhos absolutos para garantir a resolução correta quando passados pelo limite de extensão/host da Paleta de Comandos. Na maioria das vezes, as extensões de terceiros definem os caminhos. No entanto, o host da paleta de comandos executa o carregamento real e, caso contrário, resolveria caminhos relativos a si mesmo.
• Esquema de dados: Permite carregar imagens de URIs com o esquema data: (tanto nas formas codificadas em Base64 como em URL).
  • Nota: Antes das alterações introduzidas em PowerToys 0.95 e posteriores, o controle de markdown podia travar ou deixar de responder ao processar entradas muito grandes, como imagens maiores que 5 MB ou com dimensões superiores a 4000×4000 pixels, ou arquivos de markdown com tamanho superior a 1 MB. Mesmo com as alterações, recomenda-se manter os tamanhos dos arquivos de imagem abaixo de 5 MB e redimensionar as imagens para dimensões razoáveis antes de incorporar. Para obter melhores resultados, comprima imagens e divida o conteúdo de marcação muito grande em seções menores, sempre que possível.
• ms-appx protocolo: Este protocolo agora é compatível para carregar imagens.
  • Nota: 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 scheme: Este esquema agora é suportado para carregar imagens.
  • Semelhante ao ms-appx:, ms-appdata: a resolução se aplica ao host, não às extensões. Isso limita sua utilidade para extensões de terceiros.

Além disso, o Command Palette no PowerToys 0.95 e posterior introduz o conceito de indicadores de origem de imagem, implementados como parâmetros de string de consulta anexados ao URI original.

Essas dicas permitem que os desenvolvedores de extensões 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: Dimensione para se ajustar ao espaço disponível
• --x-cmdpal-upscale
  • true: Permitir upscaling
  • false: Somente reduzir 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 uso de imagens no conteúdo de markdown da sua extensão.

Próximo: Obter informações do utilizador com formulários

Conteúdo relacionado

• PowerToys Utilitário Paleta de Comandos
• Visão geral da extensibilidade
• Amostras de extensão