Estensioni di frammenti JSON nel terminale Windows

Le estensioni del frammento JSON sono frammenti di codice JSON che gli sviluppatori di applicazioni possono scrivere per aggiungere nuovi profili alle impostazioni degli utenti o persino modificare determinati profili esistenti. Usarli per aggiungere nuove combinazioni di colori alle impostazioni degli utenti.

Struttura dei file JSON

Suddividere il file JSON in due elenchi: uno per i profili e uno per gli schemi. Ecco un esempio di file JSON che aggiunge un nuovo profilo, modifica un profilo esistente e crea una nuova combinazione di colori:

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

Il primo elemento dell'elenco "profiles" aggiorna un profilo esistente. Identifica il profilo che vuole aggiornare tramite il GUID fornito al "updates" campo (vedere la sezione successiva per informazioni dettagliate su come ottenere il GUID). Il secondo elemento dell'elenco crea un nuovo profilo denominato "Profilo Cool".

Nell'elenco "schemes" viene definita una nuova combinazione di colori denominata "Postmodern Tango Light". Puoi fare riferimento a questa combinazione di colori nel file delle impostazioni o direttamente in questo file JSON (si noti che "Profilo Cool" utilizza questa combinazione di colori appena definita).

Se si desidera solo aggiungere o modificare profili senza aggiungere combinazioni di colori o viceversa, includere solo l'elenco pertinente e omettere l'altro elenco.

# 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

GUID del profilo

Come indicato in precedenza, i GUID del profilo sono un modo per fare riferimento ai profili e consentire agli utenti di aggiornarli ed estenderli senza preoccuparsi delle modifiche alla posizione o al nome. È possibile modificare solo i profili predefiniti, il prompt dei comandi e PowerShell, nonché i profili dinamici tramite frammenti. Fornire un GUID è facoltativo, ma fortemente consigliato.

Il generatore UUID versione 5 crea i GUID e supporta la codifica UTF-16LE senza BOM.

Il GUID dello spazio dei nomi per Windows Terminal nel caso di profili creati da plug-in e frammenti è {f65ddb7e-706b-4499-8a50-40313caf510a}. I profili creati dal team di Terminale Windows usano un GUID separato ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Questa separazione disambigua i profili creati dal team di Terminale Windows dai profili creati da plug-in o frammenti in modo da non scontrarsi accidentalmente.

Come determinare il GUID di un profilo esistente

Per determinare il GUID di un profilo da aggiornare, considerare il tipo di profilo:

Un profilo fornito da terze parti e archiviato in una posizione standard dei frammenti del terminale di Windows richiede il GUID del profilo e del namespace dei frammenti, il GUID {f65ddb7e-706b-4499-8a50-40313caf510a} dello spazio dei nomi dell'applicazione e il nome del profilo. Per un frammento di profilo denominato 'Git Bash' fornito dall'applicazione 'Git', il GUID generato è {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}.

Un profilo generato automaticamente da Terminale Windows richiede il GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} interno del terminale Windows e il nome del profilo. Per un profilo denominato "Ubuntu" generato automaticamente durante l'installazione di WSL, il GUID risultante è {2c4de342-38b7-51cf-b940-2309a097f518}. A differenza dell'esempio di frammento precedente, non è coinvolto alcun nome dell'applicazione.

Generazione di un nuovo GUID del profilo

Per generare un GUID per un profilo completamente nuovo prima di distribuirlo, usare l'esempio python 3 seguente. Genera un GUID basato sul GUID dello spazio dei nomi del profilo e del frammento per un profilo chiamato "Git Bash" che viene memorizzato in una cartella predefinita di Frammenti di Windows Terminal sotto il nome dell'applicazione "Git", corrispondendo comodamente al test di coerenza.

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

Calcolo di un GUID per un profilo predefinito

Per calcolare un GUID per un profilo predefinito, ad esempio i profili WSL generati automaticamente, usare l'esempio python 3 seguente. Calcola un GUID basato sul GUID dello spazio dei nomi terminale Windows per un profilo denominato "Ubuntu" generato automaticamente per la distribuzione WSL, che corrisponde facilmente al controllo della integrità.

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

Requisiti minimi per le impostazioni aggiunte con frammenti

Alcune restrizioni minime si applicano a ciò che è possibile aggiungere alle impostazioni utente usando frammenti JSON:

• Per i nuovi profili aggiunti tramite frammenti, il nuovo profilo deve definire un nome per se stesso.
• Per le nuove combinazioni di colori aggiunte tramite frammenti, la nuova combinazione di colori deve definire un nome per se stessa e definire ogni colore nella tabella dei colori (ovvero i colori "nero" tramite "brightWhite" nell'immagine di esempio precedente).

Dove inserire i file di frammento JSON

Il percorso in cui posizionare i file di frammento JSON varia a seconda del metodo di installazione dell'applicazione che li aggiunge.

Applicazioni di Microsoft Store

Per le applicazioni installate tramite Microsoft Store (o simili), l'applicazione deve dichiararsi come un'estensione dell'app. Altre informazioni su come creare e ospitare un'estensione dell'app. La sezione necessaria viene replicata qui. Il file appxmanifest del pacchetto deve includere:

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

Aspetti chiave da notare:

• Il "Name" campo deve essere com.microsoft.windows.terminal.settings per il terminale Windows per rilevare l'estensione.
• Il "Id" campo può essere compilato come desiderato.
• Il "PublicFolder" campo deve avere il nome della cartella, rispetto alla radice del pacchetto, in cui si archiviano i file JSON (questa cartella è in genere denominata "Pubblico", ma può essere denominata qualcos'altro).
• All'interno della cartella pubblica creare una sottodirectory denominata "Frammenti" e archiviare i file JSON in tale sottodirectory.

Applicazioni installate dal Web

Per le applicazioni installate dal Web, considerare due casi.

Il primo caso è che l'installazione è per tutti gli utenti del sistema. In questo caso, aggiungere i file JSON alla cartella :

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

Il secondo caso è che l'installazione è solo per l'utente corrente. In questo caso, aggiungere i file JSON alla cartella :

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

Si noti che entrambe le ProgramData cartelle e LocalAppData sono cartelle note a cui deve accedere il programma di installazione. Se la Windows Terminal\Fragments directory non esiste, il programma di installazione deve crearlo. Deve {app-name} essere univoco per l'applicazione e {file-name}.json può essere qualsiasi elemento. Il terminale legge tutti i file .json in tale directory.

Distribuzione delle risorse multimediali con la vostra estensione di frammento

A partire da Windows Terminal 1.24, le estensioni dei frammenti possono distribuire risorse multimediali come immagini e pixel shader da usare con le proprietà icon, backgroundImage, experimental.pixelShaderPath e experimental.pixelShaderImagePath nei profili e nelle azioni.

Le versioni precedenti di Terminale supportavano gli URL Web per icon e backgroundImage. Queste versioni continueranno a caricare le risorse URL Web in perpetuità. Le versioni più recenti non accederanno più agli URL Web, ma cercheranno invece nella directory contenente il file di frammento.

Se si vuole mantenere la compatibilità con tutte le versioni disponibili di Terminale, è possibile inserire qualsiasi risorsa Web nella stessa directory dei .json file.

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

È possibile basarsi sui comportamenti di compatibilità seguenti: