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

變數具有下列屬性：

  • 重設 - 關閉所有裝飾
  • 閃爍 - 開啟閃爍
  • BlinkOff - 關閉閃爍
  • 粗體 - 開啟粗體
  • BoldOff - 關閉粗體
  • 隱藏 - 開啟 [隱藏]
  • HiddenOff - 關閉隱藏
  • 反向 - 開啟反向
  • ReverseOff - 關閉反向
  • 斜體 - 將斜體 開啟
  • ItalicOff - 關閉斜體
  • 底線 - 開啟底線
  • UnderlineOff - 關閉底線
  • 刪除線 - 翻轉罷工
  • 刪除線關閉 - 關閉罷工
  • OutputRendering - 控制何時使用輸出轉譯
  • 格式化 - 巢狀物件，控制輸出數據流的預設格式設定
  • Progress - 控制進度列轉譯的巢狀物件
  • FileInfo - 巢狀物件，可控制 FileInfo 物件的著色。
  • 前景 - 用來控制前景著色的巢狀物件
  • 背景 - 用來控制背景著色的巢狀物件

基底成員會傳回對應至其名稱的 ANSI 逸出序列字串。 這些值可設定為允許自定義。 例如，您可以將粗體變更為底線。 屬性名稱可讓您更輕鬆地使用 Tab 鍵自動完成建立裝飾字串：

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

下列成員會控制如何使用 ANSI 格式設定的方式或時機：

  • $PSStyle.OutputRenderingSystem.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 物件的著色。

    • 目錄 - 內建成員，可指定目錄的色彩
    • 符號連結 - 內建成員，可指定符號連結的色彩
    • 可執行檔 - 內建成員，可指定可執行檔的色彩。
    • 擴充 功能 - 使用此成員來定義不同擴展名的色彩。 延伸 模組 成員預先包含封存和 PowerShell 檔案的延伸模組。

    注意

    $PSStyle.FileInfo 只有在啟用實驗性功能時 PSAnsiRenderingFileInfo 才能使用。 如需詳細資訊，請參閱about_Experimental_Features和使用實驗性功能。

    在 PowerShell 7.3 中 PSAnsiRenderingFileInfo ，此功能預設成為主流且可供使用。

產生 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.ProgressANSI 輸出，如上所述。 如需詳細資訊，請參閱 Write-Progress

以 Host 模式重新導向輸出

根據預設， $PSStyle.OutputRendering 會設定為 [ 主機]。 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'

當您檢查沒有 ANSI 逸出序列的內容 out.txt 時。

停用 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() 會維持不變，並傳回字串的純文本版本。
  • 如果 參數為 true，Ansi此方法string ToString(bool Ansi)會傳回原始 ANSI 內嵌字串。 否則，會傳回已移除 ANSI 逸出序列的純文字版本。
  • 方法會 FormatHyperlink(string text, uri link) 傳回字串，其中包含用來裝飾超連結的 ANSI 逸出序列。 某些終端機主機，例如 Windows 終端機，支援此標記，讓轉譯的文字在終端機中可點選。

另請參閱