Windows 终端中的 JSON 片段扩展

项目
03/21/2023

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 的详细信息，请参阅下一部分）。该列表中的第二项创建一个名为“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 是使用支持无 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 终端片段文件夹中存储的名为“Git Bash”的配置文件生成一个 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

若要计算内置配置文件（如自动生成的 WSL 配置文件）的 GUID，可以使用以下 Python 3 示例。它基于 Windows 终端命名空间 GUID 为名为“Ubuntu”且自动生成以用于 WSL 分发的配置文件计算 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 片段添加到用户设置的内容有一些最小限制：

对于通过片段添加的新配置文件，新配置文件必须至少为自身定义一个名称。
对于通过片段添加的新配色方案，新配色方案必须为自身定义一个名称，并定义颜色表中的每种颜色（即上例图像中的“黑色”到“亮白色”）。

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 文件的程序包根目录（此文件夹通常称为“公用”，但如果开发人员愿意，也可以命名为其他名称）。
在公用文件夹中，应该创建一个名为“片段”的子目录，并且 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 文件。