共用方式為


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

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