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. De kan också användas för att lägga till nya färgscheman i användarnas inställningar.

JSON-filernas struktur

JSON-filen ska delas upp 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 och identifierar den profil som den vill uppdatera via det GUID som anges i "updates" fältet (information om hur du hämtar GUID finns i nästa avsnitt). Det andra objektet i listan skapar en ny profil med namnet "Lågfrekvent profil".

"schemes" I listan definieras ett nytt färgschema med namnet "Postmodern Tango Light" och kan senare refereras av användaren i deras inställningsfil eller i själva JSON-filen (observera att "Cool Profil" använder det här nyligen definierade färgschemat).

Om utvecklaren bara vill lägga till/ändra profiler utan att lägga till färgscheman (och vice versa) behöver bara den relevanta listan finnas och den andra listan kan utelämnas.

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

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

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. De enda profiler som kan ändras via fragment är standardprofilerna, kommandotolken och PowerShell samt dynamiska profiler. Det är dock valfritt att tillhandahålla ett GUID.

GUID:erna genereras med hjälp av en Version 5 UUID-generator som stöder BOM-mindre 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}). Detta görs för att skilja profiler som skapats av Windows-terminalteamet från profiler som skapats av plugin-program eller fragment så att de aldrig av misstag kan kollidera.

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

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

En profil som levereras av en tredje part som 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 det genererade GUID:t: {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}.

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 det resulterande GUID:t: {2c4de342-38b7-51cf-b940-2309a097f518}. Till skillnad från det tidigare fragmentexemplet finns det inget programnamn.

Generera ett nytt profil-GUID

Om du vill generera ett GUID för en helt ny profil innan du distribuerar det kan du använda följande Python 3-exempel. Den genererar ett GUID baserat på profilens och fragmentets namnområdes-GUID för en profil med namnet "Git Bash" som lagras i en standardmapp för Windows Terminal Fragments under "Git"-programnamnet, vilket bekvämt matchar sanitetskontrollen.

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, kan du använda 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

Det finns några minimala begränsningar för vad som kan läggas 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 minst definiera ett namn för sig själv.
• För nya färgscheman som läggs till via fragment måste det nya färgschemat definiera ett namn för sig självt, samt definiera varje färg i färgtabellen (dvs. färgerna "svart" genom "brightWhite" i exempelbilden ovan).

Var du ska placera JSON-fragmentfilerna

Platsen för att placera JSON-fragmentfilerna varierar beroende på installationsmetoden för programmet som vill placera 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 Terminal ska kunna identifiera tillägget.
• Fältet "Id" kan fyllas i som utvecklaren vill.
• Fältet "PublicFolder" ska ha namnet på mappen i förhållande till paketroten, där JSON-filerna lagras (den här mappen kallas vanligtvis "Offentlig" men kan namnges något annat om utvecklaren vill).
• I den gemensamma mappen ska en underkatalog med namnet "Fragment" skapas och JSON-filerna ska lagras i den underkatalogen.

Program installerade från webben

För program som installeras från webben finns det två fall.

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

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

I det andra fallet är installationen endast för den aktuella användaren. I det här fallet bör JSON-filerna läggas till 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 kunna komma åt. Om i båda fallen, om Windows Terminal\Fragments katalogen 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 den 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: