about_ANSI_Terminals

  • 项目

简短说明

介绍 PowerShell 中可用于 ANSI 转义序列的支持。

长说明

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

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

ANSI 终端支持

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

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

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

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

$PSStyle

该变量具有以下属性：

  • Reset - 关闭所有修饰
  • Blink - 打开闪烁
  • BlinkOff - 关闭闪烁
  • Bold - 打开粗体
  • BoldOff - 关闭粗体
  • Hidden - 打开隐藏
  • HiddenOff - 关闭隐藏
  • Reverse - 打开反转
  • ReverseOff - 关闭反转
  • Italic - 打开斜体
  • ItalicOff - 关闭斜体
  • Underline - 打开下划线
  • UnderlineOff - 关闭下划线
  • Strikethrough - 打开删除线
  • StrikethroughOff - 关闭删除线
  • OutputRendering - 控制何时使用输出渲染
  • Formatting - 控制输出流默认格式的嵌套对象
  • Progress - 控制进度条渲染的嵌套对象
  • FileInfo - 用于控制 FileInfo 对象着色的嵌套对象。
  • Foreground - 用于控制前景着色的嵌套对象
  • Background - 用于控制背景着色的嵌套对象

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

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

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

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

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

      重要

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

    • PlainText：ANSI 转义序列始终被剥离，因此它只是纯文本。

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

  • $PSStyle.Background 和 $PSStyle.Foreground 成员是包含 16 种标准控制台颜色的 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.Formatting 是一个嵌套对象，用于控制调试、错误、详细、警告消息以及列表和表标头的默认格式。 还可以控制粗体和下划线等属性。 它取代了 $Host.PrivateData，作为管理格式化渲染颜色的方式。 $Host.PrivateData 继续存在以实现向后兼容性，但不连接到 $PSStyle.Formatting。 $PSStyle.Formatting 包括以下成员：

    • FormatAccent - 列表项的格式设置
    • TableHeader - 表标头的格式设置
    • ErrorAccent - 错误元数据的格式设置
    • Error - 错误消息的格式设置
    • Warning - 警告消息的格式
    • Verbose - 详细消息的格式设置
    • Debug - 调试消息的格式设置

  • $PSStyle.Progress 可以控制进度视图栏呈现。

    • Style - 设置呈现样式的 ANSI 字符串。
    • MaxWidth - 设置视图的最大宽度。 默认为 120。 最小值为 18。
    • View - 具有 Minimal 和 Classic 值的枚举。 Classic 为现有呈现，无更改。 Minimal 为单行最小呈现。 Minimal 是默认值。
    • UseOSCIndicator - 默认为 $false。 将此项设置为支持 OSC 指示器的终端 $true。

    注意

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

    下面的示例将呈现样式设置为最小进度栏。

    $PSStyle.Progress.View = 'Minimal'

  • $PSStyle.FileInfo 是一个嵌套对象，用于控制 fileInfo 对象的着色。

    • Directory - 用于指定目录颜色的内置成员
    • SymbolicLink - 用于指定符号链接颜色的内置成员
    • Executable - 用于指定可执行文件颜色的内置成员。
    • Extension - 使用此成员定义不同文件扩展名的颜色。 “扩展”成员预先包括存档和 PowerShell 文件的扩展。

生成 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 管理，如上所述。 有关详细信息，请参阅 Write-Progress

在 Host 模式下重定向输出

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

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

PowerShell 7.2.6 更改了以下方案中 Out-File 和 Out-String 的行为：

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

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

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

在以下示例中，PowerShell 在 Linux 上通过 bash 运行。 Get-ChildItem cmdlet 生成 ANSI 修饰的文本。 由于重定向发生在 bash 进程中，因此在 PowerShell 主机外部，输出不受 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。
  • 添加了 StringDecorated 类型来处理 ANSI 转义字符串。
  • 添加了 string IsDecorated 布尔属性，以便在字符串包含 ESC 或 C1 CSI 字符序列时返回 true。
  • 字符串的 Length 属性会返回没有 ANSI 转义序列的文本的长度。
  • StringDecorated Substring(int contentLength) 方法会返回一个子字符串，该字符串从索引 0 处开始，一直到超出 ANSI 转义序列的内容长度。 如果表格式设置要截断字符串，并保留未占用可打印字符空间的 ANSI 转义序列，则需要使用此方法。
  • string ToString() 方法保持不变，并返回字符串的纯文本版本。
  • Ansi 参数为 true 时，string ToString(bool Ansi) 方法会返回原始 ANSI 嵌入字符串。 否则，返回已删除 ANSI 转义序列的纯文本版本。
  • FormatHyperlink(string text, uri link) 会返回一个字符串，其中包含用于修饰超链接的 ANSI 转义序列。 某些终端主机（如 Windows 终端）支持此标记，这使得呈现的文本在终端中可单击。

另请参阅