JSON-Fragmenterweiterungen in Windows Terminal

JSON-Fragmenterweiterungen sind Codeausschnitte von JSON, die Anwendungsentwickler schreiben können, um den Einstellungen von Benutzern neue Profile hinzuzufügen oder sogar bestimmte vorhandene Profile zu ändern. Verwenden Sie sie, um den Einstellungen der Benutzer neue Farbschemas hinzuzufügen.

Struktur der JSON-Dateien

Teilen Sie die JSON-Datei in zwei Listen auf: eine für Profile und eine für Schemas. Hier ist ein Beispiel für eine JSON-Datei, die ein neues Profil hinzufügt, ein vorhandenes Profil ändert und ein neues Farbschema erstellt:

{
  "profiles": [
    {
      // update a profile by using its GUID
      "updates": "{2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}",
      "fontSize": 16,
      "fontWeight": "thin"
    },
    {
      // create a new profile
      "name": "Cool Profile",
      "commandline": "powershell.exe",
      "antialiasingMode": "aliased",
      "fontWeight": "bold",
      "colorScheme": "Postmodern Tango Light"
    }
  ],
  "schemes": [
    {
      // create a new color scheme
      "name": "Postmodern Tango Light",
      "black": "#0C0C0C",
      "red": "#C50F1F",
      "green": "#13A10E",
      "yellow": "#C19C00",
      "blue": "#0037DA",
      "purple": "#881798",
      "cyan": "#3A96DD",
      "white": "#CCCCCC",
      "brightBlack": "#767676",
      "brightRed": "#E74856",
      "brightGreen": "#16C60C",
      "brightYellow": "#F9F1A5",
      "brightBlue": "#3B78FF",
      "brightPurple": "#B4009E",
      "brightCyan": "#61D6D6",
      "brightWhite": "#F2F2F2"
    }
  ]
}

Das erste Element in der "profiles" Liste aktualisiert ein vorhandenes Profil. Es identifiziert das Profil, das es über die für das "updates" Feld bereitgestellte GUID aktualisieren möchte (details zum Abrufen der GUID finden Sie im nächsten Abschnitt). Das zweite Element in dieser Liste erstellt ein neues Profil namens "Cool Profile".

In der "schemes" Liste wird ein neues Farbschema namens "Postmodern Tango Light" definiert. Sie können in Ihrer Einstellungsdatei oder in dieser JSON-Datei selbst auf dieses Farbschema verweisen (beachten Sie, dass "Cool Profile" dieses neu definierte Farbschema verwendet).

Wenn Sie nur Profile hinzufügen oder ändern möchten, ohne Farbschemas hinzuzufügen oder umgekehrt, schließen Sie nur die relevante Liste ein, und lassen Sie die andere Liste weg.

Hinweis

Wenn Sie beabsichtigen, PowerShell zum Generieren von Fragmenten zu verwenden, verwenden Sie -Encoding Utf8Folgendes:

# BAD: PowerShell uses UTF16LE by default
Write-Output $fragmentJson > $fragmentPath

# GOOD: Uses UTF8, so Terminal can read this
Write-Output $fragmentJson | Out-File $fragmentPath -Encoding Utf8

Wenn Sie VS Code verwenden, um den JSON-Code zu bearbeiten, ist UTF8 die Standardeinstellung, sie können aber in der unteren Statusleiste bestätigt werden.

Profil-GUIDs

Wie bereits erwähnt, sind Profil-GUIDs eine Möglichkeit zum Verweisen auf Profile und ermöglichen es Benutzern, sie zu aktualisieren und zu erweitern, ohne sich gedanken über Standort- oder Namensänderungen zu machen. Sie können nur die Standardprofile, die Eingabeaufforderung und PowerShell sowie dynamische Profile über Fragmente ändern. Die Bereitstellung einer GUID ist optional, wird jedoch dringend empfohlen.

Der UUID-Generator von Version 5 erstellt die GUIDs und unterstützt die BOM-less UTF-16LE-Codierung.

Die Namespace-GUID für Windows Terminal im Falle von Profilen, die von Plug-Ins und Fragmenten erstellt werden, lautet {f65ddb7e-706b-4499-8a50-40313caf510a}. Vom Windows Terminal Team erstellte Profile verwenden eine separate GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Diese Trennung disambiguiert Profile, die vom Windows Terminal Team erstellt wurden, aus Profilen, die von Plug-Ins oder Fragmenten erstellt wurden, sodass sie niemals versehentlich kollidieren.

