Partilhar via

sobre_Terminais_ANSI

Breve descrição

Descreve o suporte disponível para sequências de escape ANSI no PowerShell.

Descrição longa

O PowerShell tem muitos recursos que oferecem suporte ao uso de sequências de escape ANSI para controlar a renderização da saída no aplicativo de terminal que está hospedando o PowerShell.

O PowerShell 7.2 adicionou uma nova variável automática, $PSStylee alterações no mecanismo do PowerShell para dar suporte à saída de texto decorado com ANSI.

Suporte ao Terminal ANSI

Os recursos ANSI são projetados para serem compatíveis com os terminais baseados em xterm. Para obter mais informações, consulte xterm na Wikipédia.

No Windows 10 e superior, o Windows Console Host é compatível com xterm. O aplicativo Windows Terminal também é compatível com xterm.

No macOS, o aplicativo de terminal padrão é compatível com xterm.

Para Linux, cada distribuição vem com um aplicativo de terminal diferente. Consulte a documentação da sua distribuição para encontrar uma aplicação de terminal adequada.

$PSStyle

A variável tem as seguintes propriedades:

  • Reset - Desliga todas as decorações
  • Blink - Ativa o Blink
  • BlinkOff - Desliga o Blink
  • Bold - Torna-se ousado
  • BoldOff - Desliga o negrito
  • Dim - Ativa o Dim (adicionado no PowerShell 7.4)
  • DimOff - Desativa o Dim (adicionado no PowerShell 7.4)
  • Hidden - Fica escondido
  • HiddenOff - Desativa o modo oculto
  • Reverso - Ativa Reverso
  • ReverseOff - Desliga o Reverse
  • Itálico - Ativa o Itálico
  • ItalicOff - Desliga o Itálico
  • Sublinhar - Ativa o sublinhado
  • UnderlineOff - Desliga o sublinhado
  • Strikethrough - Vira greve
  • StrikethroughOff - Desativa o rasurado
  • OutputRendering - Controla quando a renderização de saída é usada
  • Formatação - Objeto aninhado que controla a formatação padrão dos fluxos de saída
  • Progress - Objeto aninhado que controla a renderização de barras de progresso
  • FileInfo - Objeto aninhado para controlar a coloração de objetos FileInfo.
  • Primeiro Plano - Objeto aninhado para controlar a coloração do Primeiro Plano
  • Background - Objeto aninhado para controlar a coloração do plano de fundo

Os membros base retornam cadeias de caracteres de sequências de escape ANSI mapeadas para seus nomes. Os valores são configuráveis para permitir a personalização. Por exemplo, você pode alterar negrito para sublinhado. Os nomes das propriedades facilitam-lhe a criação de cadeias de caracteres decoradas usando o completamento por tabulação.

"$($PSStyle.Background.BrightCyan)Power$($PSStyle.Underline)$($PSStyle.Bold)Shell$($PSStyle.Reset)"

Os membros a seguir controlam como ou quando a formatação ANSI é usada:

  • $PSStyle.OutputRendering é um enum System.Management.Automation.OutputRendering com os valores:

    • ANSI: As sequências de fuga ANSI são sempre passadas através as-is.

      Importante

      Você deve usar modo ANSI ao redirecionar a saída para um arquivo ou o pipeline que se destina a ser executado a jusante. Isso garante que a saída não seja alterada. O uso de qualquer outro modo altera a saída removendo sequências de escape ANSI, o que pode alterar o comportamento de execução.

    • PlainText: As sequências de escape ANSI são sempre removidas para que seja apenas texto simples. Em sessões remotas, se o host remoto estiver definido como PlainText, a saída será removida das sequências de escape ANSI antes de enviá-la de volta ao cliente local.

    • Host: Este é o comportamento padrão. As sequências de escape ANSI são removidas da saída redirecionada ou canalizada. Para obter mais informações, consulte Redirecionamento de saída.

  • Os membros $PSStyle.Background e $PSStyle.Foreground são cadeias de caracteres que contêm as sequências de escape ANSI para as 16 cores padrão do console.

    • Black
    • BrightBlack
    • White
    • BrightWhite
    • Red
    • BrightRed
    • Magenta
    • BrightMagenta
    • Blue
    • BrightBlue
    • Cyan
    • BrightCyan
    • Green
    • BrightGreen
    • Yellow
    • BrightYellow

    Os valores são configuráveis e podem conter qualquer número de sequências de escape ANSI. Há também um método FromRgb() para especificar a cor de 24 bits. Há duas maneiras de chamar o método FromRgb().

    string FromRgb(byte red, byte green, byte blue)
