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

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

JSON ファイルの構造

JSON ファイルを、プロファイル用とスキーム用の 2 つのリストに分割します。新しいプロファイルを追加し、既存のプロファイルを変更し、新しい配色を作成する 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 番目の項目では、"クールプロファイル" という名前の新しいプロファイルが作成されます。

"schemes"リストでは、"Postmodern Tango Light" という新しい配色が定義されています。この配色は、設定ファイルまたはこの JSON ファイル自体で参照できます ("クールプロファイル" では、この新しく定義された配色が使用されていることに注意してください)。

配色を追加せずにプロファイルのみを追加または変更する場合、またはその逆の場合は、関連するリストのみを含めて、他のリストを省略します。

注

PowerShell を使用してフラグメントを生成する予定の場合は、 -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

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

プロファイル GUID

前述のように、プロファイル GUID は、プロファイルを参照し、ユーザーが場所や名前の変更を気にせずに更新および拡張できるようにする方法です。フラグメントを使用して、既定のプロファイル、コマンドプロンプト、PowerShell、および動的プロファイルのみを変更できます。 GUID の指定は省略可能ですが、強くお勧めします。

バージョン 5 UUID ジェネレーターは GUID を作成し、BOM レス UTF-16LE エンコードをサポートします。

プラグインとフラグメントによって作成されたプロファイルの場合の 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 Terminal Fragments フォルダーに格納された「Git Bash」というプロファイルのプロファイル GUID とフラグメント名前空間 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 フラグメントを使用してユーザー設定に追加できる内容に適用されます。

フラグメントを介して追加された新しいプロファイルの場合、新しいプロファイルはそれ自体の名前を定義する必要があります。
フラグメントによって追加される配色には、それ自体の名前を定義し、カラーテーブルにあるすべての色を定義する必要があります（つまり、前の例の画像の色 “黒” から “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" と呼ばれますが、他の名前を付けることができます)。
パブリックフォルダー内に"Fragments" という名前のサブディレクトリを作成し、そのサブディレクトリに JSON ファイルを格納します。

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

Web からインストールされたアプリケーションの場合は、2 つのケースを検討してください。

最初のケースは、インストールがシステム上のすべてのユーザー向けであるということです。この場合は、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 ファイルを読み取ります。

フラグメント拡張機能を使用したメディアリソースの配布

Windows ターミナル 1.24 の時点で、フラグメント拡張機能は、プロファイルとアクションの icon、 backgroundImage、 experimental.pixelShaderPath 、および experimental.pixelShaderImagePath プロパティで使用されるイメージやピクセルシェーダーなどのメディアリソースを配布できます。

以前のバージョンのターミナルでは、 icon と backgroundImageの Web URL がサポートされています。これらのバージョンでは、永続的に Web URL リソースが引き続き読み込まれます。新しいバージョンでは Web URL にアクセスできなくなりますが、代わりにフラグメントファイルを含むディレクトリが検索されます。

利用可能なすべてのバージョンのターミナルとの互換性を維持したい場合は、 .json ファイルと同じディレクトリに任意の Web リソースを配置できます。

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

次の互換性の動作に依存できます。

リソースパス	< 1.24	≥ 1.24
`https://example.com/app/app_icon.png`	✅ Web から読み込まれる	✅ から読み込まれる `$FRAGMENT_ROOT\app_icon.png`
`app_icon.png`	❌ 無視	✅ から読み込まれる `$FRAGMENT_ROOT\app_icon.png`
`ms-appx://MyApplication/Fragments/app_icon.png`	❌ 無視	✅ から読み込まれる `$FRAGMENT_ROOT\app_icon.png`

注

1.24 より前のバージョンの Windows ターミナルでは、プロファイルでの icon と backgroundImage の Web URL のみがサポートされています。 experimental.pixelShaderPathまたはアクション iconに互換性のあるフォールバックを指定する方法はありません。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-12