about_ANSI_Terminals

  • Artykuł

Krótki opis

Opisuje obsługę dostępnych sekwencji ucieczki ANSI w programie PowerShell.

Długi opis

Program PowerShell ma wiele funkcji, które obsługują używanie sekwencji ucieczki ANSI do kontrolowania renderowania danych wyjściowych w aplikacji terminalowej obsługującej program PowerShell.

Program PowerShell 7.2 dodał nową zmienną automatyczną, $PSStyleoraz zmiany aparatu programu PowerShell w celu obsługi danych wyjściowych tekstu ozdobionego anSI.

Obsługa terminalu ANSI

Funkcje ANSI zostały zaprojektowane tak, aby były zgodne z terminalami opartymi na architekturze xterm. Aby uzyskać więcej informacji, zobacz xterm w Wikipedii.

W systemie Windows 10 lub nowszym host konsoli systemu Windows jest zgodny z xterm. Aplikacja Terminal Windows jest również zgodna z architekturą xterm.

W systemie macOS domyślna aplikacja terminalowa jest zgodna z xterm.

W przypadku systemu Linux każda dystrybucja jest dostarczana z inną aplikacją terminalową. Zapoznaj się z dokumentacją dystrybucji, aby znaleźć odpowiednią aplikację terminalową.

$PSStyle

Zmienna ma następujące właściwości:

  • Reset — wyłącza wszystkie dekoracje
  • Blink — włącza miganie
  • BlinkOff — wyłącza miganie
  • Pogrubienie — włącza pogrubienie
  • BoldOff — wyłącza pogrubienie
  • Dim — włącza funkcję Dim (dodano w programie PowerShell 7.4)
  • DimOff — wyłącza funkcję Dim (dodano w programie PowerShell 7.4)
  • Ukryte — włącza funkcję Ukryte
  • HiddenOff — wyłącza opcję Ukryte
  • Odwrotnie — włącza odwrotnie
  • Odwróć — wyłącza
  • Kursywa — włącza kursywę
  • Kursywa — wyłącza kursywę
  • Podkreślenie — włącza podkreślenie
  • PodkreślenieOff — wyłącza podkreślenie
  • Przekreślenie — włącza przekreślenie
  • StrikethroughOff — wyłącza przekreślenie
  • OutputRendering — kontrolka podczas renderowania danych wyjściowych
  • Formatowanie — zagnieżdżony obiekt, który kontroluje domyślne formatowanie strumieni wyjściowych
  • Progress — zagnieżdżony obiekt, który kontroluje renderowanie pasków postępu
  • FileInfo — zagnieżdżony obiekt do kontrolowania kolorowania obiektów FileInfo .
  • Pierwszy plan — zagnieżdżony obiekt do kontrolowania kolorowania pierwszego planu
  • Tło — zagnieżdżony obiekt do kontrolowania kolorowania tła

Podstawowe elementy członkowskie zwracają ciągi sekwencji ucieczki ANSI mapowane na ich nazwy. Wartości są ustawiane w celu zezwolenia na dostosowywanie. Można na przykład zmienić pogrubienie na podkreślone. Nazwy właściwości ułatwiają tworzenie ciągów ozdobionych przy użyciu uzupełniania tabulacji:

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