string FromRgb(int rgb)

    Qualquer um dos exemplos a seguir define a cor de fundo como a cor hexadecimal de 24 bits Beige.

    $PSStyle.Background.FromRgb(245, 245, 220)
$PSStyle.Background.FromRgb(0xf5f5dc)

  • $PSStyle.Formatting é um objeto aninhado para controlar a formatação padrão de mensagens de depuração, erro, verboso, aviso e de cabeçalhos de lista e tabela. Também pode controlar atributos como o negrito e o sublinhado. Substitui o $Host.PrivateData como a forma de gerir cores para a renderização de formatação. $Host.PrivateData continua a existir para compatibilidade com versões anteriores, mas não está ligado a $PSStyle.Formatting. $PSStyle.Formatting tem os seguintes membros:

    • FormatAccent - formatação para itens de lista
    • ErrorAccent - formatação para metadados de erro
    • Erro - formatação para mensagens de erro
    • Warning - formatação para mensagens de aviso
    • Verbose - formatação para mensagens detalhadas
    • Debug - formatação de mensagens de depuração
    • TableHeader - formatação para cabeçalhos de tabela
    • CustomTableHeaderLabel - formatação para cabeçalhos de tabela que não são realmente propriedades no objeto
    • FeedbackName - formatação para o nome do provedor de comentários (adicionado como um recurso experimental no PowerShell 7.4)
    • FeedbackText - formatação para mensagens de feedback (adicionado como um recurso experimental no PowerShell 7.4)
    • FeedbackAction - formatação para as ações sugeridas pelo provedor de comentários (adicionada como um recurso experimental no PowerShell 7.4)

  • $PSStyle.Progress permite controlar a renderização da barra de visualização de progresso.

    • Style - Uma cadeia de caracteres ANSI definindo o estilo de renderização.
    • MaxWidth - Define a largura máxima da vista. O padrão é 120. O valor mínimo é 18.
    • View - Um enum com valores, Minimal e Classic. Classic é a renderização existente sem alterações. Minimal é uma renderização mínima de uma única linha. Minimal é o padrão.
    • UseOSCIndicator - O padrão é $false. Defina isso como $true para terminais que suportam indicadores OSC.

    Observação

    Se o host não suportar o Terminal Virtual, $PSStyle.Progress.View será automaticamente definido como Classic.

    O exemplo a seguir define o estilo de renderização como uma barra de progresso mínima.

    $PSStyle.Progress.View = 'Minimal'

  • $PSStyle.FileInfo é um objeto aninhado para controlar a coloração dos objetos FileInfo.

    • Directory - Membro interno para definir a cor dos diretórios

    • SymbolicLink - Membro embutido para especificar cores para links simbólicos

    • Executável - Membro incorporado para especificar a cor de executáveis.

    • Extension - Use este membro para definir cores para diferentes extensões de arquivo. O membro Extension pré-define cores para extensões de arquivo e PowerShell.

      O exemplo seguinte mostra como alterar as cores para várias FileInfo definições e extensões específicas de ficheiros. As cores são escolhidas para funcionar bem num fundo de terminal claro.

      $PSStyle.FileInfo.Directory = $PSStyle.Background.FromRgb(0x2f6aff) +
    $PSStyle.Foreground.BrightWhite
