Расширения фрагментов JSON в Терминале Windows

Статья
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" обновляет существующий профиль, определяя профиль, который нужно обновить, с помощью идентификатора GUID, указанного в поле "updates" (сведения о том, как получить идентификатор 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 создаются с помощью генератора UUID версии 5, который поддерживает кодировку UTF-16LE без BOM.

GUID пространства имен для Терминала Windows в случае профилей, созданных подключаемыми модулями и фрагментами, — {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, требует внутреннего идентификатора GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} Терминала Windows и имени профиля. Для профиля с именем Ubuntu, автоматически созданного во время установки WSL, результирующий идентификатор GUID будет {2c4de342-38b7-51cf-b940-2309a097f518}. В отличие от предыдущего примера с фрагментом имя приложения не используется.

Создание нового GUID профиля

Чтобы создать GUID для нового профиля перед его распространением, вы можете использовать следующий пример Python 3. Он создает GUID на основе GUID пространства имен профилей и фрагментов для профиля с именем Git Bash, хранящегося в стандартной папке фрагментов Терминал Windows в имени приложения Git, удобно соответствующего проверка.

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. Будет вычислен GUID на основе GUID пространства имен Терминала Windows для профиля с именем Ubuntu, который был автоматически создан для дистрибутива WSL, что удобно для проверки работоспособности.

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 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.

Приложения, установленные из Интернета

Для приложений, установленных из Интернета, есть два варианта.

Первый: установка предназначена для всех пользователей системы. В этом случае файлы 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 в этом каталоге.