about_ANSI_Terminals

Artigo
08/27/2024

Descrição breve

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

Descrição longa

O PowerShell tem muitos recursos que dão 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, $PSStyle, e alterações no mecanismo do PowerShell para dar suporte à saída de texto decorado com ANSI.

Suporte a terminais 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 Wikipedia.

No Windows 10 e superior, o Host do Console do Windows é 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 é fornecida 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:

Redefinir - Desativa todas as decorações
Blink - Ativa o Blink
BlinkOff - Desliga o Blink
Negrito - Ativa o negrito
BoldOff - Desativa o negrito
Dim - Ativa Dim (adicionado no PowerShell 7.4)
DimOff – desativa o Dim (adicionado no PowerShell 7.4)
Oculto - Ativa Oculto
HiddenOff - Desativa o Oculto
Inverter - Ativa a marcha à ré
ReverseOff - Desativa o Reverse
Itálico - Ativa o itálico
ItalicOff - Desativa o itálico
Sublinhado - Ativa o sublinhado
UnderlineOff - Desativa o sublinhado
Tachado - Vira greve em
StrikethroughOff - Desativa o tachado
OutputRendering - Controle quando a renderização de saída é usada
Formatação - Objeto aninhado que controla a formatação padrão para fluxos de saída
Progresso - Objeto aninhado que controla a renderização das 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
Plano de fundo - Objeto aninhado para controlar a cor do plano de fundo

Os membros de 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 de propriedade facilitam a criação de cadeias de caracteres decoradas usando o preenchimento de tabulação:

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

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

$PSStyle.OutputRendering é uma System.Management.Automation.OutputRendering enumeração com os valores:
- ANSI: As sequências de escape ANSI são sempre passadas no estado em que se encontram.
  
  Importante
  
  Você deve usar o modo ANSI ao redirecionar a saída para um arquivo ou o pipeline que deve ser executado downstream. 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 sejam 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 Redirecionando a saída.
Os $PSStyle.Background membros 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 FromRgb() método para especificar a cor de 24 bits. Existem duas maneiras de chamar o FromRgb() método.
```
string FromRgb(byte red, byte green, byte blue)
string FromRgb(int rgb)
```
Um dos exemplos a seguir define a cor de fundo como a cor Beigede 24 bits .
```
$PSStyle.Background.FromRgb(245, 245, 220)
$PSStyle.Background.FromRgb(0xf5f5dc)
```
$PSStyle.Formatting é um objeto aninhado para controlar a formatação padrão de depuração, erro, detalhado, mensagens de aviso e cabeçalhos de lista e tabela. Você também pode controlar atributos como negrito e sublinhado. Ele substitui $Host.PrivateData como a maneira de gerenciar cores para formatação de renderização. $Host.PrivateData continua a existir para compatibilidade com versões anteriores, mas não está conectado ao $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
- Aviso - formatação para mensagens de aviso
- Detalhado - formatação para mensagens detalhadas
- Depuração - formatação para 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 comentários (adicionada como um recurso experimental no PowerShell 7.4)
- FeedbackAction – formatação para as ações sugeridas do provedor de comentários (adicionado como um recurso experimental no PowerShell 7.4)
$PSStyle.Progress Permite controlar a renderização da barra de visualização de progresso.
- Estilo - Uma string ANSI que define o estilo de renderização.
- MaxWidth - Define a largura máxima da exibição. Assume o padrão de 120. O valor mínimo é 18.
- View - Uma enumeração com valores Minimal e Classic. Classic é a renderização existente sem alterações. Minimal é uma renderização mínima de linha única. Minimal é o padrão.
- UseOSCIndicator - O padrão é $false. Defina como $true para terminais que suportam indicadores OSC.
Observação

Se o host não der suporte ao terminal virtual, $PSStyle.Progress.View será definido automaticamente 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 de objetos FileInfo .
- Diretório - Membro interno para especificar a cor dos diretórios
- SymbolicLink - Membro interno para especificar a cor dos links simbólicos
- Executável - Membro interno para especificar a cor dos executáveis.
- Extensão - Use este membro para definir cores para diferentes extensões de arquivo. O membro Extensão inclui previamente extensões para arquivos do PowerShell e da camada de armazenamento de arquivos.

Cmdlets que geram saída ANSI

Os cmdlets markdown – o cmdlet Show-Markdown exibe o conteúdo de um arquivo que contém texto markdown. A saída é renderizada usando sequências ANSI para representar estilos diferentes. Você pode gerenciar 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 realçar 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

Redirecionando a saída no `Host` modo

Por padrão, $PSStyle.OutputRendering é um conjunto 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-File, e Out-String. A saída de executáveis nativos não é afetada.

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

Quando o objeto de entrada é uma cadeia de caracteres pura, esses cmdlets mantêm a cadeia de caracteres inalterada, independentemente da configuração 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 .

Essa é 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 de uma linha de comando e redireciona a saída.

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

pwsh -noprofile -command 'Get-Childitem' > out.txt

Ao inspecionar o conteúdo, você vê as sequências de out.txt escape ANSI.

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

pwsh -noprofile -command 'Get-Childitem > out.txt'

Quando você inspeciona o conteúdo de não há sequências de out.txt 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 conforme abaixo:

dumb -Define $Host.UI.SupportsVirtualTerminal = $false
xterm-mono -Define $PSStyle.OutputRendering = PlainText
xtermm -Define $PSStyle.OutputRendering = PlainText

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

Usando `$PSStyle` 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 StringDecorated tipo é adicionado para lidar com cadeias de caracteres de escape ANSI.
A string IsDecorated propriedade booleana foi adicionada para retornar true quando a cadeia de caracteres contém ESC sequências de C1 CSI caracteres.
A Length propriedade de uma cadeia de caracteres retorna o comprimento do texto sem as sequências de escape ANSI.
O StringDecorated Substring(int contentLength) método retorna uma subcadeia de caracteres 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 a formatação da tabela a fim de truncar cadeias de caracteres e preservar as sequências de escape ANSI que não ocupam espaço de caracteres imprimível.
O string ToString() método permanece o mesmo e retorna a versão de texto não criptografado da cadeia de caracteres.
O string ToString(bool Ansi) método retornará a cadeia de caracteres inserida ANSI bruta se o Ansi parâmetro for verdadeiro. Caso contrário, uma versão de texto não criptografado com sequências de escape ANSI removidas será retornada.
O FormatHyperlink(string text, uri link) método retorna uma cadeia de caracteres contendo sequências de escape ANSI usadas para decorar hiperlinks. Alguns hosts de terminal, como o Terminal do Windows, dão suporte a 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 à [System.Management.Automation.PSStyle] classe.

[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 ConsoleColor em sequências de escape ANSI para cores de primeiro plano e plano de fundo ou para uma combinação de ambas.

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

Compartilhar via

about_ANSI_Terminals

Descrição breve

Descrição longa

Suporte a terminais ANSI

$PSStyle

Cmdlets que geram saída ANSI

Redirecionando a saída no `Host` modo

Desativando a saída ANSI

Usando `$PSStyle` de C#

Métodos estáticos da classe PSStyle

Confira também

Recursos adicionais

Compartilhar via

about_ANSI_Terminals

Descrição breve

Descrição longa

Suporte a terminais ANSI

$PSStyle

Cmdlets que geram saída ANSI

Redirecionando a saída no Host modo

Desativando a saída ANSI

Usando $PSStyle de C#

Métodos estáticos da classe PSStyle

Confira também

Recursos adicionais

Redirecionando a saída no `Host` modo

Usando `$PSStyle` de C#