共用方式為

Windows 終端機中的 JSON 片段延伸模組

JSON 片段延伸模組是 JSON 片段，應用程式開發人員可以撰寫這些片段，以將新設定檔新增至使用者的設定，甚至修改某些現有設定檔。 使用它們將新的配色方案新增至使用者的設定。

JSON 檔案的結構

將JSON檔案分割成兩個清單：一個用於設定檔，一個用於配置。 以下是新增設定檔、修改現有設定檔以及建立新配色方案的 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 的詳細資訊，請參閱下一節）。 該列表中的第二項會創建一個名為“酷配置文件”的新配置文件。

在 "schemes" 列表中，定義了一種名為“後現代探戈燈”的新配色方案。 您可以在設定檔案或此 JSON 檔案本身中參考此色彩配置（請注意，「Cool Profile」使用這個新定義的色彩配置）。

如果您只想新增或修改設定檔而不新增色彩配置，反之亦然，請只包含相關清單並省略其他清單。

備註

如果您打算使用 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-less 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 Bash」的設定檔和片段命名空間 GUID 產生 GUID，該設定檔儲存在「Git」應用程式名稱下的標準 Windows 終端機片段資料夾中，方便地符合健全性檢查。

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

若要計算內建配置檔的 GUID，例如自動產生的 WSL 配置檔，請使用下列 Python 3 範例。 它會根據 Windows 終端機命名空間 GUID 計算名為「Ubuntu」的設定檔的 GUID，該設定檔是針對 WSL 發行版自動產生的，方便地符合健全性檢查。

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>

需要注意的關鍵事項：

  • 此 "Name" 欄位必須是 com.microsoft.windows.terminal.settings 才能讓 Windows 終端機偵測到擴充功能。
  • "Id"該字段可以根據需要填寫。
  • 欄位 "PublicFolder" 應包含相對於套件根目錄的資料夾名稱，用來儲存 JSON 檔案（此資料夾通常稱為「公用」，但也可以使用其他名稱）。
  • 在公用資料夾中，建立名為「Fragments」的子目錄，並將JSON檔案儲存在該子目錄中。

從 Web 安裝的應用程式

對於從 Web 安裝的應用程式，請考慮兩種情況。

第一種情況是安裝適用於系統上的所有使用者。 在此情況下，請將 JSON 檔案新增至資料夾：

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

第二種情況是安裝僅適用於當前用戶。 在此情況下，請將 JSON 檔案新增至資料夾：

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

請注意，和ProgramDataLocalAppData資料夾都是安裝程式應該存取的已知資料夾。 如果目錄 Windows Terminal\Fragments 不存在，安裝程式應該建立它。 {app-name} 必須是您應用程式獨有的，而 {file-name}.json 可以是任何形式 - 終端程式會讀取該目錄下的所有 .json 檔案。

使用片段擴充功能分發媒體資源

從 Windows 終端機 1.24 開始，片段延伸模組可以散發媒體資源，例如影像和圖元著色器，以搭配設定檔和動作上的 、 和 iconbackgroundImageexperimental.pixelShaderPath屬性使用。experimental.pixelShaderImagePath

舊版終端機支援 和 icon的 Web URL backgroundImage 。 這些版本將繼續永久載入 Web URL 資源。 較新版本將不再存取 Web URL，而是會尋找包含片段檔案的目錄。

如果您希望保持與所有可用版本的終端機的兼容性，您可以將任何 Web 資源放在與文件 .json 相同的目錄中。

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

您可以依賴下列相容性行為：

資源路徑 < 1.24 ≥ 1.24
https://example.com/app/app_icon.png ✅ 從網絡加載 ✅ 載入自 $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 終端機版本僅支援設定檔上的 iconbackgroundImage Web URL。 無法指定 或 experimental.pixelShaderPath 動作 icon的相容後援。

  • Last updated on