$PSStyle.FileInfo.SymbolicLink = $PSStyle.Foreground.Cyan
$PSStyle.FileInfo.Executable = $PSStyle.Foreground.BrightMagenta
$PSStyle.FileInfo.Extension['.ps1'] = $PSStyle.Foreground.Cyan
$PSStyle.FileInfo.Extension['.ps1xml'] = $PSStyle.Foreground.Cyan
$PSStyle.FileInfo.Extension['.psd1'] = $PSStyle.Foreground.Cyan
$PSStyle.FileInfo.Extension['.psm1'] = $PSStyle.Foreground.Cyan

Cmdlets que geram saída ANSI

  • Os cmdlets markdown - o cmdlet Show-Markdown exibe o conteúdo de um ficheiro que contém texto de marcação. A saída é renderizada usando sequências ANSI para representar estilos diferentes. Você pode gerir as definições dos estilos usando os cmdlets Get-MarkdownOption e Set-MarkdownOption.
  • Cmdlets PSReadLine - o módulo PSReadLine usa sequências ANSI para colorir elementos de sintaxe do PowerShell na linha de comando. As cores podem ser gerenciadas usando Get-PSReadLineOption e Set-PSReadLineOption.
  • Get-Error - o cmdlet Get-Error retorna uma exibição detalhada de um objeto Error, formatado para facilitar a leitura.
  • Select-String - A partir do PowerShell 7.0, Select-String usa sequências ANSI para destacar os padrões correspondentes na saída.
  • Write-Progress - A saída ANSI é gerenciada usando $PSStyle.Progress, conforme descrito acima. Para obter mais informações, consulte Write-Progress

Redirecionamento de saída no modo Host

Por padrão, $PSStyle.OutputRendering é definido como Host. As sequências de escape ANSI são removidas da saída redirecionada ou canalizada.

OutputRendering só se aplica à renderização no Host, Out-Filee Out-String. A saída de executáveis nativos não é afetada.

O PowerShell 7.2.6 alterou o comportamento do Out-File e do Out-String para os seguintes cenários:

  • Quando o objeto de entrada é uma cadeia de caracteres simples, estes cmdlets mantêm-na inalterada, independentemente da configuração de OutputRendering .
  • Quando o objeto de entrada precisa ter uma exibição de formatação aplicada a ele, esses cmdlets mantêm ou removem sequências de escape das cadeias de caracteres de saída de formatação com base na configuração OutputRendering.

Esta é uma alteração significativa nesses cmdlets em comparação com o PowerShell 7.2.

OutputRendering não se aplica à saída do processo de host do PowerShell, por exemplo, quando você executa pwsh a partir de uma linha de comando e redireciona a saída.

No exemplo a seguir, o PowerShell é executado no Linux a partir do bash. O cmdlet Get-ChildItem produz texto decorado com ANSI. Como o redirecionamento ocorre no processo de bash, fora do host do PowerShell, a saída não é afetada pelo OutputRendering.

pwsh -NoProfile -Command 'Get-ChildItem' > out.txt

Quando inspecionas o conteúdo de out.txt, vês as sequências de escape ANSI.

Por outro lado, quando o redirecionamento ocorre dentro da sessão do PowerShell, OutputRendering afeta a saída redirecionada.

pwsh -NoProfile -Command 'Get-ChildItem > out.txt'

Quando você inspeciona o conteúdo de out.txt não há sequências de escape ANSI.

Desativando a saída ANSI

O suporte para sequências de escape ANSI pode ser desativado usando as variáveis de ambiente TERM ou NO_COLOR.

Os seguintes valores de $Env:TERM alteram o comportamento da seguinte maneira:

  • dumb - conjuntos $Host.UI.SupportsVirtualTerminal = $false
  • xterm-mono - conjuntos $PSStyle.OutputRendering = PlainText
  • xterm - conjuntos $PSStyle.OutputRendering = PlainText

Se $Env:NO_COLOR existir, $PSStyle.OutputRendering será definido como PlainText. Para obter mais informações sobre a variável de ambiente NO_COLOR, consulte https://no-color.org/.