Ermitteln der GUID eines vorhandenen Profils

Um die GUID eines zu aktualisierenden Profils zu ermitteln, überlegen Sie, welche Art von Profil es ist:

Ein Profil, das von einem Drittanbieter geliefert und an einem standardmäßigen Windows-Terminal-Fragment-Speicherort gespeichert ist, erfordert die Profil- und Fragment-Namespace-GUID {f65ddb7e-706b-4499-8a50-40313caf510a}, die Anwendungs-Namespace-GUID und den Profilnamen. Für ein Profilfragment mit dem Namen "Git Bash", das von der Anwendung "Git" bereitgestellt wird, lautet {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}die generierte GUID.

Ein von Windows Terminal automatisch generiertes Profil erfordert die interne Windows-Terminal-GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} und den Profilnamen. Für ein während der WSL-Installation automatisch generiertes Profil mit dem Namen 'Ubuntu' ist die resultierende GUID {2c4de342-38b7-51cf-b940-2309a097f518}. Im Gegensatz zum vorherigen Fragmentbeispiel ist kein Anwendungsname beteiligt.

Generieren einer neuen Profil-GUID

Verwenden Sie zum Generieren einer GUID für ein völlig neues Profil vor der Verteilung das folgende Python 3-Beispiel. Es generiert eine GUID basierend auf der GUID des Profils und des Fragment-Namespace für ein Profil namens "Git Bash", das in einem standardmäßigen Windows Terminal Fragments-Ordner unter dem Anwendungsnamen "Git" gespeichert ist und praktisch mit der Plausibilitätsprüfung übereinstimmt.

import uuid

# The Windows Terminal namespace GUID for custom profiles & fragments
terminalNamespaceGUID = uuid.UUID("{f65ddb7e-706b-4499-8a50-40313caf510a}")

# The Application Namespace GUID
appNamespaceGUID = uuid.uuid5(terminalNamespaceGUID, "Git".encode("UTF-16LE").decode("ASCII"))

# Calculate the example GUID for the 'Git Bash' profile
profileGUID = uuid.uuid5(appNamespaceGUID, "Git Bash".encode("UTF-16LE").decode("ASCII"))

# Output the GUID as Windows Terminal expects it (enclosed in curly brackets)
print(f"{{{profileGUID}}}")

Berechnen einer GUID für ein integriertes Profil

Verwenden Sie zum Berechnen einer GUID für ein integriertes Profil, z. B. die automatisch generierten WSL-Profile, das folgende Python 3-Beispiel. Es berechnet eine GUID basierend auf der Windows Terminal-Namespace-GUID für ein Profil namens "Ubuntu", das automatisch für die WSL-Verteilung generiert wurde, bequem mit der Sanity-Prüfung übereinstimmen.

import uuid

# The Windows Terminal namespace GUID automatically generated profiles
terminalNamespaceGUID = uuid.UUID("{2bde4a90-d05f-401c-9492-e40884ead1d8}")

# Calculate the example GUID for the 'Git Bash' profile
profileGUID = uuid.uuid5(terminalNamespaceGUID, "Ubuntu".encode("UTF-16LE").decode("ASCII"))

# Output the GUID as Windows Terminal expects it (enclosed in curly brackets)
print(f"{{{profileGUID}}}")

Mindestanforderungen für Einstellungen, die mit Fragmenten hinzugefügt wurden

Einige minimale Einschränkungen gelten für das, was Sie mithilfe von JSON-Fragmenten zu Benutzereinstellungen hinzufügen können:

Für neue Profile, die über Fragmente hinzugefügt werden, muss das neue Profil einen Namen für sich selbst definieren.
Für neue Farbschemas, die durch Fragmente hinzugefügt werden, muss das neue Farbschema einen Namen für sich selbst definieren und jede Farbe in der Farbtabelle definieren (d. a. die Farben "schwarz" durch "brightWhite" im vorherigen Beispielbild).

Speicherort der JSON-Fragmentdateien

Der Speicherort zum Platzieren der JSON-Fragmentdateien variiert je nach Installationsmethode der Anwendung, die sie hinzufügt.

Microsoft Store-Anwendungen

