JSON-fragmenttillägg i Windows-terminalen

JSON-fragmenttillägg är kodfragment av JSON som programutvecklare kan skriva för att lägga till nya profiler i användarnas inställningar eller till och med ändra vissa befintliga profiler. Använd dem för att lägga till nya färgscheman i användarnas inställningar.

JSON-filernas struktur

Dela upp JSON-filen i två listor: en för profiler och en för scheman. Här är ett exempel på en JSON-fil som lägger till en ny profil, ändrar en befintlig profil och skapar ett nytt färgschema:

{
  "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"
    }
  ]
}

Det första objektet i "profiles" listan uppdaterar en befintlig profil. Den identifierar den profil som den vill uppdatera via guid som tillhandahålls till "updates" fältet (se nästa avsnitt för information om hur du hämtar GUID). Det andra objektet i listan skapar en ny profil med namnet "Lågfrekvent profil".

I listan "schemes" definieras ett nytt färgschema med namnet "Postmodern Tango Light". Du kan referera till det här färgschemat i inställningsfilen eller i själva JSON-filen (observera att "Lågfrekvent profil" använder det här nyligen definierade färgschemat).

Om du bara vill lägga till eller ändra profiler utan att lägga till färgscheman, eller tvärtom, inkludera endast den relevanta listan och utelämna den andra listan.

Anmärkning

Om du planerar att använda PowerShell för att generera fragment använder du -Encoding Utf8:

# 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

Om du använder VS Code för att redigera JSON är UTF8 standard, men du kan bekräfta det i det nedre statusfältet.

Profil-GUID:er

Som tidigare nämnts är profil-GUID:er ett sätt att referera till profiler och låta användarna uppdatera och utöka dem utan att behöva oroa sig för plats- eller namnändringar. Du kan bara ändra standardprofilerna, kommandotolken och PowerShell samt dynamiska profiler via fragment. Att tillhandahålla ett GUID är valfritt, men starkt uppmuntrat.

UUID-generatorn version 5 skapar GUID:erna och stöder BOM-less UTF-16LE-kodning.

Namnområdets GUID för Windows-terminalen i händelse av profiler som skapats av plugin-program och fragment är {f65ddb7e-706b-4499-8a50-40313caf510a}. Profiler som skapats av Windows Terminal Team använder ett separat GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Den här separationen skiljer profiler som skapats av Windows Terminal Team från profiler som skapats av plugin-program eller fragment så att de aldrig oavsiktligt kolliderar.

Så här fastställer du GUID för en befintlig profil

Tänk på vilken typ av profil det är för att fastställa GUID för en profil som ska uppdateras:

En profil som levereras av en tredje part och lagras på en standardplats för Windows Terminal Fragment kräver profil- och fragmentnamnområdets GUID {f65ddb7e-706b-4499-8a50-40313caf510a}, programmets namnområdes-GUID och profilnamnet. För ett profilfragment med namnet "Git Bash" som tillhandahålls av programmet "Git" är {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}det genererade GUID:t .

En profil som genereras automatiskt av Windows-terminalen kräver det interna GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} :et för Windows-terminalen och profilnamnet. För en profil med namnet "Ubuntu" som genereras automatiskt under WSL-installationen är {2c4de342-38b7-51cf-b940-2309a097f518}det resulterande GUID:t . Till skillnad från föregående fragmentexempel finns det inget programnamn.

Generera ett nytt profil-GUID

Om du vill generera ett GUID för en helt ny profil innan du distribuerar den använder du följande Python 3-exempel. Den genererar ett GUID baserat på profilen och fragmentets GUID för namnområdet för en profil som heter "Git Bash", vilket lagras i en standardmapp för Windows Terminal-fragment under programnamnet "Git", vilket bekvämt matchar rimlighetskontrollen.

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}}}")

Beräkna ett GUID för en inbyggd profil

