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

Расширения фрагментов 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). Второй элемент в этом списке создает новый профиль с именем "Крутой профиль".

В списке "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 can read this
Write-Output $fragmentJson | Out-File $fragmentPath -Encoding Utf8

Если вы используете VS Code для редактирования JSON, UTF8 — это значение по умолчанию, но его можно подтвердить в нижней строке состояния.

Идентификаторы GUID профиля

Как уже упоминалось ранее, идентификаторы профилей — это способ ссылки на профили и разрешить пользователям обновлять и расширять их, не беспокоясь об изменениях расположения или имени. Вы можете изменять только профили по умолчанию, командную строку и PowerShell, а также динамические профили с помощью фрагментов. Предоставление GUID является необязательным, но настоятельно рекомендуется.

Генератор UUID версии 5 создает GUID и поддерживает кодирование UTF-16LE без BOM.

GUID пространства имен для терминала Windows в случае профилей, созданных подключаемыми модулями и фрагментами {f65ddb7e-706b-4499-8a50-40313caf510a}. Профили, созданные командой Windows Terminal, используют отдельный идентификатор GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Это разделение различает профили, созданные командой терминалов Windows, из профилей, созданных подключаемыми модулями или фрагментами, чтобы они никогда не случайно сталкивались.

Как определить GUID существующего профиля

Чтобы определить GUID профиля для обновления, рассмотрите тип профиля:

Для профиля, отправленного сторонним поставщиком и хранящегося в стандартном расположении фрагмента Windows Terminal, требуется профиль и GUID пространства имен фрагментов {f65ddb7e-706b-4499-8a50-40313caf510a}, GUID пространства имен приложения и имя профиля. Для фрагмента профиля под названием '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 Terminal под именем приложения '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 Terminal для профиля «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:

Для новых профилей, добавленных через фрагменты, новый профиль должен определить имя для себя.
Для новых цветовых схем, добавленных через фрагменты, новая цветовая схема должна самостоятельно задать себе имя и указать каждый цвет в таблице цветов (т. е. цвета от "черный" до "ярко-белый" в предыдущем примере изображения).

Место размещения файлов фрагментов 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" (общедоступная), но может быть названа чем-то другим.
В общедоступной папке создайте подкаталог с именем "Фрагменты" и сохраните ФАЙЛЫ 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

Обратите внимание, что и ProgramDataLocalAppData папки являются известными папками, к которым должен обращаться установщик. Windows Terminal\Fragments Если каталог не существует, установщик должен создать его. Он {app-name} должен быть уникальным для вашего приложения, а {file-name}.json может быть любым — терминал считывает все файлы .json в этом каталоге.

Распространение мультимедийных ресурсов с расширением на фрагменты

В Windows Terminal 1.24 расширения фрагментов могут распространять мультимедийные ресурсы, такие как изображения и шейдеры пикселей, для использования с свойствами icon, backgroundImage, experimental.pixelShaderPath и experimental.pixelShaderImagePath в профилях и действиях.

Более ранние версии Терминала поддерживали веб-URL-адреса для icon и backgroundImage. Эти версии будут продолжать загружать URL-адреса постоянно. Новые версии больше не будут обращаться к URL-адресам веб-сайтов, но вместо этого будут искать в каталоге, содержащем файл с фрагментом.

Если вы хотите обеспечить совместимость со всеми доступными версиями Терминала, вы можете разместить веб-ресурсы в том же каталоге, что и файлы .json.

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

Вы можете полагаться на следующее поведение совместимости:

Путь к ресурсу	< 1.24	≥ 1.24
`https://example.com/app/app_icon.png`	✅ загружено из Интернета	✅ загружено из `$FRAGMENT_ROOT\app_icon.png`
`app_icon.png`	❌ Проигнорировано	✅ загружено из `$FRAGMENT_ROOT\app_icon.png`
`ms-appx://MyApplication/Fragments/app_icon.png`	❌ Проигнорировано	✅ загружено из `$FRAGMENT_ROOT\app_icon.png`