关于 ANSI 终端

简短描述

描述 PowerShell 中对 ANSI 转义序列的可用支持。

详细描述

PowerShell 具有许多功能，支持使用 ANSI 转义序列来控制托管 PowerShell 的终端应用程序中的输出呈现。

PowerShell 7.2 添加了一个新的自动变量 $PSStyle，并对 PowerShell 引擎进行了更改以支持 ANSI 修饰文本的输出。

ANSI 终端支持

ANSI 功能旨在与基于 xterm 的终端兼容。有关详细信息，请参阅 Wikipedia 中的 xterm。

在 Windows 10 及更高版本上，Windows 控制台主机与 xterm 兼容。 Windows 终端应用程序也与 xterm 兼容。

在 macOS 上，默认终端应用程序与 xterm 兼容。

对于 Linux，每个发行版都附带不同的终端应用程序。请查阅您的发行版的文档以找到合适的终端应用程序。

$PS样式

该变量具有以下属性：

• 重置 - 关闭所有装饰
• 闪烁 - 打开闪烁
• BlinkOff - 关闭闪烁
• 粗体 - 打开粗体
• BoldOff - 关闭粗体
• Dim - 打开 Dim（在 PowerShell 7.4 中添加）
• DimOff - 关闭 Dim（在 PowerShell 7.4 中添加）
• 隐藏 - 打开隐藏
• HiddenOff - 关闭隐藏
• 反向 - 打开反向
• ReverseOff - 关闭反向
• 斜体 - 打开斜体
• ItalicOff - 关闭斜体
• 下划线 - 打开下划线
• UnderlineOff - 关闭下划线
• 删除线 - 打开删除线
• StrikethroughOff - 关闭删除线
• OutputRendering - 控制何时使用输出渲染
• Formatting - 控制输出流默认格式的嵌套对象
• Progress - 控制进度条渲染的嵌套对象
• FileInfo - 用于控制 FileInfo 对象着色的嵌套对象。
• 前景 - 用于控制前景色的嵌套对象
• 背景 - 用于控制背景颜色的嵌套对象

基本成员返回映射到其名称的 ANSI 转义序列字符串。这些值可设置以允许定制。例如，您可以将粗体更改为下划线。属性名称使您可以更轻松地使用制表符补全创建修饰字符串：

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

以下成员控制如何或何时使用 ANSI 格式：

• $PSStyle.OutputRendering 是一个 System.Management.Automation.OutputRendering 枚举，其值如下：

  • ANSI：ANSI 转义序列始终按原样传递。

    这很重要

    将输出重定向到要在下游执行的文件或管道时，应使用 ANSI 模式。这确保了输出不被改变。使用任何其他模式都会通过删除 ANSI 转义序列来改变输出，这可能会改变执行行为。

• PlainText：ANSI 转义序列始终被删除，因此它只是纯文本。在远程会话中，如果远程主机设置为 PlainText，则输出将在发送回本地客户端之前去除 ANSI 转义序列。

• Host：这是默认行为。 ANSI 转义序列已从重定向或管道输出中删除。有关详细信息，请参阅重定向输出。

Black

BrightBlack

White

BrightWhite

Red

BrightRed

Magenta

BrightMagenta

Blue

BrightBlue

Cyan

BrightCyan

Green

BrightGreen

Yellow

BrightYellow

这些值是可设置的，并且可以包含任意数量的 ANSI 转义序列。还有一个 FromRgb() 方法来指定 24 位颜色。有两种方法可以调用 FromRgb() 方法。

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

以下任一示例将背景颜色设置为 24 位颜色 Beige。

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

笔记

如果主机不支持虚拟终端，$PSStyle.Progress.View 会自动设置为 Classic。

以下示例将渲染样式设置为最小进度条。

$PSStyle.Progress.View = 'Minimal'

生成 ANSI 输出的 cmdlet

