Rozšíření fragmentu JSON v terminálu Windows

Rozšíření fragmentu JSON jsou fragmenty kódu JSON, které můžou vývojáři aplikací psát, aby do nastavení uživatelů přidali nové profily nebo dokonce upravili určité existující profily. Pomocí nich můžete do nastavení uživatelů přidat nová barevná schémata.

Struktura souborů JSON

Rozdělte soubor JSON do dvou seznamů: jeden pro profily a jeden pro schémata. Tady je příklad souboru JSON, který přidá nový profil, upraví existující profil a vytvoří nové barevné schéma:

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

První položka v "profiles" seznamu aktualizuje existující profil. Identifikuje profil, který chce aktualizovat pomocí identifikátoru GUID zadaného "updates" do pole (podrobnosti o získání identifikátoru GUID najdete v další části). Druhá položka v seznamu vytvoří nový profil s názvem "Cool Profile".

"schemes" V seznamu je definováno nové barevné schéma s názvem Postmodern Tango Light. Toto barevné schéma můžete odkazovat v souboru nastavení nebo v samotném souboru JSON (všimněte si, že "Cool Profile" používá toto nově definované barevné schéma).

Pokud chcete přidat nebo upravit profily jenom bez přidání barevných schémat nebo naopak, zahrňte pouze příslušný seznam a vynechat druhý seznam.

Poznámka:

Pokud chcete k vygenerování fragmentů použít PowerShell, použijte -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

Pokud k úpravě JSON použijete VS Code, je UTF8 výchozí, ale můžete ho potvrdit na dolním stavovém řádku.

Identifikátory GUID profilu

Jak už bylo uvedeno dříve, identifikátory GUID profilů představují způsob, jak odkazovat na profily a umožnit uživatelům aktualizovat je a rozšířit, aniž by se museli starat o změny umístění nebo názvu. Můžete upravit pouze výchozí profily, příkazový řádek a PowerShell a dynamické profily prostřednictvím fragmentů. Poskytnutí identifikátoru GUID je volitelné, ale důrazně doporučujeme.

Generátor UUID verze 5 vytvoří identifikátory GUID a podporuje kódování UTF-16LE bez BOM.

Identifikátor GUID oboru názvů pro terminál Windows v případě profilů vytvořených moduly plug-in a fragmenty je {f65ddb7e-706b-4499-8a50-40313caf510a}. Profily vytvořené týmem terminálu Systému Windows používají samostatný identifikátor GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Toto rozdělení zajišťuje, že profily vytvořené týmem Windows Terminal jsou jednoznačně odlišeny od profilů vytvořených pluginy nebo fragmenty, takže se nikdy omylem nesloučí.

Určení identifikátoru GUID existujícího profilu

Pokud chcete určit identifikátor GUID profilu, který se má aktualizovat, zvažte, o jaký druh profilu se jedná:

Profil odeslaný třetí stranou a uložený ve standardním umístění pro fragmenty v terminálu Windows vyžaduje {f65ddb7e-706b-4499-8a50-40313caf510a} identifikátor GUID oboru názvů pro profil a fragment, identifikátor GUID oboru názvů aplikace a název profilu. Pro fragment profilu s názvem 'Git Bash', který je dodán aplikací Git, je vygenerován identifikátor GUID {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}.

Profil automaticky vygenerovaný terminálem Windows vyžaduje interní identifikátor GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} terminálu Windows a název profilu. Pro profil s názvem Ubuntu automaticky vygenerovaný během instalace WSL je výsledný identifikátor GUID {2c4de342-38b7-51cf-b940-2309a097f518}. Na rozdíl od předchozího příkladu fragmentu neexistuje žádný název aplikace.

Generování nového identifikátoru GUID profilu

Pokud chcete před distribucí vygenerovat identifikátor GUID pro zcela nový profil, použijte následující příklad Pythonu 3. Vygeneruje identifikátor GUID na základě identifikátoru GUID profilu a oboru názvů fragmentu pro profil s názvem 'Git Bash', uložený ve standardní složce fragmentů Windows Terminalu pro aplikaci s názvem Git, což pohodlně odpovídá zhodnocení správnosti.

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

Výpočet identifikátoru GUID pro předdefinovaný profil

