Ekstensi fragmen JSON di Terminal Windows

Artikel
03/21/2023

Ekstensi fragmen JSON adalah cuplikan JSON yang dapat ditulis pengembang aplikasi untuk menambahkan profil baru ke pengaturan pengguna, atau bahkan memodifikasi profil tertentu yang ada. Mereka juga dapat digunakan untuk menambahkan skema warna baru ke pengaturan pengguna.

Struktur file JSON

File JSON harus dibagi menjadi 2 daftar, satu untuk profil dan satu untuk skema. Berikut adalah contoh file json yang menambahkan profil baru, memodifikasi profil yang sudah ada, dan membuat skema warna baru:

{
  "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"
    }
  ]
}

Item pertama dalam "profiles" daftar memperbarui profil yang ada, mengidentifikasi profil yang ingin diperbarui melalui GUID yang disediakan ke "updates" bidang (detail tentang cara mendapatkan GUID berada di bagian berikutnya). Item kedua dalam daftar tersebut membuat profil baru yang disebut "Profil Dingin".

"schemes" Dalam daftar, skema warna baru yang disebut "Postmodern Tango Light" didefinisikan, dan kemudian dapat direferensikan oleh pengguna dalam file pengaturan mereka atau dalam file JSON ini sendiri (perhatikan bahwa "Profil Dingin" menggunakan skema warna yang baru ditentukan ini).

Tentu saja, jika pengembang hanya ingin menambahkan/memodifikasi profil tanpa menambahkan skema warna (dan sebaliknya), hanya daftar yang relevan yang perlu ada dan daftar lain yang dapat dihilangkan.

Catatan

Jika Anda berencana menggunakan PowerShell untuk menghasilkan fragmen, Anda harus menggunakan -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

Jika Anda menggunakan Visual Studio Code untuk mengedit JSON, UTF8 adalah default, tetapi Anda dapat mengonfirmasi di bilah status bawah.

GUID Profil

Seperti yang dinyatakan sebelumnya, GUID profil adalah cara untuk mereferensikan profil dan memungkinkan pengguna memperbarui dan memperluasnya tanpa khawatir tentang perubahan lokasi atau nama. Satu-satunya profil yang dapat dimodifikasi melalui fragmen adalah profil default, Prompt Perintah dan PowerShell, serta profil dinamis. Namun, menyediakan GUID bersifat opsional.

GUID dihasilkan menggunakan generator UUID Versi 5 yang mendukung pengodean UTF-16LE tanpa BOM.

NAMESPACE GUID untuk Terminal Windows jika profil yang dibuat oleh plugin dan fragmen adalah {f65ddb7e-706b-4499-8a50-40313caf510a}. Profil yang dibuat oleh tim Terminal Windows menggunakan GUID terpisah ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Ini dilakukan untuk memisahkan profil yang dibuat oleh Tim Terminal Windows dari profil yang dibuat oleh plugin atau fragmen sehingga mereka tidak pernah dapat bertabrakan secara tidak sengaja.

Cara menentukan GUID profil yang ada

Untuk menentukan GUID profil yang akan diperbarui, itu tergantung pada jenis profilnya:

Profil yang dikirim oleh pihak ketiga yang disimpan di lokasi Terminal Windows Fragmen standar memerlukan GUID {f65ddb7e-706b-4499-8a50-40313caf510a}namespace profil & fragmen , GUID namespace aplikasi, dan nama profil. Untuk fragmen profil bernama 'Git Bash' yang disediakan oleh aplikasi 'Git' GUID yang dihasilkan adalah: {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}.

Profil yang dibuat secara otomatis oleh Terminal Windows memerlukan GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} internal Terminal Windows dan nama profil. Untuk profil bernama 'Ubuntu' yang dibuat secara otomatis selama penginstalan WSL, GUID yang dihasilkan adalah: {2c4de342-38b7-51cf-b940-2309a097f518}. Berbeda dengan contoh fragmen sebelumnya tidak ada 'nama aplikasi' yang terlibat.