• markdown cmdlet - Show-Markdown cmdlet 显示包含 markdown 文本的文件的内容。输出使用 ANSI 序列呈现以表示不同的样式。您可以使用 Get-MarkdownOption 和 Set-MarkdownOption cmdlet 管理样式的定义。
• PSReadLine cmdlet - PSReadLine 模块使用 ANSI 序列对命令行上的 PowerShell 语法元素进行着色。可以使用 Get-PSReadLineOption 和 Set-PSReadLineOption 管理颜色。
• Get-Error - Get-Error cmdlet 返回 Error 对象的详细视图，并进行格式化以使其更易于阅读。
• Select-String - 从 PowerShell 7.0 开始，Select-String 使用 ANSI 序列突出显示输出中的匹配模式。
• Write-Progress - ANSI 输出使用 $PSStyle.Progress 进行管理，如上所述。有关详细信息，请参阅写入进度

在 Host 模式下重定向输出

默认情况下，$PSStyle.OutputRendering 设置为Host。 ANSI 转义序列已从重定向或管道输出中删除。

OutputRendering 仅适用于主机、Out-File 和 Out-String 中的渲染。本机可执行文件的输出不受影响。

PowerShell 7.2.6 更改了以下场景的 Out-File 和 Out-String 行为：

• 当输入对象是纯字符串时，这些 cmdlet 会保持字符串不变，无论 OutputRendering 设置如何。
• 当输入对象需要应用格式化视图时，这些 cmdlet 会根据 OutputRendering 设置从格式化输出字符串中保留或删除转义序列。

与 PowerShell 7.2 相比，这是这些 cmdlet 中的重大更改。

OutputRendering 不适用于 PowerShell 主机进程的输出，例如，当您从命令行运行 pwsh 并重定向输出时。

在以下示例中，PowerShell 在 Linux 上通过 bash 运行。 Get-ChildItem cmdlet 生成 ANSI 修饰的文本。由于重定向发生在 PowerShell 主机外部的 bash 进程中，因此输出不受 OutputRendering 的影响。

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

当您检查 out.txt 的内容时，您会看到 ANSI 转义序列。

相比之下，当在 PowerShell 会话中发生重定向时，OutputRendering 会影响重定向的输出。

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

当您检查 out.txt 的内容时，没有 ANSI 转义序列。

禁用 ANSI 输出

可以使用 TERM 或 NO_COLOR 环境变量关闭对 ANSI 转义序列的支持。

以下 $env:TERM 值会更改行为，如下所示：

• dumb - 设置$Host.UI.SupportsVirtualTerminal=$false
• xterm-mono - 设置 $PSStyle.OutputRendering=PlainText
• xtermm - 设置 $PSStyle.OutputRendering=PlainText

如果 $env:NO_COLOR 存在，则 $PSStyle.OutputRendering 设置为 PlainText。有关 NO_COLOR 环境变量的更多信息，请参阅 https://no-color.org/。

在 C# 中使用 $PSStyle

C# 开发人员可以将 PSStyle 作为单例进行访问，如以下示例所示：

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

PSStyle 存在于 System.Management.Automation 命名空间中。

PowerShell 引擎包括以下更改：

• PowerShell 格式化系统已更新，以遵循 $PSStyle.OutputRendering。
• 添加了 StringDecolated 类型来处理 ANSI 转义字符串。
• 添加了 string IsDecolated 布尔属性，以便在字符串包含 ESC 或 C1 CSI 字符序列时返回 true。
• 字符串的 Length 属性返回不带 ANSI 转义序列的文本的长度。
• StringDecolated Substring(int contentLength) 方法返回一个从索引 0 开始直到内容长度不属于 ANSI 转义序列的子字符串。这是表格式化所必需的，以截断字符串并保留不占用可打印字符空间的 ANSI 转义序列。
• string ToString() 方法保持不变并返回字符串的纯文本版本。
• 如果 Ansi 参数为 true，则 string ToString(bool Ansi) 方法将返回原始 ANSI 嵌入字符串。否则，将返回删除了 ANSI 转义序列的纯文本版本。
• FormatHyperlink(string text, uri link) 方法返回一个字符串，其中包含用于修饰超链接的 ANSI 转义序列。某些终端主机（例如 Windows 终端）支持此标记，这使得渲染的文本可以在终端中单击。

PSStyle 类的静态方法

PowerShell 7.4 向 [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)

这些方法提供了一种将 ConsoleColor 值转换为前景色和背景色或两者组合的 ANSI 转义序列的方法。

以下示例显示了这些方法生成的 ANSI 转义序列。

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

参见

• about_实验_功能
• 使用实验功能