Następujące elementy członkowskie kontrolują sposób lub kiedy jest używane formatowanie ANSI:

  • $PSStyle.OutputRenderingSystem.Management.Automation.OutputRendering to wyliczenie z wartościami:

    • ANSI: sekwencje ucieczki ANSI są zawsze przekazywane zgodnie z oczekiwaniami.

      Ważne

      Należy użyć trybu ANSI podczas przekierowywania danych wyjściowych do pliku lub potoku, który ma być wykonywany podrzędnie. Dzięki temu dane wyjściowe nie są zmieniane. Użycie dowolnego innego trybu zmienia dane wyjściowe przez usunięcie sekwencji ucieczki ANSI, co może zmienić zachowanie wykonywania.

    • PlainText: Sekwencje ucieczki ANSI są zawsze rozdzielone tak, aby był tylko zwykły tekst. W sesjach zdalnych, jeśli host zdalny jest ustawiony na PlainText, dane wyjściowe są pozbawione sekwencji ucieczki ANSI przed wysłaniem go z powrotem do klienta lokalnego.

    • Host: jest to zachowanie domyślne. Sekwencje ucieczki ANSI są usuwane z przekierowanych lub potokowych danych wyjściowych. Aby uzyskać więcej informacji, zobacz Przekierowywanie danych wyjściowych.

  • Elementy $PSStyle.Background członkowskie i $PSStyle.Foreground to ciągi zawierające sekwencje ucieczki ANSI dla 16 standardowych kolorów konsoli.

    • Black
    • BrightBlack
    • White
    • BrightWhite
    • Red
    • BrightRed
    • Magenta
    • BrightMagenta
    • Blue
    • BrightBlue
    • Cyan
    • BrightCyan
    • Green
    • BrightGreen
    • Yellow
    • BrightYellow

    Wartości są ustawiane i mogą zawierać dowolną liczbę sekwencji ucieczki ANSI. Istnieje również metoda określania FromRgb() koloru 24-bitowego. Istnieją dwa sposoby wywoływania FromRgb() metody.

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

    Jeden z poniższych przykładów ustawia kolor tła na 24-bitowy kolor Beige.

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

  • $PSStyle.Formatting jest obiektem zagnieżdżonym do kontrolowania domyślnego formatowania debugowania, błędu, pełnej, komunikatów ostrzegawczych oraz nagłówków listy i tabeli. Możesz również kontrolować atrybuty, takie jak pogrubienie i podkreślenie. Zastępuje $Host.PrivateData ona jako sposób zarządzania kolorami na potrzeby renderowania formatowania. $Host.PrivateData nadal istnieje w przypadku zgodności z poprzednimi wersjami, ale nie jest połączony z usługą $PSStyle.Formatting. $PSStyle.Formatting ma następujących członków:

    • FormatAccent — formatowanie elementów listy
    • ErrorAccent — formatowanie metadanych błędów
    • Błąd — formatowanie komunikatów o błędach
    • Ostrzeżenie — formatowanie komunikatów ostrzegawczych
    • Pełne — formatowanie pełnych komunikatów
    • Debugowanie — formatowanie komunikatów debugowania
    • TableHeader — formatowanie nagłówków tabeli
    • CustomTableHeaderLabel — formatowanie nagłówków tabeli, które są wartościami obliczeniowymi
    • FeedbackName — formatowanie nazwy dostawcy opinii (dodane jako funkcja eksperymentalna w programie PowerShell 7.4)
    • FeedbackText — formatowanie komunikatów opinii (dodane jako funkcja eksperymentalna w programie PowerShell 7.4)
    • FeedbackAction — formatowanie sugerowanych akcji dostawcy opinii (dodane jako funkcja eksperymentalna w programie PowerShell 7.4)

  • $PSStyle.Progress umożliwia kontrolowanie renderowania paska widoku postępu.

    • Styl — ciąg ANSI ustawia styl renderowania.
    • MaxWidth — ustawia maksymalną szerokość widoku. Wartość domyślna to 120. Wartość minimalna to 18.
    • View — wyliczenie z wartościami Minimal i Classic. Classic to istniejące renderowanie bez zmian. Minimal jest renderowaniem minimalnym w jednym wierszu. Wartość domyślna to Minimal.
    • UseOSCIndicator — wartości domyślne: $false. Ustaw tę wartość $true dla terminali obsługujących wskaźniki OSC.

    Uwaga

    Jeśli host nie obsługuje terminalu wirtualnego, $PSStyle.Progress.View zostanie automatycznie ustawiony na Classicwartość .

    Poniższy przykład ustawia styl renderowania na minimalny pasek postępu.

    $PSStyle.Progress.View = 'Minimal'

  • $PSStyle.FileInfo jest obiektem zagnieżdżonym w celu kontrolowania kolorowania obiektów FileInfo .

    • Katalog — wbudowany element członkowski określający kolor katalogów
    • SymbolLink — wbudowany element członkowski określający kolor łączy symbolicznych
    • Wykonywalny — wbudowany element członkowski określający kolor plików wykonywalnych .
    • Rozszerzenie — ten element członkowski służy do definiowania kolorów dla różnych rozszerzeń plików. Element członkowski rozszerzenia zawiera wstępnie rozszerzenia dla plików archiwum i programu PowerShell.

Polecenia cmdlet generujące dane wyjściowe ANSI

Przekierowywanie danych wyjściowych w Host trybie

Domyślnie $PSStyle.OutputRendering jest ustawioną wartością Host. Sekwencje ucieczki ANSI są usuwane z przekierowanych lub potokowych danych wyjściowych.

Funkcja OutputRendering dotyczy tylko renderowania w hostach, Out-Filei Out-String. Nie ma to wpływu na dane wyjściowe z natywnych plików wykonywalnych.

