Windows ターミナルの JSON フラグメント拡張機能

  • [アーティクル]

JSON フラグメント拡張機能は、アプリケーション開発者がユーザーの設定に新しいプロファイルを追加したり、既存の特定のプロファイルを変更したりするために記述できる JSON のスニペットです。 また、ユーザーの設定に新しい配色を追加するために使用することもできます。

JSON ファイルの構造

JSON ファイルは 2 つのリストに分割する必要があります。1 つはプロファイル用、もう 1 つはスキーム用です。 新しいプロファイルを追加し、既存のプロファイルを変更し、新しい配色を作成する json ファイルの例を次に示します。

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

"profiles" リストの最初の項目は、"updates" フィールドに指定された GUID を使用して更新対象のプロファイルを識別することで、既存のプロファイルを更新しています (GUID を取得する方法の詳細については、次のセクションを参照してください)。 そのリスト 2 番目の項目では、"Cool Profile" という名前の新しいプロファイルを作成しています。

"schemes" のリストでは、"Postmodern Tango Light" という名前の新しい配色が定義されており、これはその後、ユーザーが設定ファイルまたはこの JSON ファイル自体で参照できます ("Cool Profile" では、ここで新しく定義された配色が使用されています)。

もちろん、開発者が配色を追加せずにプロファイルを追加または変更したいだけの場合 (またその逆の場合)、関連するリストのみが存在する必要があり、他のリストは省略できます。

Note

PowerShell を使用してフラグメントを生成する場合は、-Encoding Utf8 を使用する必要があります。

# 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

JSON の編集に VS Code を使用している場合は UTF8 が既定値ですが、下部のステータス バーで確認できます。

プロファイル GUID

前に説明したように、プロファイル GUID は、プロファイルを参照し、ユーザーが場所や名前の変更を気にすることなくそれらを更新および拡張するための方法です。 フラグメントによって変更できるプロファイルは、既定のプロファイル、コマンドプロンプトと PowerShell、および動的プロファイルだけです。 GUID の指定は省略可能ですが、指定することを強く推奨します。

GUID は、BOM-less UTF-16LE エンコードをサポートする Version 5 UUID ジェネレーターを使用して生成されます。

プラグインとフラグメントによって作成されたプロファイルの場合、Windows ターミナルの名前空間 GUID は {f65ddb7e-706b-4499-8a50-40313caf510a} です。 Windows ターミナル チームによって作成されたプロファイルでは、別の GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8}) が使用されます。 これは、プラグインまたはフラグメントによって作成されたプロファイルから、Windows ターミナル チームによって作成されたプロファイルを明確に区別するために (間違って衝突しないように) 行われます。

既存のプロファイルの GUID を確認する方法

更新するプロファイルの GUID は、プロファイルの種類によって異なります。

標準の Windows ターミナル フラグメントの場所に格納されたサードパーティによって配布されるプロファイルには、プロファイルとフラグメントの名前空間 GUID {f65ddb7e-706b-4499-8a50-40313caf510a}、アプリケーション名前空間 GUID、およびプロファイル名が必要です。 アプリケーション 'Git' によって提供される "Git Bash" という名前のプロファイル フラグメントの場合、生成される GUID は {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b} です。

Windows ターミナルによって自動的に生成されるプロファイルには、Windows ターミナルの内部 GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} とプロファイル名が必要です。 WSL のインストール中に自動的に生成される 'Ubuntu' という名前のプロファイルの場合、結果として得られる GUID は {2c4de342-38b7-51cf-b940-2309a097f518} です。 前のフラグメントの例とは対照的に、"アプリケーション名" は関与しません。

新しいプロファイル GUID の生成

配布前に完全に新しいプロファイルの GUID を生成するには、次の Python 3 の例を使用できます。 これにより、'Git' アプリケーション名の下の標準の Windows ターミナルのフラグメント フォルダー内に格納されている、"Git Bash" というプロファイルのプロファイルとフラグメント名前空間 GUID に基づいて GUID が生成されます。これは、サニティ チェックに一致します。

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

組み込みプロファイルの GUID の計算

自動的に生成された WSL プロファイルなど、組み込みのプロファイルの GUID を計算するには、次の Python 3 の例を使用できます。 WSL ディストリビューションに対して自動的に生成された 'Ubuntu' という名前のプロファイルの Windows ターミナル名前空間 GUID に基づいて GUID が計算され、サニティ チェックと一致します。

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

フラグメントを使用して追加される設定の最小要件

JSON フラグメントを使用してユーザー設定に追加できるものについては、最小限の制限があります。

  • フラグメントによって追加される新しいプロファイルの場合、新しいプロファイルには、少なくともそれ自体の名前を定義する必要があります。
  • フラグメントによって追加される新しい配色の場合、新しい配色では、それ自身の名前に加えて、色テーブルのすべての色を定義する必要があります (たとえば、上の図の例では、色 "black" から "brightWhite" まで)。

JSON フラグメント ファイルを配置する場所

JSON フラグメント ファイルを配置する場所は、それを配置するアプリケーションのインストール方法によって異なります。

Microsoft Store アプリケーション

Microsoft Store (またはそれと同様) を使用してインストールされたアプリケーションでは、アプリケーションが自身をアプリの拡張機能として宣言する必要があります。 その方法の詳細については、「アプリ拡張機能の作成とホスティング」を参照してください。 必要なセクションをここに複製します。 パッケージの appxmanifest ファイルには次のものが含まれている必要があります。

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

次の点に注意してください。

  • Windows ターミナルが拡張機能を検出できるようにするには、"Name" フィールドが com.microsoft.windows.terminal.settings である必要があります。
  • "Id" フィールドは、開発者が自由に入力できます。
  • "PublicFolder" フィールドには、パッケージ ルートに対して相対的なフォルダー名を指定する必要があります。ここには JSON ファイルが格納されます (通常、このフォルダーは "Public" という名前ですが、開発者は必要に応じて別の名前を付けることができます)。
  • Public フォルダー内には、"Fragment" という名前のサブディレクトリを作成し、JSON ファイルをそのサブディレクトリに格納する必要があります。

Web からインストールされるアプリケーション

Web からインストールされるアプリケーションの場合、2 つのケースがあります。

1 つ目は、システム上のすべてのユーザーを対象としたインストールです。 この場合は、JSON ファイルを次のフォルダーに追加する必要があります。

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

2 つ目のケースは、現在のユーザーのみを対象としたインストールです。 この場合は、JSON ファイルを次のフォルダーに追加する必要があります。

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

ProgramData フォルダーと LocalAppData フォルダーの両方が、インストーラーがアクセスできる既知のフォルダーであることに注意してください。 どちらの場合でも、Windows Terminal\Fragments ディレクトリが存在しない場合は、インストーラーによって作成されます。 {app-name} はアプリケーションに固有である必要があり{file-name}.json、は何でもかまいません。ターミナルは、そのディレクトリ内のすべての json ファイルを読み取ります。