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

發行項
02/03/2024

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 的詳細說明位於下一節)。該清單中的第二個項目會建立名為「Cool Profile」的新設定檔。

在 "schemes" 清單中，定義了名為「Postmodern Tango Light」的新色彩配置，且之後可在使用者的設定檔案中或此 JSON 檔案本身中進行參照 (請注意，「Cool Profile」會使用此新定義的色彩配置)。

當然，如果開發人員只想要新增/修改設定檔而不新增色彩配置（反之亦然），則只需要提供相關清單，其他清單則可省略。

注意

如果您打算使用 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

如果您使用 VS Code 來編輯 JSON，預設值為 UTF8，但您可以在底部狀態列中確認。

設定檔 GUID

如先前所述，設定檔 GUID 是參考設定檔的方法，可讓使用者更新和擴充設定檔，而不必擔心位置或名稱變更。唯一可以透過片段修改的設定檔是預設設定檔、命令提示字元和 PowerShell，以及動態設定檔。您不一定要提供 GUID，但強烈建議這麼做。

GUID 是使用第 5 版 UUID 產生器產生，支援無 BOM UTF-16LE 編碼。

針對由外掛程式和片段所建立的設定檔，其 Windows 終端機的命名空間 GUID 為 {f65ddb7e-706b-4499-8a50-40313caf510a}。 Windows 終端機團隊建立的設定檔會使用不同的 GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8})。這麼做是為了釐清由 Windows終端機團隊所建立的設定檔，以及由外掛程式或片段所建立的設定檔，如此可徹底避免意外衝突。

如何判斷現有設定檔的 GUID

若要判斷要更新的設定檔 GUID，取決於該設定檔的類型：

儲存在標準 Windows 終端機片段位置的第三方所運送的配置檔需要配置檔和片段命名空間 GUID、應用程式命名空間 GUID {f65ddb7e-706b-4499-8a50-40313caf510a}和設定檔名稱。若設定檔片段名稱為「Git Bash」、並且由應用程式「Git」提供，則產生的 GUID 為：{2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}。

Windows 終端機自動產生的設定檔需要 Windows 終端機內部 GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} 和設定檔名稱。若設定檔名稱為「Ubuntu」，在 WSL 安裝期間自動產生，則產生的 GUID 為：{2c4de342-38b7-51cf-b940-2309a097f518}。與先前的片段範例相反，不需要「應用程式名稱」。

產生新的設定檔 GUID

若要在散發之前為全新的設定檔產生 GUID，您可以使用下列 Python 3 範例。它會根據配置檔和片段命名空間 GUID，針對儲存在『Git』應用程式名稱下標準 Windows 終端機 Fragments 資料夾中的設定檔產生 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

若要為內建設定檔計算 GUID (例如自動產生的 WSL 設定檔)，您可以使用下列 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 片段檔案的位置，會根據想要放置 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 檔案 (此資料夾通常稱為「Public」，但可視開發人員需要命名為其他名稱)。
在 Public資料夾中，應建立名為「Fragments」的子目錄，且 JSON 檔案應儲存在該子目錄中。

從網路安裝的應用程式

若應用程式是透過網路安裝，則有 2 種情況。

第一種安裝是適用於系統上的所有使用者。在此情況下，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

請注意，ProgramData 和 LocalAppData 資料夾皆應為安裝程式能夠存取的已知資料夾。在任一情況下，若 Windows Terminal\Fragments 目錄不存在，則安裝程式應該會自行建立。 {app-name} 對您的應用程式應是唯一的，而 {file-name}.json 則沒有限制；終端機應該會讀取該目錄中的所有 .json 檔案。