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 的详细信息，请参阅下一部分）。 该列表中的第二项创建名为“冷配置文件”的新配置文件。

在 "schemes" 列表中，定义了名为“Postmodern Tango Light”的新配色方案，随后可由用户在其设置文件或此 JSON 文件中引用（请注意，“冷配置文件”使用此新定义的配色方案）。

当然，如果开发人员只希望添加/修改配置文件而不添加配色方案（反之亦然），则只需要存在相关列表，并且可以省略其他列表。

# 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

配置文件 GUID

如前所述配置文件 GUID 是一种引用配置文件的方法，允许用户更新和扩展配置文件，而无需担心位置或名称更改。 唯一可以通过片段修改的配置文件是默认配置文件、命令提示符和 PowerShell 以及 动态配置文件。 但是，强烈建议提供 GUID。

GUID 是使用支持无 BOM UTF-16LE 编码的版本 5 UUID 生成器生成的。

对于插件和片段创建的配置文件，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 示例。 它基于配置文件和片段命名空间 GUID 为存储在“Git”应用程序名称下的标准 Windows 终端片段文件夹中的配置文件生成 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 片段添加到用户设置的内容有一些最小限制：

• 对于通过片段添加的新配置文件，新配置文件必须至少定义自身的名称。
• 对于通过片段添加的新配色方案，新配色方案必须为自己定义一个名称，并定义颜色表中的每一种颜色（即颜色“黑色”通过上面的示例图像中的“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>

要注意的要点：

• 该 "Name" 字段必须为 com.microsoft.windows.terminal.settings Windows 终端能够检测扩展。
• 可以根据开发人员的意愿填写该 "Id" 字段。
• 该 "PublicFolder" 字段应具有文件夹的名称（相对于存储 JSON 文件的包根目录）（此文件夹通常称为“公共”，但如果开发人员愿意，可以命名其他名称）。
• 在公用文件夹中，应创建一个名为“Fragments”的子目录，JSON 文件应存储在该子目录中。

从 Web 安装的应用程序

对于从 Web 安装的应用程序，有 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 文件。

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

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

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

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

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

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