Usando $PSStyle a partir de C#

Os desenvolvedores de C# podem acessar PSStyle como um singleton, conforme mostrado no exemplo a seguir:

string output = $"{PSStyle.Instance.Foreground.Red}{PSStyle.Instance.Bold}Hello{PSStyle.Instance.Reset}";

PSStyle existe no namespace System.Management.Automation.

O mecanismo do PowerShell inclui as seguintes alterações:

  • O sistema de formatação do PowerShell é atualizado para respeitar $PSStyle.OutputRendering.
  • O tipo StringDecorated é adicionado para manipular cadeias de caracteres com escape ANSI.
  • A propriedade booleana string IsDecorated foi adicionada para retornar verdadeiro quando a string contém as sequências de caracteres ESC ou C1 CSI.
  • A propriedade Length de uma cadeia de caracteres retorna o comprimento do texto sem as sequências de escape ANSI.
  • O método StringDecorated Substring(int contentLength) retorna uma substring começando no índice 0 até o comprimento do conteúdo que não faz parte das sequências de escape ANSI. Isso é necessário para que a formatação da tabela trunce cadeias de caracteres e preserve as sequências de escape ANSI que não ocupam espaço de caracteres imprimíveis.
  • O método string ToString() permanece o mesmo e retorna a versão de texto sem formatação da cadeia de caracteres.
  • O método string ToString(bool Ansi) retorna a cadeia de caracteres incorporada ANSI bruta se o parâmetro Ansi for true. Caso contrário, uma versão de texto simples com sequências de escape ANSI removidas será retornada.
  • O método FormatHyperlink(string text, uri link) retorna uma cadeia de caracteres contendo sequências de escape ANSI usadas para decorar hiperlinks. Alguns hosts de terminal, como o Windows Terminal, suportam essa marcação, o que torna o texto renderizado clicável no terminal.

Métodos estáticos da classe PSStyle

O PowerShell 7.4 adiciona três novos métodos estáticos à classe [System.Management.Automation.PSStyle].

[System.Management.Automation.PSStyle] | Get-Member -Static -MemberType Method

   TypeName: System.Management.Automation.PSStyle

Name                               MemberType Definition
----                               ---------- ----------
Equals                             Method     static bool Equals(System.Object objA, System.Object objB)
MapBackgroundColorToEscapeSequence Method     static string MapBackgroundColorToEscapeSequence(System.ConsoleColor bac…
MapColorPairToEscapeSequence       Method     static string MapColorPairToEscapeSequence(System.ConsoleColor foregroun…
MapForegroundColorToEscapeSequence Method     static string MapForegroundColorToEscapeSequence(System.ConsoleColor for…
ReferenceEquals                    Method     static bool ReferenceEquals(System.Object objA, System.Object objB)

Esses métodos fornecem uma maneira de converter valores de ConsoleColor em sequências de escape ANSI para cores de primeiro plano e plano de fundo ou para uma combinação de ambos.

Os exemplos a seguir mostram as sequências de escape ANSI produzidas por esses métodos.

using namespace System.Management.Automation
[PSStyle]::MapBackgroundColorToEscapeSequence('Black') | Format-Hex

   Label: String (System.String) <3A04954D>

          Offset Bytes                                           Ascii
                 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
          ------ ----------------------------------------------- -----
0000000000000000 1B 5B 34 30 6D                                  �[40m

[PSStyle]::MapForegroundColorToEscapeSequence('Red') | Format-Hex

   Label: String (System.String) <38B50F41>

          Offset Bytes                                           Ascii
                 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
          ------ ----------------------------------------------- -----
0000000000000000 1B 5B 39 31 6D                                  �[91m

[PSStyle]::MapColorPairToEscapeSequence('Red','Black') | Format-Hex

   Label: String (System.String) <365A5875>

          Offset Bytes                                           Ascii
                 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
          ------ ----------------------------------------------- -----
0000000000000000 1B 5B 39 31 3B 34 30 6D                         �[91;40m

Consulte também

  • Last updated on