通过

about_ANSI_Terminals

  • 项目

简短说明

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

长说明

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

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

ANSI 终端支持

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

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

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

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

$PSStyle

变量具有以下属性：

  • 重置 - 关闭所有修饰
  • 闪烁 - 打开闪烁
  • BlinkOff - 关闭闪烁
  • 粗体 - 打开粗体
  • BoldOff - 关闭粗体
  • 隐藏 - 打开隐藏
  • HiddenOff - 关闭隐藏
  • 反向 - 打开反向
  • ReverseOff - 关闭 Reverse
  • 斜体 - 打开斜体
  • ItalicOff - 关闭斜体
  • 下划线 - 打开下划线
  • UnderlineOff - 关闭下划线
  • 删除线 - 打开删除线
  • StrikethroughOff - 关闭删除线
  • OutputRendering - 控制何时使用输出呈现
  • 格式设置 - 控制输出流的默认格式的嵌套对象
  • 进度 - 控制进度栏呈现的嵌套对象
  • FileInfo - 用于控制 FileInfo 对象着色的嵌套对象。
  • 前景 - 用于控制前景色的嵌套对象
  • 背景 - 用于控制背景着色的嵌套对象

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

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

以下成员控制 ANSI 格式的使用方式或时间：

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

    • ANSI：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 - 错误元数据的格式设置
    • 错误 - 错误消息的格式设置
    • 警告 - 警告消息的格式设置
    • 详细 - 详细消息的格式设置
    • 调试 - 调试消息的格式设置

  • $PSStyle.Progress 允许你控制进度视图栏呈现。

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

    注意

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

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

    $PSStyle.Progress.View = 'Minimal'

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

    • 目录 - 用于指定目录颜色的内置成员
    • SymbolicLink - 用于指定符号链接颜色的内置成员
    • 可执行文件 - 用于指定可执行文件颜色的内置成员。
    • 扩展名 - 使用此成员为不同的文件扩展名定义颜色。 “扩展”成员预先包括存档和 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 - 使用 $PSStyle.Progress管理 ANSI 输出，如上所述。 有关详细信息，请参阅 Write-Progress

在 Host 模式下重定向输出

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

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

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

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

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

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

在以下示例中，PowerShell 从 bash在 Linux 上运行。 cmdlet Get-ChildItem 生成 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 终端）支持此标记，这使得呈现的文本在终端中可单击。

另请参阅