Program PowerShell 7.2.6 zmienił zachowanie programu Out-File i Out-String w następujących scenariuszach:

  • Gdy obiekt wejściowy jest czystym ciągiem, te polecenia cmdlet zachowują ciąg bez zmian niezależnie od ustawienia OutputRendering .
  • Gdy obiekt wejściowy musi mieć zastosowany widok formatowania, te polecenia cmdlet zachowują lub usuwają sekwencje ucieczki z ciągów wyjściowych formatowania na podstawie ustawienia OutputRendering .

Jest to zmiana powodująca niezgodność w tych poleceniach cmdlet w porównaniu z programem PowerShell 7.2.

Funkcja OutputRendering nie ma zastosowania do danych wyjściowych z procesu hosta programu PowerShell, na przykład po uruchomieniu pwsh z wiersza polecenia i przekierowaniu danych wyjściowych.

W poniższym przykładzie program PowerShell jest uruchamiany w systemie Linux z programu bash. Polecenie Get-ChildItem cmdlet tworzy tekst ozdobiony anSI. Ponieważ przekierowanie występuje w bash procesie, poza hostem programu PowerShell, dane wyjściowe nie mają wpływu na dane wyjściowe OutputRendering.

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

Podczas inspekcji zawartości zobaczysz out.txt sekwencje ucieczki ANSI.

Natomiast w przypadku przekierowania w sesji programu PowerShell funkcja OutputRendering wpływa na przekierowane dane wyjściowe.

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

Podczas inspekcji zawartości nie out.txt ma sekwencji ucieczki ANSI.

Wyłączanie danych wyjściowych ANSI

Obsługę sekwencji ucieczki ANSI można wyłączyć przy użyciu zmiennych środowiskowych TERM lub NO_COLOR .

Następujące wartości $env:TERM zmiany zachowania w następujący sposób:

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

Jeśli $env:NO_COLOR istnieje, $PSStyle.OutputRendering zostanie ustawiona wartość PlainText. Aby uzyskać więcej informacji na temat zmiennej środowiskowej NO_COLOR , zobacz https://no-color.org/.

Używanie $PSStyle z języka C#

Deweloperzy języka C# mogą uzyskiwać dostęp PSStyle jako pojedynczy, jak pokazano w poniższym przykładzie:

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

PSStyle istnieje w przestrzeni nazw System.Management.Automation.

Aparat programu PowerShell zawiera następujące zmiany:

  • System formatowania programu PowerShell jest aktualizowany w celu poszanowania $PSStyle.OutputRenderingelementu .
  • Typ StringDecorated jest dodawany do obsługi ciągów ucieczki ANSI.
  • Właściwość string IsDecorated logiczna została dodana, aby zwrócić wartość true , gdy ciąg zawiera ESC lub C1 CSI sekwencje znaków.
  • Właściwość Length ciągu zwraca długość tekstu bez sekwencji ucieczki ANSI.
  • Metoda StringDecorated Substring(int contentLength) zwraca podciąg rozpoczynający się od indeksu 0 do długości zawartości, która nie jest częścią sekwencji ucieczki ANSI. Jest to potrzebne do formatowania tabeli w celu obcinania ciągów i zachowywania sekwencji ucieczki ANSI, które nie zajmują miejsca na drukowalnym znaku.
  • Metoda string ToString() pozostaje taka sama i zwraca wersję ciągu w postaci zwykłego tekstu.
  • Metoda string ToString(bool Ansi) zwraca nieprzetworzony ciąg osadzony ANSI, jeśli Ansi parametr ma wartość true. W przeciwnym razie zwracana jest wersja zwykłego tekstu z usuniętymi sekwencjami ucieczki ANSI.
  • Metoda FormatHyperlink(string text, uri link) zwraca ciąg zawierający sekwencje ucieczki ANSI używane do dekorowania hiperlinków. Niektóre hosty terminali, takie jak Terminal Windows, obsługują ten znacznik, co sprawia, że renderowany tekst można kliknąć w terminalu.

Metody statyczne klasy PSStyle

Program PowerShell 7.4 dodaje do klasy trzy nowe metody [System.Management.Automation.PSStyle] statyczne.

[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)

Te metody umożliwiają konwertowanie wartości ConsoleColor na sekwencje ucieczki ANSI dla kolorów pierwszego planu i tła lub kombinacji obu tych elementów.

W poniższych przykładach pokazano sekwencje ucieczki ANSI utworzone przez te metody.

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

Zobacz też