Membuat GUID profil baru

Untuk menghasilkan GUID untuk profil yang benar-benar baru sebelum mendistribusikannya, Anda dapat menggunakan contoh Python 3 berikut. Ini menghasilkan GUID berdasarkan profil &fragmen namespace GUID untuk profil yang disebut 'Git Bash' yang disimpan dalam folder fragmen Terminal Windows standar di bawah nama aplikasi 'Git', dengan mudah mencocokkan pemeriksaan kewarasan.

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}}}")

Menghitung GUID untuk profil bawaan

Untuk menghitung GUID untuk profil bawaan, seperti profil WSL yang dihasilkan secara otomatis, Anda dapat menggunakan contoh Python 3 berikut. Ini menghitung GUID berdasarkan GUID namespace Terminal Windows untuk profil yang disebut 'Ubuntu' yang secara otomatis dihasilkan untuk distribusi WSL, dengan mudah mencocokkan pemeriksaan kewarasan.

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}}}")

Persyaratan minimum untuk pengaturan ditambahkan dengan fragmen

Ada beberapa batasan minimal pada apa yang dapat ditambahkan ke pengaturan pengguna menggunakan fragmen JSON:

Untuk profil baru yang ditambahkan melalui fragmen, profil baru harus, minimal, menentukan nama untuk dirinya sendiri.
Untuk skema warna baru yang ditambahkan melalui fragmen, skema warna baru harus menentukan nama untuk dirinya sendiri, serta menentukan setiap warna dalam tabel warna (yaitu warna "hitam" melalui "brightWhite" dalam contoh gambar di atas).

Tempat menempatkan file fragmen JSON

Lokasi untuk menempatkan file fragmen JSON bervariasi tergantung pada metode penginstalan aplikasi yang ingin menempatkannya.

Aplikasi Microsoft Store

Untuk aplikasi yang diinstal melalui Microsoft Store (atau sejenisnya), aplikasi harus mendeklarasikan dirinya sebagai ekstensi aplikasi. Pelajari selengkapnya tentang cara Membuat dan menghosting ekstensi aplikasi. Bagian yang diperlukan direplikasi di sini. File appxmanifest dari paket harus mencakup:

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

Hal-hal penting yang perlu diperhatikan:

Bidang "Name" harus agar com.microsoft.windows.terminal.settings Terminal Windows dapat mendeteksi ekstensi.
Bidang "Id" dapat diisi sesuai keinginan pengembang.
Bidang "PublicFolder" harus memiliki nama folder, relatif terhadap akar paket, tempat file JSON disimpan (folder ini biasanya disebut "Publik" tetapi dapat dinamai sesuatu yang lain jika pengembang menginginkannya).
Di dalam folder publik, subdirektori yang disebut "Fragmen" harus dibuat, dan file JSON harus disimpan di subdirektori tersebut.

Aplikasi yang diinstal dari web

Untuk aplikasi yang diinstal dari web, ada 2 kasus.

Yang pertama adalah bahwa penginstalan adalah untuk semua pengguna pada sistem. Dalam hal ini, file JSON harus ditambahkan ke folder:

C:\ProgramData\Microsoft\Windows Terminal\Fragments\{app-name}\{file-name}.json

Dalam kasus kedua, penginstalan hanya untuk pengguna saat ini. Dalam hal ini, file JSON harus ditambahkan ke folder:

C:\Users\<user>\AppData\Local\Microsoft\Windows Terminal\Fragments\{app-name}\{file-name}.json

Perhatikan bahwa folder ProgramData dan LocalAppData adalah folder yang diketahui yang harus dapat diakses oleh alat penginstal. Jika dalam kedua kasus, jika Windows Terminal\Fragments direktori tidak ada, alat penginstal harus membuatnya. {app-name} harus unik untuk aplikasi Anda dan {file-name}.json bisa apa saja - terminal akan membaca semua file .json di direktori tersebut.

Bagikan melalui