Om du vill beräkna ett GUID för en inbyggd profil, till exempel de automatiskt genererade WSL-profilerna, använder du följande Python 3-exempel. Den beräknar ett GUID baserat på Windows-terminalens namnområdes-GUID för en profil med namnet "Ubuntu" som genererades automatiskt för WSL-distributionen, vilket bekvämt matchar sanity-kontrollen.

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}}}")

Minimikrav för inställningar som lagts till med fragment

Vissa minimala begränsningar gäller för vad du kan lägga till i användarinställningarna med hjälp av JSON-fragment:

För nya profiler som läggs till via fragment måste den nya profilen definiera ett namn för sig själv.
För nya färgscheman som läggs till genom fragment måste det nya färgschemat definiera ett namn för sig själv och definiera varje färg i färgtabellen (det vill säga färgerna "svart" genom "brightWhite" i föregående exempelbild).

Var du ska placera JSON-fragmentfilerna

Platsen där JSON-fragmentfilerna ska placeras varierar beroende på installationsmetoden för programmet som lägger till dem.

Microsoft Store-program

För program som installeras via Microsoft Store (eller liknande) måste programmet deklarera sig som ett apptillägg. Läs mer om hur du skapar och är värd för ett apptillägg. Det nödvändiga avsnittet replikeras här. Appxmanifest-filen i paketet måste innehålla:

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

Viktiga saker att notera:

Fältet "Name" måste vara com.microsoft.windows.terminal.settings för att Windows-terminalen ska kunna identifiera tillägget.
Fältet "Id" kan fyllas i som du vill.
Fältet "PublicFolder" ska ha namnet på mappen, i förhållande till paketroten, där du lagrar JSON-filerna (den här mappen kallas vanligtvis "Offentlig" men kan namnges något annat).
I den gemensamma mappen skapar du en underkatalog med namnet "Fragment" och lagrar JSON-filerna i den underkatalogen.

Program installerade från webben

Överväg två fall för program som installerats från webben.

Det första fallet är att installationen är avsedd för alla användare i systemet. I det här fallet lägger du till JSON-filerna i mappen:

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

Det andra fallet är att installationen endast är för den aktuella användaren. I det här fallet lägger du till JSON-filerna i mappen:

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

Observera att både mapparna ProgramData och LocalAppData är kända mappar som installationsprogrammet ska komma åt. Om katalogen Windows Terminal\Fragments inte finns bör installationsprogrammet skapa den. {app-name} Bör vara unikt för ditt program och {file-name}.json kan vara vad som helst – terminalen läser alla .json filer i katalogen.

Distribuera medieresurser med fragmenttillägget

Från och med Windows Terminal 1.24 kan fragmenttillägg distribuera medieresurser som bilder och pixelskuggor som ska användas med iconegenskaperna , backgroundImageexperimental.pixelShaderPath och experimental.pixelShaderImagePath för profiler och åtgärder.

Tidigare versioner av Terminal-webb-URL:er som stöds för icon och backgroundImage. Dessa versioner fortsätter att läsa in webb-URL-resurser i all evighet. Nyare versioner kommer inte längre åt webb-URL:er, utan kommer i stället att titta i katalogen som innehåller fragmentfilen.

Om du vill upprätthålla kompatibiliteten med alla tillgängliga versioner av Terminal kan du placera alla webbresurser i samma katalog som dina .json filer.

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

Du kan förlita dig på följande kompatibilitetsbeteenden:

Resurssökväg	< 1.24	≥ 1,24
`https://example.com/app/app_icon.png`	✅ inläst från webben	✅ inlästa från `$FRAGMENT_ROOT\app_icon.png`
`app_icon.png`	❌ Ignoreras	✅ inlästa från `$FRAGMENT_ROOT\app_icon.png`
`ms-appx://MyApplication/Fragments/app_icon.png`	❌ Ignoreras	✅ inlästa från `$FRAGMENT_ROOT\app_icon.png`