Pokud chcete vypočítat identifikátor GUID pro předdefinovaný profil, například automaticky vygenerované profily WSL, použijte následující příklad Pythonu 3. Vypočítá identifikátor GUID založený na identifikátoru GUID oboru názvů terminálu Windows pro profil s názvem Ubuntu, který se automaticky vygeneroval pro distribuci WSL a pohodlně odpovídá kontrole sanity.

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

Minimální požadavky na nastavení přidaná s fragmenty

Některá minimální omezení platí pro to, co můžete přidat do uživatelských nastavení pomocí fragmentů JSON:

Pro nové profily přidané prostřednictvím fragmentů musí nový profil definovat název pro sebe.
Pro nová barevná schémata přidaná prostřednictvím fragmentů musí nové barevné schéma definovat název pro sebe a definovat každou barvu v tabulce barev (to znamená barvy "černá" až "jasná bílá" v předchozím příkladu obrázku).

Kam umístit soubory fragmentu JSON

Umístění pro umístění souborů fragmentu JSON se liší v závislosti na metodě instalace aplikace, která je přidá.

Aplikace z Microsoft Storu

U aplikací nainstalovaných prostřednictvím Microsoft Storu (nebo podobných) musí být aplikace deklarována jako rozšíření aplikace. Přečtěte si další informace o tom, jak vytvořit a hostovat rozšíření aplikace. Tady se replikuje nezbytná část. Soubor appxmanifest balíčku musí obsahovat:

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

Důležité věci, které je potřeba si uvědomit:

Pole "Name" musí být com.microsoft.windows.terminal.settings určené pro terminál Windows, aby bylo možné rozšíření zjistit.
Pole "Id" můžete vyplnit podle potřeby.
Pole "PublicFolder" by mělo mít název složky vzhledem ke kořenovému adresáři balíčku, do kterého ukládáte soubory JSON (tato složka se obvykle nazývá "Veřejná", ale může mít název něco jiného).
Ve veřejné složce vytvořte podadresář s názvem Fragmenty a uložte soubory JSON do daného podadresáře.

Aplikace nainstalované z webu

U aplikací nainstalovaných z webu zvažte dva případy.

Prvním případem je, že instalace je určená pro všechny uživatele v systému. V tomto případě přidejte soubory JSON do složky:

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

Druhým případem je, že instalace je určena pouze pro aktuálního uživatele. V tomto případě přidejte soubory JSON do složky:

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

Všimněte si, že složky ProgramData i LocalAppData jsou známé složky, ke kterým má instalační program přistupovat. Windows Terminal\Fragments Pokud adresář neexistuje, měl by ho instalační program vytvořit. Měla {app-name} by být jedinečná pro vaši aplikaci a {file-name}.json může to být cokoli – terminál načte všechny .json soubory v daném adresáři.

Distribuce multimediálních prostředků s rozšířením fragmentu

Od terminálu Windows 1.24 mohou rozšíření fragmentů distribuovat multimediální prostředky, jako jsou obrázky a pixelové shadery, které se mají používat s iconbackgroundImageexperimental.pixelShaderPath profily a experimental.pixelShaderImagePath akcemi a vlastnosti.

Starší verze terminálových podporovaných webových adres URL pro icon a backgroundImage. Tyto verze budou nadále načítat prostředky webových adres URL v utajení. Novější verze už nebudou mít přístup k webovým adresám URL, ale budou hledat v adresáři obsahujícím váš soubor fragmentu.

Pokud chcete zachovat kompatibilitu se všemi dostupnými verzemi terminálu, můžete umístit všechny webové prostředky do stejného adresáře jako soubory .json .

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

Můžete se spolehnout na následující chování kompatibility:

Cesta k prostředku	< 1.24	≥ 1.24
`https://example.com/app/app_icon.png`	✅ načteno z webu	✅ načteno z `$FRAGMENT_ROOT\app_icon.png`
`app_icon.png`	❌ ignorovaný	✅ načteno z `$FRAGMENT_ROOT\app_icon.png`
`ms-appx://MyApplication/Fragments/app_icon.png`	❌ ignorovaný	✅ načteno z `$FRAGMENT_ROOT\app_icon.png`