about_ANSI_Terminals
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 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 $PSStyle
automática e alterações no mecanismo do PowerShell para oferecer 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 Wikipedia.
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 é 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:
- Reset - Desliga todas as decorações
- Piscar - Ativa o Blink
- BlinkOff - Desativa o Blink
- Ousado - Vira Negrito
- BoldOff - Desativa o Negrito
- Dim - Ativa o Dim (adicionado ao PowerShell 7.4)
- DimOff - Desativa o Dim (adicionado ao PowerShell 7.4)
- Hidden - Fica Oculto
- HiddenOff - Desativa Oculto
- Reverso - Ativa o Reverso
- ReverseOff - Desativa a opção Reverter
- Itálico - Ativa Itálico
- ItalicOff - Desativa o itálico
- Sublinhado - Vira sublinhado em
- UnderlineOff - Desativa o sublinhado
- Strikethrough - Vira strike through
- StrikethroughOff - Desativa o strike through
- 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
- 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 em primeiro plano
- Plano de fundo - Objeto aninhado para controlar a coloração 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 a conclusão de 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
é umSystem.Management.Automation.OutputRendering
enum com os valores:ANSI
: As sequências de escape ANSI são sempre passadas como estão.Importante
Você deve usar o modo ANSI ao redirecionar a saída para um arquivo ou o pipeline que se destina a 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 seja apenas texto sem formatação. Em sessões remotas, se o host remoto estiver definido comoPlainText
, 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
$PSStyle.Background
membros e$PSStyle.Foreground
são cadeias de caracteres que contêm as sequências de escape ANSI para as 16 cores de console padrão.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 para especificar a
FromRgb()
cor de 24 bits. Há duas maneiras de chamar oFromRgb()
método.string FromRgb(byte red, byte green, byte blue) string FromRgb(int rgb)
Qualquer um dos exemplos a seguir define a cor do plano de fundo como a cor
Beige
de 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, detalhamento, 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 renderização de formataçã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
- Debug - formatação para mensagens de depuração
- TableHeader - formatação para cabeçalhos de tabela
- CustomTableHeaderLabel - formatação para cabeçalhos de tabela que são valores calculados
- 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 do provedor de comentários (adicionadas como um recurso experimental no PowerShell 7.4)
$PSStyle.Progress
Permite controlar a renderização da barra de exibição de progresso.- Estilo - Uma cadeia de caracteres ANSI definindo 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 - Um enum com valores
Minimal
eClassic
.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 isso como para terminais que oferecem suporte a$true
indicadores OSC.
Observação
Se o host não der suporte ao terminal virtual,
$PSStyle.Progress.View
será definido automaticamente comoClassic
.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 para diretórios
- SymbolicLink - Membro interno para especificar a cor para links simbólicos
- Executável - Membro interno para especificar a cor dos executáveis.
- Extensão - Use esse 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 de markdown - o cmdlet Show-Markdown exibe o conteúdo de um arquivo que contém texto de 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 Progresso da gravação
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 radical 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 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
Quando você inspeciona o conteúdo de 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
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
StringDecorated
tipo é adicionado para manipular cadeias de caracteres de escape ANSI. - A
string IsDecorated
propriedade boolean foi adicionada para retornar true quando a cadeia de caracteres contémESC
sequências deC1 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 sem formatação da cadeia de caracteres. - O
string ToString(bool Ansi)
método retorna a cadeia de caracteres ANSI incorporada bruta se oAnsi
parâmetro for true. 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 que contém 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