簡短描述
說明 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 - 關閉粗體
- Dim - 開啟 Dim （PowerShell 7.4 中新增）
- DimOff - 關閉 Dim 關閉 （PowerShell 7.4 中新增）
- 隱藏 - 開啟 [隱藏]
- 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 逸出序列一律會移除，使其只有純文本。 在遠端工作階段中，如果遠端主機設定為PlainText，輸出會先移除 ANSI 逸出序列，再將它傳回本機用戶端。Host：這是預設行為。 ANSI 逸出序列會從重新導向或管道輸出中移除。 如需詳細資訊，請參閱 重新導向輸出。
$PSStyle.Background和$PSStyle.Foreground成員是包含 16 種標準控制台色彩之 ANSI 逸出序列的字串。BlackBrightBlackWhiteBrightWhiteRedBrightRedMagentaBrightMagentaBlueBrightBlueCyanBrightCyanGreenBrightGreenYellowBrightYellow
這些值是可設定的，而且可以包含任意數目的 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 - 清單專案的格式設定
- ErrorAccent - 錯誤元數據的格式設定
- 錯誤 - 錯誤訊息的格式設定
- 警告 - 警告訊息的格式設定
- 詳細資訊 - 詳細資訊訊息的格式設定
- 偵 錯 - 偵錯訊息的格式設定
- TableHeader - 表格標頭的格式設定
- CustomTableHeaderLabel - 表格標頭的格式設定，這些標頭實際上不是物件上的屬性
- FeedbackName - 意見反應提供者名稱的格式設定（在 PowerShell 7.4 中新增為實驗性功能）
- FeedbackText - 意見反應訊息的格式設定（在 PowerShell 7.4 中新增為實驗性功能）
- FeedbackAction - 意見反應提供者建議動作的格式設定（在 PowerShell 7.4 中新增為實驗性功能）
$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 檔案副名的顏色。
以下範例展示了如何更改各種
FileInfo設定和特定副檔名的顏色。 顏色選擇是為了適合光線終端背景而設計。$PSStyle.FileInfo.Directory = $PSStyle.Background.FromRgb(0x2f6aff) + $PSStyle.Foreground.BrightWhite $PSStyle.FileInfo.SymbolicLink = $PSStyle.Foreground.Cyan $PSStyle.FileInfo.Executable = $PSStyle.Foreground.BrightMagenta $PSStyle.FileInfo.Extension['.ps1'] = $PSStyle.Foreground.Cyan $PSStyle.FileInfo.Extension['.ps1xml'] = $PSStyle.Foreground.Cyan $PSStyle.FileInfo.Extension['.psd1'] = $PSStyle.Foreground.Cyan $PSStyle.FileInfo.Extension['.psm1'] = $PSStyle.Foreground.Cyan
產生 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
在主機模式下重新導向輸出
根據預設， $PSStyle.OutputRendering 會設定為 [ 主機]。 ANSI 逸出序列會從重新導向或管道輸出中移除。
OutputRendering 僅適用於主機、 Out-File和 Out-String中的轉譯。 原生可執行文件的輸出不會受到影響。
PowerShell 7.2.6 已針對下列案例變更 和 Out-File 的行為Out-String：
- 當輸入對像是純字串時，不論 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 -
xterm-集$PSStyle.OutputRendering = PlainText
如果 $Env:NO_COLOR 存在，則會 $PSStyle.OutputRendering 設定為 PlainText。 如需NO_COLOR環境變數的詳細資訊
使用 $PSStyle from C#
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。 -
Length字串的 屬性會傳回沒有 ANSI 逸出序列之文字的長度。 - 方法
StringDecorated Substring(int contentLength)會傳回從索引 0 開始的子字串，最多到不是 ANSI 逸出序列一部分的內容長度。 這是表格格式設定的必要專案，以截斷字串並保留 ANSI 逸出序列，而不需要列印的字元空間。 - 方法
string ToString()會維持不變，並傳回字串的純文本版本。 - 如果 參數為
string ToString(bool Ansi)，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