Bei Anwendungen, die über den Microsoft Store (oder ähnlich) installiert sind, muss die Anwendung sich selbst als App-Erweiterung deklarieren. Erfahren Sie mehr über das Erstellen und Hosten einer App-Erweiterung. Der erforderliche Abschnitt wird hier repliziert. Die Appxmanifest-Datei des Pakets muss Folgendes enthalten:

<Package
  ...
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
  IgnorableNamespaces="uap uap3 mp">
  ...
    <Applications>
      <Application Id="App" ... >
        ...
        <Extensions>
          ...
          <uap3:Extension Category="windows.appExtension">
            <uap3:AppExtension Name="com.microsoft.windows.terminal.settings"
                               Id="<id>"
                               PublicFolder="Public">
            </uap3:AppExtension>
          </uap3:Extension>
        </Extensions>
      </Application>
    </Applications>
    ...
</Package>

Wichtige Punkte, die Sie beachten müssen:

Das "Name" Feld muss auf com.microsoft.windows.terminal.settings gesetzt werden, damit Windows Terminal die Erweiterung erkennen kann.
Das "Id" Feld kann wie gewünscht ausgefüllt werden.
Das "PublicFolder" Feld sollte den Namen des Ordners relativ zum Paketstamm aufweisen, in dem Sie die JSON-Dateien speichern (dieser Ordner wird normalerweise als "Öffentlich" bezeichnet, kann aber etwas anderes benannt werden).
Erstellen Sie im öffentlichen Ordner ein Unterverzeichnis namens "Fragmente", und speichern Sie die JSON-Dateien in diesem Unterverzeichnis.

Aus dem Web installierte Anwendungen

Bei Anwendungen, die aus dem Web installiert sind, sollten Sie zwei Fälle in Betracht ziehen.

Der erste Fall ist, dass die Installation für alle Benutzer auf dem System gilt. Fügen Sie in diesem Fall die JSON-Dateien dem Ordner hinzu:

C:\ProgramData\Microsoft\Windows Terminal\Fragments\{app-name}\{file-name}.json

Der zweite Fall ist, dass die Installation nur für den aktuellen Benutzer gilt. Fügen Sie in diesem Fall die JSON-Dateien dem Ordner hinzu:

C:\Users\<user>\AppData\Local\Microsoft\Windows Terminal\Fragments\{app-name}\{file-name}.json

Beachten Sie, dass sowohl der Ordner ProgramData als auch der Ordner LocalAppData bekannte Verzeichnisse sind, auf die das Installationsprogramm zugreifen sollte. Wenn das Windows Terminal\Fragments Verzeichnis nicht vorhanden ist, sollte es vom Installationsprogramm erstellt werden. Das {app-name} sollte spezifisch für Ihre Anwendung sein und das {file-name}.json kann irgendetwas sein - das Terminal liest alle .json-Dateien in diesem Verzeichnis.

Verteilen von Medienressourcen mit Der Fragmenterweiterung

Ab Windows Terminal 1.24 können Fragmenterweiterungen Medienressourcen wie Bilder und Pixelshader verteilen, die mit den iconbackgroundImageexperimental.pixelShaderPath Profilen und experimental.pixelShaderImagePath Aktionen verwendet werden sollen.

Frühere Versionen von Terminal unterstützte Web-URLs für icon und backgroundImage. Diese Versionen laden weiterhin Web-URL-Ressourcen dauerhaft. Neuere Versionen greifen nicht mehr auf Web-URLs zu, sondern suchen stattdessen im Verzeichnis, das Ihre Fragmentdatei enthält.

Wenn Sie die Kompatibilität mit allen verfügbaren Versionen von Terminal beibehalten möchten, können Sie alle Webressourcen im selben Verzeichnis wie Ihre .json Dateien platzieren.

Fragments\
 `- AppName\ <- FRAGMENT_ROOT
     |- file1.json
     |- file2.json
     `- app_icon.png

Sie können sich auf das folgende Kompatibilitätsverhalten verlassen:

Ressourcenpfad	< 1.24	≥ 1.24
`https://example.com/app/app_icon.png`	✅ geladen aus dem Web	✅ geladen von `$FRAGMENT_ROOT\app_icon.png`
`app_icon.png`	❌ ignoriert	✅ geladen von `$FRAGMENT_ROOT\app_icon.png`
`ms-appx://MyApplication/Fragments/app_icon.png`	❌ ignoriert	✅ geladen von `$FRAGMENT_ROOT\app_icon.png`