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" 列表中，定义了名为“Postmodern Tango Light”的新配色方案。 可以在您的设置文件或 JSON 文件本身中使用此色彩方案（请注意，“酷炫配置文件”使用了此新定义的色彩方案）。

如果只想添加或修改配置文件而不添加配色方案，反之亦然，请仅包含相关列表并省略其他列表。

# 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

配置文件 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 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 示例。 它根据为 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应用商店应用程序

对于通过 Microsoft 应用商店安装的应用程序（或类似），应用程序必须声明自己为应用扩展。 详细了解如何 创建和托管应用扩展。 此处复制了必要的部分。 包的 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 安装的应用程序，请考虑两种情况。

第一种情况是安装适用于系统上的所有用户。 在这种情况下，请将 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 文件。

使用片段扩展分发媒体资源

从 Windows 终端 1.24 开始，片段扩展可以分发媒体资源，例如图像和像素着色器，以便与配置文件和作的属性一起使用iconbackgroundImageexperimental.pixelShaderPathexperimental.pixelShaderImagePath。

早期版本的终端支持 icon 用于和 backgroundImage. 这些版本将继续以永久的方式加载 Web URL 资源。 较新版本将不再访问 Web URL，而是会在包含片段文件的目录中查找。

如果要保持与所有可用版本的终端的兼容性，可以将任何 Web 资源放置在文件所在的同一目录中 .json 。

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

可以依赖以下兼容性行为：