Langsung ke konten utama
Mod dapat menggambar antarmukanya sendiri di Claude Code dan mengubah bagian antarmuka yang sudah digambar Claude Code. Setiap tempat mod dapat menggambar disebut render site, seperti panel, pita di atas prompt, atau spinner. Claude Code menaikkan event ui.render setiap kali akan menggambar render site, dan hook Anda untuk event tersebut mengembalikan apa yang akan digambar di sana. Peta ini menunjukkan di mana mod dapat menggambar dalam sesi terminal: Peta sesi terminal Claude Code dalam rendering layar penuh. Mod dapat menambahkan panel sebagai sidebar di sebelah kanan, toast di sudut kanan atas transkrip, baris log dalam transkrip, pita di atas prompt, dan baris status di bawah prompt. Mod dapat menggambar ulang pesan, baris panggilan tool, dan spinner. Prompt adalah milik Claude Code sendiri. Peta sesi terminal Claude Code dalam rendering layar penuh. Mod dapat menambahkan panel sebagai sidebar di sebelah kanan, toast di sudut kanan atas transkrip, baris log dalam transkrip, pita di atas prompt, dan baris status di bawah prompt. Mod dapat menggambar ulang pesan, baris panggilan tool, dan spinner. Prompt adalah milik Claude Code sendiri. Di terminal yang lebih sempit, panel duduk di atas prompt daripada di samping transkrip. Bangun mod pertama Anda sebelum Anda mulai di sini. Mulai dengan contoh yang dikerjakan, yang membangun panel dengan dua tab dan penghitung, kemudian baca bagian untuk setiap bagian yang ingin Anda ubah.
Untuk mencari satu prop atau batas, lihat referensi.

Bangun panel dengan tab

Di bagian ini Anda membangun mod yang menambahkan perintah /hello-tabs, dan perintah membuka panel. Panel adalah sidebar di samping transkrip dalam terminal fullscreen yang lebar, atau wilayah berbingkai di atas prompt sebaliknya. Panel ini menampilkan dua tab, dan tab kedua memiliki tombol yang menambah satu ke penghitung. Hitungan masih ada setelah Anda memulai ulang Claude Code. Mod yang selesai terlihat seperti ini. Rekaman membuka panel, beralih ke tab kedua, menekan tombol beberapa kali, dan kembali ke tab pertama:
Tab-tab tersebut adalah dua tombol dalam satu baris. Mod melacak mana yang aktif dan menggambar konten tab tersebut di bawah baris.
1

Buat plugin

Mod adalah plugin dengan manifest, hooks.json yang menunjuk ke kode Anda, dan file kode. Buat mod menjelaskan masing-masing. Buat direktori bernama hello-tabs dengan direktori .claude-plugin dan hooks di dalamnya, kemudian simpan dua file pertama.Simpan manifest sebagai hello-tabs/.claude-plugin/plugin.json:
hello-tabs/.claude-plugin/plugin.json
Beri nama titik masuk Anda di hello-tabs/hooks/hooks.json:
hello-tabs/hooks/hooks.json
2

Tulis kodenya

Daftar ini menjelaskan apa yang dilakukan setiap hook, sesuai urutan kemunculannya dalam kode:
  • Menambahkan perintah /hello-tabs, dan memuat hitungan yang disimpan sesi sebelumnya
  • Membuka panel saat Anda menjalankan perintah tersebut
  • Menggambar konten panel: baris tab dan badan tab yang terbuka
Dua variabel tingkat modul, tab dan count, menyimpan status panel.Simpan ini sebagai hello-tabs/hooks/register.js:
hello-tabs/hooks/register.js
Setiap hook juga melakukan sesuatu yang tidak jelas dari kode:
  • session.start juga membaca hitungan yang disimpan dari $.store, penyimpanan kunci-nilai yang bertahan antar sesi.
  • command.run hanya memberi tahu Claude Code bahwa panel ada. Membuka panel tidak menggambar apa pun dengan sendirinya: Claude Code kemudian menaikkan ui.render untuk menanyakan apa yang ada di dalamnya.
  • ui.render mengembalikan pohon elemen, Box yang menyimpan kotak lain, teks, dan tombol, dan membangunnya lagi dari tab dan count setiap kali berjalan.
Menekan tombol menjalankan callback onPress-nya, yang mengubah variabel dan memanggil redraw. Claude Code kemudian menjalankan hook ui.render lagi, dan hook membangun pohon baru dari nilai baru. Setiap gambar interaktif menggunakan siklus render itu: callback mengubah status, dan hook merender lagi dari status baru.
3

Buka panel

Di shell Anda, mulai Claude Code dengan claude --plugin-dir ./hello-tabs. Di prompt Claude Code, jalankan /hello-tabs. Panel terbuka dengan 1: One dan 2: Two di seluruh bagian atas. Tekan 2, kemudian tekan a, pintasan keyboard untuk Add one, beberapa kali. Hitungan naik.
4

Periksa bahwa hitungan disimpan

Tekan Esc untuk menutup panel, kemudian keluar dari sesi. Di shell Anda, mulai Claude Code lagi dengan perintah claude --plugin-dir ./hello-tabs yang sama, dan di prompt Claude Code jalankan /hello-tabs. Hitungan ada di mana Anda meninggalkannya.Untuk menghapus hitungan, buat mod memanggil $.store.delete('count'). Jaga status mencakup berapa lama setiap jenis nilai bertahan.

Pilih tempat untuk menggambar

Untuk memilih titik render tempat hook ui.render menggambar, berikan filter, yang disebut matcher, sebagai argumen kedua untuk on. { component: 'Pane' } menjalankan hook hanya untuk panel. Di dalam hook, e.component menyebutkan nama titik render, e.surface menyatakan aplikasi mana yang sedang menggambar, dan e.props menyimpan data milik titik render tersebut. Untuk panel, e.requestId adalah id yang Anda gunakan saat membukanya. Panel dan pita kosong hingga sebuah mod mengisinya. Pilih tab untuk melihat apa masing-masing dan cara menggambar di dalamnya:
Panel adalah bilah samping di sebelah transkrip pada terminal layar penuh yang lebar, atau area berbingkai di atas prompt jika tidak demikian. Ketika beberapa panel terbuka, masing-masing mendapatkan tab yang menampilkan judulnya.Panel muncul ketika mod Anda memanggil $.ui.open dengan id yang Anda pilih, seperti dalam $.ui.open({ id: 'hello-tabs' }). Buka panel pada waktu yang tepat membahas field lainnya dan kapan panel menunggu terminal yang lebih lebar.Untuk menggambar di panel Anda, filter dengan { component: 'Pane' } dan periksa bahwa e.requestId adalah id Anda.
Sebuah mod juga dapat menempatkan barisnya sendiri di transkrip.

Mengubah apa yang sudah digambar Claude Code

Claude Code menggambar sebagian besar antarmukanya sendiri: pesan, baris panggilan tool, spinner, dan lainnya. Masing-masing bagian tersebut juga merupakan titik render, sehingga sebuah mod dapat mengubah gayanya atau menggantinya. Untuk mengubah salah satunya, filter hook ui.render Anda dengan namanya dari tabel ini: Pane, AskUserQuestion, Spinner, UserMessage, AssistantMessage, dan titik panggilan tool berfungsi di terminal, aplikasi Desktop, dan ekstensi VS Code. Tabel titik render mencantumkan di mana masing-masing titik lainnya dimunculkan. Pada titik yang sudah digambar Claude Code, hook Anda dapat mengubah detail, mengganti gambarnya, atau membiarkannya. Pilih tab untuk melihat masing-masing diterapkan pada spinner. Contoh-contoh ini membaca variabel calls yang dihitung oleh hook lain, seperti dalam mod tutorial.
Untuk mempertahankan gambar Claude Code dan mengubah satu bagiannya, berikan kepada next salinan event dengan props yang diubah. Hook ini mengubah teks setelah kata spinner:
Spinner mempertahankan animasi dan katanya, dan teks Anda mengikuti kata tersebut:
Pada titik-titik ini, next(e) mengembalikan referensi ke gambar Claude Code, { type: 'engine', ref }, kecuali jika sebuah mod yang berjalan setelah milik Anda mengembalikan tree-nya sendiri. Untuk mengubah isi gambar tersebut, berikan kepada next salinan event dengan props yang berbeda, seperti yang dilakukan tab Mengubah detail. Anda dapat mengembalikan referensi apa adanya, atau menempatkannya di dalam Box di samping elemen Anda sendiri:
Saat Claude bekerja, spinner beranimasi seperti sebelumnya, dan under the spinner muncul di bawahnya. Dialog izin bukan titik render, sehingga sebuah mod tidak dapat mengubah apa yang ditampilkannya. Dialog pertanyaan, AskUserQuestion, adalah titik render, sehingga sebuah mod dapat mengubah dialog tersebut ketika Claude mengajukan pertanyaan. Tree untuk dialog tersebut harus memuat referensi tepat satu kali, dengan elemen Anda di atasnya. Jika tidak, Claude Code menggambar dialognya sendiri.

Buka panel pada waktu yang tepat

Panel hanya muncul ketika mod Anda membukanya. Cara dan waktu Anda membukanya menentukan apakah panel tersebut mengambil fokus keyboard, berapa banyak ruang yang dimintanya, dan apakah panel tersebut ditampilkan sama sekali di terminal yang sempit. Untuk membuka panel, panggil $.ui.open dengan id yang Anda pilih. id adalah nama panel: hook ui.render Anda memeriksanya, dan Anda memberikannya lagi untuk menutup panel. Jika mod lain memiliki panel yang terbuka dengan id tersebut, panggilan akan ditolak.
Untuk menutup panel, panggil $.ui.close dengan id yang Anda gunakan saat membukanya:
Selain id, $.ui.open menerima field opsional berikut: Ekstensi VS Code mengabaikan rows dan columns dan menentukan ukuran panel sendiri. focus, closeOnEscape, dan holdToasts bersifat opsional dan hanya menerima true. Untuk tidak menggunakannya, hilangkan field tersebut. Memberikan false akan memunculkan error seperti ui.open: focus is true or left out. Untuk menetapkan salah satunya secara kondisional, tambahkan field tersebut hanya ketika kondisinya terpenuhi. Panggilan ini meminta fokus keyboard hanya ketika items tidak kosong:
Agar sebuah perintah dapat membuka panel saat Claude sedang bekerja, tambahkan immediate: true saat Anda mendaftarkan perintah. Tanpanya, perintah yang diketik selama giliran berlangsung akan menunggu hingga giliran berakhir.

Menahan toast di balik dialog

Berikan holdToasts: true ke $.ui.open ketika panel adalah dialog yang dijawab lalu ditinggalkan pengguna, sehingga toast tidak muncul saat mereka memutuskan. Di terminal, penahanan berlangsung selama panel tersebut yang sedang ditampilkan, dan toast yang dimunculkan dalam waktu tersebut menunggu hingga penahanan berakhir. Claude Code menahan toast dari mod lain dan notifikasi singkatnya sendiri, selain toast yang dimunculkan mod Anda dengan $.ui.toast. Jangan gunakan field ini pada panel yang tetap terbuka, agar pengguna tetap dapat melihatnya.

Ketika panel menunggu terminal yang lebih lebar

Panel yang dibuka mod Anda tanpa diminta tidak muncul di terminal yang sempit, sehingga panel tersebut tidak dapat mengambil alih layar kecil. Apakah panel muncul bergantung pada apa yang membukanya:
  • Dibuka oleh sesuatu yang dilakukan pengguna, seperti perintah yang mereka jalankan atau tombol yang mereka tekan, panel muncul pada lebar berapa pun
  • Dibuka oleh mod Anda yang bertindak sendiri, seperti dari timer atau hook turn.start, panel hanya muncul di terminal dengan lebar minimal 144 kolom. Setelah pengguna membuka panel tersebut sendiri sekali, 110 kolom sudah cukup.
Ketika panel muncul, $.ui.open di-resolve menjadi { isPlaced: true }. Ketika panel sedang menunggu, isPlaced bernilai false dan reason adalah string yang menjelaskan alasannya. Panel yang menunggu muncul ketika pengguna membukanya atau melebarkan terminal. Untuk memberi tahu bahwa sesuatu tersedia tanpa membuka panel, panggil $.ui.toast('Your message'), yang menampilkan notifikasi toast.

Menggambar di ekstensi VS Code

Di ekstensi VS Code, apa yang digambar sebuah mod muncul di panel chat dengan ekstensi versi 2.1.299 atau lebih baru. Sesi yang tidak mengambil feature flag, seperti sesi di Amazon Bedrock, memerlukan versi 2.1.304 atau lebih baru. Dalam hook ui.render untuk panel tersebut, e.surface bernilai vscode. Untuk memeriksa titik render dan elemen mana yang digambar panel, serta props mana yang diabaikannya, lihat tabel titik render dan elemen. Agar sebuah mod berfungsi di panel sekaligus di terminal, perhitungkan perbedaan berikut:
  • Panel: pada panel chat dengan lebar 800 piksel atau lebih, panel-panel berlabuh di samping percakapan, e.props.placement bernilai 'dock', dan e.viewport.isFullscreen bernilai true. Pada panel chat yang lebih sempit, panel-panel digambar di atas kotak prompt, placement bernilai 'inline', dan sebuah panel menampilkan 12 baris sebelum menggulir.
  • Toast dan baris status: semuanya berada dalam satu tumpukan tepat di atas kotak prompt, bersama dengan panel-panel ketika panel chat sempit, dengan satu baris status per mod. Tumpukan tersebut disembunyikan saat permintaan izin atau dialog ditampilkan.
  • Label: panel chat membingkai apa yang digambar atau ditulis ulang oleh sebuah mod dan memberinya label dengan nama plugin, seperti From the token-chart plugin atau Edited by the token-chart plugin.
  • Keyboard: tombol tidak memiliki hotkey, sehingga pengguna mengklik tombol atau menekan Enter pada tombol tersebut setelah tombol mendapatkan fokus.
  • Fokus keyboard: panel chat mengabulkan permintaan focus: true dari sebuah panel hanya ketika panel chat memiliki fokus, Claude sedang idle tanpa pertanyaan yang menunggu, dan kotak prompt kosong.
  • Dialog pertanyaan: pada AskUserQuestion, panel chat mempertahankan kartu pertanyaannya sendiri dan menggambar elemen Anda di atasnya. Props yang Anda berikan ke next tidak mengubah kartu tersebut.
  • Saran prompt: $.prompt.suggest di-resolve dengan isShown: false dan tidak menampilkan apa pun, karena panel chat menyimpan teks saran redup di kotak prompt untuk saran Claude sendiri.
  • Batas teks: panel chat memotong baris status pada 200 karakter atau dua baris, dan toast pada 500 karakter.

Menempatkan baris di transkrip

Baris adalah satu baris yang ditambahkan mod Anda ke transkrip di terminal, setelah pesan terbaru. Baris tersebut tetap berada di posisi itu seiring berjalannya percakapan, dan Claude tidak melihatnya. $.ui.place memerlukan Claude Code v2.1.314 atau lebih baru.
1

Tempatkan baris

Panggil $.ui.place dengan sebuah id. id adalah nama yang Anda buat untuk baris tersebut, seperti build-status. Nama ini dapat berisi 1 hingga 64 huruf, digit, _, atau -, dan setiap baris yang dimiliki mod Anda di transkrip memerlukan id-nya sendiri.
2

Gambar baris

Gambar baris tersebut pada titik render Placed.
Contoh ini menambahkan perintah /build-status. Ketika pengguna menjalankan perintah tersebut, mod menambahkan baris yang menampilkan Build: passing. Teksnya tetap agar contoh ini singkat, sehingga mod sungguhan akan menggambar hasilnya sendiri:
Untuk mencoba contoh ini, letakkan kode ini di sebuah mod. Dalam sesi terminal, jalankan /build-status di prompt Claude Code. Build: passing muncul sebagai baris di akhir transkrip. Panggilan tersebut tidak selalu menampilkan baris, dan sebuah baris dapat hilang kemudian, jadi tangani kasus-kasus berikut di mod Anda:
  • Hasilnya: { isPlaced: true, requestId } ketika terminal menggambar baris tersebut. Jika tidak, isPlaced bernilai false dan reason menjelaskan alasannya, seperti no attached surface draws placed rows yet. Salah satu alasannya adalah batas jumlah baris yang dapat dimiliki sebuah mod pada satu waktu.
  • Panggilan kedua dengan id yang sama: selama baris pertama masih ada di transkrip, panggilan tersebut tidak menambahkan baris dan di-resolve dengan requestId dari baris tersebut. Untuk mengubah apa yang ditampilkan baris, gambar ulang baris tersebut.
  • Ketika baris hilang: ketika percakapan berakhir, ketika pengguna melakukan rewind melewati baris tersebut, atau, di luar rendering layar penuh, ketika percakapan dipadatkan. --resume tidak mengembalikan baris tersebut. Untuk menampilkan baris lagi, panggil $.ui.place lagi.

Memasang latar belakang di balik percakapan

$.theme.set dan $.theme.clear menggantikan $.ui.backdrop, yang telah dihapus di Claude Code v2.1.319. Ubah $.ui.backdrop({ id: 'your-backdrop' }) menjadi panggilan $.theme.set seperti yang ada dalam contoh di bagian ini, dan $.ui.backdrop(undefined) menjadi $.theme.clear(), yang menghapus latar belakang dari mod mana pun.
Untuk memasang latar belakang di balik percakapan di aplikasi Desktop atau aplikasi seluler, panggil $.theme.set dengan backdrop, lalu gambar latar belakang tersebut pada titik render Backdrop. Untuk melepas latar belakang, panggil $.theme.clear(). Terminal tidak menggambar latar belakang. $.theme.set dan $.theme.clear memerlukan Claude Code v2.1.319 atau lebih baru. Contoh ini memerlukan Claude Code v2.1.323 atau lebih baru, jadi periksa versi Anda terlebih dahulu. Mod ini memasang latar belakang saat sesi dimulai, menggambar latar belakang tersebut, dan menambahkan perintah /plain yang melepas latar belakang:
Sebelum v2.1.323, tulis id sebagai pengganti scene dalam panggilan $.theme.set dan di e.props, serta pindahkan overrideColorScheme ke dalam backdrop sebagai colorScheme.
Untuk mencoba contoh ini, letakkan kode ini di sebuah mod dan mulai sesi di aplikasi Desktop atau aplikasi seluler. Untuk melepas latar belakang, jalankan /plain di prompt Claude Code. Transkrip menampilkan the theme is cleared setelah nama mod, seperti night-sky: the theme is cleared untuk mod bernama night-sky. Periksa apa yang diterima backdrop, apa yang diberitahukan hasil panggilan kepada Anda, dan apa yang dapat diubah oleh mod lain:
  • Field backdrop: scene adalah nama yang Anda pilih untuk latar belakang yang digambar oleh hook Anda. Untuk field lainnya dan overrideColorScheme, lihat tipe untuk build Anda.
  • Apakah latar belakang digambar: $.theme.set di-resolve dengan isDrawn: true ketika aplikasi Desktop atau seluler yang terhubung ke sesi menyatakan bahwa aplikasi tersebut menggambar latar belakang. Jika tidak, isDrawn bernilai false dan reason menjelaskan alasannya.
  • Satu tema untuk setiap sesi: mod yang memanggil $.theme.set menggantikan latar belakang dan warna sesi, dan mod yang memanggil $.theme.clear() menghapusnya, mod mana pun yang memasangnya. Panggil $.theme.clear() hanya ketika pengguna memintanya.

Mengubah warna aplikasi Desktop

Untuk mengubah warna tab Code di aplikasi Desktop dengan sebuah mod, minta Claude membuatkannya atau tulis sendiri. Kedua cara tersebut memerlukan Claude Code v2.1.324 atau lebih baru di tab Code, jadi periksa versinya di sana terlebih dahulu. Claude Code di terminal tetap menggunakan warnanya sendiri.

Meminta Claude membuatkan mod warna

1

Jelaskan warnanya

Mulai sesi lokal di tab Code dan beri tahu Claude warna yang Anda inginkan. Misalnya, masukkan make a mod that makes the app cream in light mode and dark brown in dark mode. Claude menulis file-file mod tersebut.
2

Setujui mod

Jawab pertanyaan yang diajukan Claude Code tentang file-file mod dan hot reloading. Untuk fungsi setiap jawaban, lihat Meminta Claude membuatkan mod.
3

Periksa warnanya

Tab Code berubah warna ketika mod dimuat. Untuk menyesuaikan sebuah warna, beri tahu Claude apa yang perlu diubah. Jika tidak ada yang berubah, lihat Memperbaiki warna mod yang tidak muncul.

Menulis mod warna sendiri

makeColors adalah fungsi yang membangun tema dari beberapa warna hex. Langkah-langkah berikut membuat mod bernama paper yang menggunakannya.
1

Minta Claude menyalin makeColors

Mulai sesi lokal di tab Code, dan masukkan copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/. Periksa bahwa kedua file tersebut ada di direktori itu.
2

Simpan manifest dan hooks.json

Dari Menulis mod sendiri, simpan .claude-plugin/plugin.json dan hooks/hooks.json di ~/.claude/skills/paper/, dan ubah first-mod menjadi paper di kedua file tersebut. Mod di bawah ~/.claude/skills/ dimuat saat Anda memulai sesi.
3

Tulis kodenya

Simpan file ini sebagai ~/.claude/skills/paper/hooks/register.js. Saat sesi dimulai, kode ini memanggil $.theme.set dengan warna untuk mode terang dan mode gelap:
Untuk menggunakan warna Anda sendiri, ganti nilai hex dengan warna hex enam digit lainnya.
4

Periksa warnanya

Mulai sesi lokal baru di tab Code. Dengan nilai dari contoh ini, latar belakangnya berwarna krem dalam mode terang dan cokelat tua dalam mode gelap. Jika tidak ada yang berubah, lihat Memperbaiki warna mod yang tidak muncul.

Memperbaiki warna mod yang tidak muncul di aplikasi Desktop

Jika Anda menggunakan penyedia pihak ketiga alih-alih akun Claude di Claude Desktop v5.11492.5 atau lebih lama, tab Code tetap menggunakan warnanya sendiri, jadi lewati pemeriksaan ini. Selain itu, jika warna sebuah mod tidak muncul di tab Code, atau jika warnanya menghilang, periksa penyebab berikut:
  • Versi lama: perbarui aplikasi Desktop, mulai ulang aplikasi, dan mulai sesi lokal baru di tab Code. Jika Claude yang menulis mod tersebut, minta lagi di sana.
  • Mod tidak dimuat: jika Claude yang menulis mod tersebut, lihat kapan mod dimuat di Meminta Claude membuatkan mod. Jika Anda yang menulisnya, bandingkan file-file Anda dan path-nya dengan Menulis mod warna sendiri.
  • Tema ditolak: minta Claude menjalankan panggilan makeColors milik mod. Jika panggilan tersebut memunculkan error, atau daftar problems-nya memiliki entri yang diawali dengan Desktop won't paint this theme, minta Claude memperbaiki tema tersebut. Jika Anda menginstal mod tersebut, kirimkan temuan Claude kepada pembuatnya.
  • Panggilan $.theme lain: ketika mod mana pun dalam sesi memanggil $.theme.set atau $.theme.clear(), warna dan latar belakang dari panggilan sebelumnya menghilang. Dalam mod Anda sendiri, berikan colors dan backdrop dalam panggilan $.theme.set yang sama. Gunakan hanya satu mod yang menetapkan tema pada satu waktu.

Menghapus warna mod dari aplikasi Desktop

Untuk melepas warna sebuah mod dari tab Code, matikan mod tersebut terlebih dahulu. Mod yang masih aktif dapat menetapkan warnanya lagi.
1

Matikan mod

2

Mulai sesi baru

Mulai sesi lokal baru di tab Code.
3

Hapus warna yang tetap ada

Jika warnanya masih ada, buka Settings dari tab Code, dan cari code appearance di sana. Buka hasilnya, lalu pilih Remove colors.

Bangun pohon dari elemen

Apa yang dikembalikan hook ui.render adalah pohon elemen: deskripsi apa yang akan digambar, terbuat dari kotak, teks, dan kontrol bersarang di dalam satu sama lain. Anda mendeskripsikan gambar, dan Claude Code merendernya di aplikasi mana pun yang dibuka pengguna: terminal, aplikasi Desktop, atau ekstensi VS Code. Untuk mendapatkan elemen, panggil $.ui.resolve(e) dalam hook Anda, seperti dalam const { Box, Text, Button } = $.ui.resolve(e). Setiap elemen adalah fungsi. Anda meneruskan prop, dan Anda menempatkan elemen dan string yang ada di dalamnya dalam children. Pilih tab untuk melihat setiap elemen yang paling umum dan cara terminal menggambarnya:
Text menggambar string, dengan gaya opsional seperti bold dan color:
Galeri antarmuka memiliki contoh dan tangkapan layar dari sebagian besar elemen. Tabel ini mencantumkan elemen-elemen utama: Jika modul Anda adalah file .tsx atau .jsx, Anda dapat menulis pohon sebagai JSX. Dekonstruksi elemen dari $.ui.resolve(e) terlebih dahulu. Jika gambar Anda tidak muncul, periksa pohonnya untuk prop yang tidak diambil oleh elemen atau anak di tempat yang tidak seharusnya ada. Hook yang mengembalikan pohon seperti itu gagal, dan baris hook skipped menyebutkan mod Anda dan aturan yang dilanggar pohon tersebut. Untuk Text di panel dengan prop bernama bogusProp, baris itu berbunyi:
Di aplikasi Desktop dan ekstensi VS Code, Link digambar sebagai teks biasa kecuali href-nya memenuhi persyaratan berikut:
  • Skema dan host: URL https:, atau URL http://localhost seperti http://localhost:3000
  • Tanpa @: tulis @ di path atau query sebagai %40
  • Ejaan: apa yang dikembalikan new URL(href).href, selain / yang tidak ada setelah host. Hal itu mengecualikan host dengan huruf besar, spasi, dan :443 pada URL https:.
Di terminal, persyaratan ini tidak berlaku.

Saat Client gagal

Di terminal, saat file yang dijalankan Client gagal, baris redup seperti my-mod: Client client/spinner.js: boom menggantikan tempat Client, dan sisa gambar Anda tetap ditampilkan. Jika mod Anda menangani ui.fault, Claude Code kemudian menggambar situs lagi.

Gambar grid sel berwarna

Untuk peta panas, sparkline, atau papan permainan di terminal, gambar satu Raster dan bukan Box untuk setiap sel. Raster mengambil key, ukurannya dalam columns dan rows, dan cells, string base64 yang mengemas setiap sel. Setiap sel adalah tiga angka: titik kode karakter, warnanya, dan warna latar belakangnya. Warna adalah nilai RGB 24-bit dalam heksadesimal, seperti 0xc62828 untuk merah. Nilai 0x01000000, satu di atas rentang tersebut, berarti default terminal. Aplikasi selain terminal tidak memiliki Raster, jadi periksa e.surface dan gambar teks di sana. Badan panel ini menggambar peta panas tiga kali dua:
Di terminal, panel menampilkan grid: Panel di terminal yang menyimpan grid kecil blok berwarna, dua baris tiga. Baris atas adalah hijau, amber, dan merah. Baris bawah adalah hijau, hijau, dan amber. Array rows adalah bagian yang akan Anda ubah, dan cellsOf mengubahnya menjadi string yang dikemas. Hook menggambar hanya di panel yang id-nya adalah heat, jadi buka satu dengan $.ui.open({ id: 'heat' }) dari perintah, seperti contoh hello-tabs membuka panelnya. Setiap karakter harus lebar satu sel. Untuk menganimasikan Raster yang sudah di layar, panggil $.ui.blit dengan id panel sebagai requestId, key Raster, ukuran yang sama, dan sel baru. Untuk contoh ini, itu adalah $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }). Itu melukis ulang elemen itu saja tanpa menjalankan hook ui.render Anda lagi.

Merespons penekanan dan pengetikan

Ketika pengguna menekan tombol, mengetik ke bidang, atau memilih dari daftar yang digambar mod Anda, Claude Code memanggil callback kontrol itu, yang berjalan dalam modul Anda. Setiap kontrol mengambil callback-nya sendiri:
  • Button: mengambil onPress(e), di mana e.surface adalah aplikasi tempat penekanan berasal
  • Input: mengambil onSubmit(value) dan onInput(value)
  • Select: mengambil onSelect(value) dengan pilihan dalam options, daftar setidaknya satu pilihan dengan nilai unik, seperti [{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]

Kontrol mana yang memerlukan key

Berikan prop key pada setiap Input dan Select, seperti key: 'size'. Button boleh tidak memiliki key ketika memiliki prop label atau satu anak berupa string. Key-nya kemudian adalah nilai label atau string tersebut. Tes dan mod lain mengidentifikasi kontrol berdasarkan key-nya:
  • Tes: sebuah tes menekan atau mengetik ke kontrol berdasarkan key-nya.
  • Mod lain: Claude Code menembakkan ui.press, ui.input, atau ui.select dengan key kontrol dalam e.element sebelum menjalankan callback kontrol tersebut. Hook mod lain juga dapat berjalan untuk event tersebut. Hook itu melihat apa yang pengguna ketik ke Input Anda dan dapat mengubah teks itu atau mencegah callback Anda berjalan. API mods tidak memberi mod tersebut metode untuk menekan tombol Anda.
Jika sebuah pesan mengatakan needs a key atau is drawn twice, temukan penyebabnya berdasarkan pesan tersebut.

Fokus keyboard dan pintasan keyboard

Mod Anda tidak pernah membaca keyboard itu sendiri. Pengguna menekan kunci, Claude Code memutuskan kontrol mana yang dimaksudkan, dan callback kontrol itu berjalan. Kecuali untuk pintasan keyboard digit di pita atau pengikatan action, itu hanya terjadi saat panel atau pita Anda memiliki fokus keyboard. Sisa waktu, kunci pergi ke prompt. Di ekstensi VS Code, tombol tidak memiliki pintasan keyboard: pengguna mengklik tombol atau menekan Enter padanya, dan mengetik ke bidang.

Bagaimana panel mendapat fokus keyboard

Panel mendapat fokus keyboard ketika:
  • Mod Anda membukanya dengan focus: true dari perintah atau penekanan
  • Pengguna menekan Ctrl+X kemudian Tab
  • Pengguna mengkliknya, yang di terminal memerlukan rendering layar penuh
Claude Code memberikan focus: true hanya saat prompt kosong dan tidak ada yang lain memiliki fokus keyboard. Panel yang terbuka saat pengguna mengetik tidak mengambil keystroke mereka.

Apa yang dilakukan setiap kunci

Tabel ini mencantumkan apa yang dilakukan kunci saat panel atau pita Anda memiliki fokus keyboard: Mod tidak dapat mengikat Tab atau tombol panah ke apa pun yang lain, jadi permainan mengarahkan dengan w, a, s, dan d.

Atur pintasan keyboard dan fokus pertama

  • hotkey: untuk membiarkan pengguna menekan Button dengan satu kunci, berikan hotkey dari satu digit atau satu huruf kecil, seperti dalam hotkey: 'a'
  • autoFocus: untuk memilih kontrol mana yang memiliki fokus saat panel terbuka, tambahkan autoFocus: true ke dalamnya. Di ekstensi VS Code, autoFocus tidak melakukan apa-apa: kontrol digambar seolah-olah Anda tidak menyertakannya, dan Anda tidak perlu mengubah apa pun. Prop ini hanya menerima true, jadi hilangkan pada kontrol lainnya.
Bagaimana pintasan keyboard ditampilkan tergantung pada tombol dan aplikasi: Di terminal, beri nama kunci dalam label tombol berbingkai, atau gunakan plain: true, sehingga pengguna dapat melihat apa yang harus ditekan. Referensi elemen memiliki aturan Button lainnya: action, pintasan keyboard digit di pita, dan dua tombol pada satu pintasan keyboard.

Saat pengguna menciutkan pita

Di terminal, saat mod menggambar di pita, pengguna dapat menciutkan pita menjadi satu baris agar tidak menghalangi:
  • Klik [-]: saat pita dibentangkan, Claude Code menggambar tanda ini di ujung kanan baris pertamanya. Dalam rendering layar penuh, pengguna mengkliknya untuk menciutkan pita.
  • Tekan Ctrl+X kemudian Ctrl+A: ini berfungsi baik saat prompt, pita, atau panel yang memiliki fokus keyboard. Pengguna dapat mengikat kunci lain ke sini melalui aksi abovePrompt:toggle.
Pita yang diciutkan menyembunyikan semua yang digambar mod di sana dan sebagai gantinya menampilkan satu baris redup, yang menyebutkan kunci untuk membentangkannya sesuai pengikatan yang dimiliki pengguna:
Kunci yang sama, atau dalam rendering layar penuh sebuah klik pada baris tersebut, membentangkan pita kembali. Sampai saat itu, tidak ada yang menekan tombol di dalamnya: tidak ada pintasan keyboard, tidak ada digit yang diketik ke prompt kosong, dan tidak ada pintasan keyboard untuk action sebuah tombol. Jika pita memiliki fokus keyboard saat pengguna menciutkannya, fokus kembali ke prompt, dan Ctrl+X kemudian Tab melewati pita selama pita diciutkan. Pita tetap diciutkan sampai pengguna membentangkannya, bahkan setelah /clear, dan dibentangkan kembali saat Claude Code dimulai berikutnya. Mod Anda tidak dapat membentangkannya. Jangan jadikan pita sebagai satu-satunya tempat mod Anda menampilkan sesuatu yang harus dijawab pengguna. Untuk menampilkannya di tempat lain hanya selama pita diciutkan, baca e.props.isCollapsed dalam hook ui.render Anda, yang tetap berjalan. isCollapsed memerlukan Claude Code v2.1.321 atau yang lebih baru.

Ambil input yang diketik dan gambar baris untuk setiap item

Banyak panel adalah bidang teks dengan daftar di bawahnya. Contoh di bagian ini adalah panel catatan: Anda mengetik catatan dan menekan Enter untuk menambahkannya, dan setiap catatan memiliki tombol x yang menghapusnya. Dengan dua catatan ditambahkan, terminal menggambar panel dengan cara ini:
✕ di batas atas adalah tanda milik Claude Code sendiri untuk menutup panel. Contoh menggunakan teknik berikut:
  • Ambil input yang diketik: Input memanggil onSubmit(value) dengan teks bidang saat pengguna menekan Enter, dan onInput(value) pada setiap perubahan
  • Gambar daftar: petakan data Anda ke satu baris masing-masing, dan berikan setiap tombol baris key-nya sendiri
Hook ini menggambar konten panel:
Untuk mencoba panel:
  • Tambahkan catatan: ketik baris dan tekan Enter. Baris muncul sebagai baris baru, dan bidang kosong.
  • Hapus catatan: tekan Tab sampai tombol x catatan memiliki fokus, kemudian tekan Enter. x adalah label tombol dan bukan pintasan keyboard, jadi mengetik huruf tidak menekan itu.
Setiap perubahan mengikuti siklus render yang sama seperti hello-tabs: callback mengubah notes, memanggil redraw, dan menyimpan daftar ke $.store. Jika hook Anda menggambar panel lagi saat pengguna sedang mengetik catatan, bidang mempertahankan teks mereka selama hook meneruskan value yang sama setiap kali. Untuk mengganti teks mereka dengan teks Anda sendiri, teruskan value yang berbeda. Contoh menyimpan catatan dan tidak memuatnya. Untuk membawanya kembali di sesi berikutnya, bacalah dalam hook session.start, cara hello-tabs membaca count. Prop berikut membentuk baris bidang, Note: Type a note and press Enter ⏎ add: Mengirimkan Input tidak memulai giliran kecuali callback Anda memanggil $.prompt.submit.

Gambar ulang situs

Gambar adalah snapshot: itu menunjukkan apa yang dikembalikan hook ui.render Anda terakhir kali hook berjalan. Untuk menampilkan sesuatu yang baru, hook harus berjalan lagi. Claude Code menjalankannya lagi untuk beberapa perubahan, dan mod Anda meminta sisanya.

Ketika Claude Code menggambar ulang tanpa diminta

Claude Code menjalankan hook ui.render Anda lagi ketika prop situs berubah atau lebar terminal berubah. Ketika sebuah Client di situs gagal dan mod Anda menangani ui.fault, Claude Code menjalankan hook sekali lagi setelah hook ui.fault Anda kembali, sehingga hook ui.render Anda dapat menghilangkan Client tersebut. Itu tidak menjalankan hook pada timer, dan itu tidak dapat mengatakan ketika variabel dalam modul Anda berubah.

Gambar ulang saat data Anda berubah

Untuk memiliki situs Anda digambar lagi setelah data Anda sendiri berubah, panggil $.ui.invalidate('ui.render'). Panel ini menghitung penekanan. Callback tombol mengubah count, kemudian meminta redraw:
Setiap penekanan menaikkan angka di panel. Contoh hello-tabs membungkus panggilan yang sama dalam fungsi redraw-nya. Nilai yang Anda simpan dalam $.state tidak memerlukan panggilan, karena menulis nilai menggambar ulang situs yang membacanya.

Gambar ulang pada timer

Untuk menjaga jam, hitung mundur, atau nilai dari luar sesi saat ini, gambar ulang sesuai jadwal. Mulai timer dalam hook session.start modul. Jika modul sudah memiliki satu, seperti hello-tabs, tambahkan baris $.clock.every ke dalamnya:
Claude Code kini menjalankan hook ui.render Anda sekali setiap detik. Timer berhenti setelah modul dimuat ulang, dan instance baru dari modul tersebut memulai timer-nya sendiri.

Seberapa sering situs dapat digambar ulang

Claude Code membatasi frekuensi penggambaran ulang situs, jadi mod Anda dapat memanggil $.ui.invalidate sesering data berubah. Untuk seberapa sering setiap situs dapat digambar ulang, lihat tabel batas. Panggilan yang datang lebih cepat dari batas digabungkan menjadi satu redraw. Redraw itu menjalankan hook Anda sekali, dan hook membaca data Anda seperti adanya saat itu, jadi nilai terbaru ditampilkan dan nilai di antaranya tidak. Animasi tidak dapat berjalan lebih cepat dari batas.

Menyimpan state

Tempat sebuah mod menyimpan nilai menentukan berapa lama nilai itu bertahan: hingga modul dimuat ulang, hingga sesi berakhir, atau dari satu sesi ke sesi berikutnya. Pilihlah berdasarkan berapa lama nilai tersebut harus bertahan: $.store.get(key) di-resolve ke nilai tersebut atau undefined, dan $.store.set(key, value) menerima nilai JSON apa pun.

Menyimpan nilai di $.state

$.state menyimpan nilai selama satu sesi, dan menggambar ulang untuk Anda. Ini adalah state reaktif: hook ui.render yang membaca sebuah nilai akan berlangganan ke nilai tersebut, sehingga Claude Code menggambar ulang lokasi itu setiap kali Anda menulis nilainya, dan Anda tidak perlu memanggil $.ui.invalidate. Nilai di $.state juga bertahan setelah modul dimuat ulang, sedangkan variabel tidak. Untuk menyiapkannya, deklarasikan nilai-nilai Anda, arahkan manifest Anda ke deklarasi tersebut, lalu definisikan dan gunakan setiap nilai. Contoh-contoh berikut memindahkan count dari hello-tabs ke $.state.

Mendeklarasikan nilai

Deklarasikan nilai-nilai dalam file deklarasi tipe. Key terluar adalah nama plugin Anda, dan setiap entri di bawahnya adalah sebuah nilai beserta tipenya. Simpan ini sebagai hello-tabs/types/index.d.ts:
hello-tabs/types/index.d.ts

Mengarahkan manifest ke deklarasi

Agar claude plugin validate dapat memeriksa kode Anda terhadap file tersebut, tambahkan field types ke manifest dengan path-nya:
hello-tabs/.claude-plugin/plugin.json

Mendefinisikan, membaca, dan menulis nilai

Di modul Anda, definisikan setiap nilai dengan nilai default, baca saat menggambar, dan tulis dari sebuah callback. atom memberi nama sebuah nilai dan default-nya, read mengembalikannya, dan update menulisnya. Ketiga helper tersebut memanggil $.state.get dan $.state.set untuk Anda:
Karena hook ui.render membaca count, Claude Code menjalankan hook tersebut lagi setiap kali tombol menulisnya. Aturan berikut berlaku untuk kode tersebut:
  • Tulis plugin dan key sebagai string literal: claude plugin validate membacanya dari source Anda
  • Simpan hasil setiap panggilan atom dalam const: jika Anda mendeklarasikan count dengan let, validasi gagal dengan takes a source the scan can read
  • Deklarasikan setiap nilai dalam file deklarasi tipe: jika tidak, validasi gagal dengan hello-tabs.count is not declared
  • Tulis dari callback atau hook event lain: hook ui.render dapat membaca state tetapi tidak dapat menulisnya, jadi tulislah dari onPress, onSubmit, atau hook untuk event lain

Mengubah hello-tabs agar menggunakan $.state

Untuk memindahkan count di hello-tabs ke $.state, ubah setiap baris yang menggunakannya:
  • Di bagian atas modul: tambahkan baris import, dan ganti let count = 0 dengan baris atom
  • Di hook ui.render: tambahkan baris read sebelum tabButton, dan gambar 'Count: ' + n di dalam Text
  • Di tombol Add one: ganti onPress dengan yang ada di Menyimpan dari lebih dari satu sesi, yang menyimpan hitungan sekaligus menulisnya
  • Di hook session.start: ganti dua baris yang membaca saved dengan panggilan loadCount dari Memuat ulang nilai yang tersimpan setelah /clear
Pertahankan redraw untuk tombol-tombol tab, karena tab masih berupa variabel.

Memuat ulang nilai yang tersimpan setelah /clear

Jika mod Anda menyalin nilai tersimpan dari $.store ke $.state pada session.start, mod tersebut harus menyalinnya lagi setelah /clear, /resume, atau /branch. Perintah-perintah tersebut mengatur ulang setiap nilai $.state ke default-nya, dan session.start tidak dipicu lagi. classic.SessionStart memang dipicu setelah masing-masing perintah tersebut, dengan e.source bernilai clear, resume, atau fork, jadi salin nilai tersebut lagi dalam hook padanya. Jika tidak, gambar Anda menampilkan nilai default, dan callback yang menyimpan nilai $.state akan menulis nilai default di atas apa yang telah Anda simpan. Kode ini memuat count dari kedua hook. Kode ini dibangun di atas versi $.state dari hello-tabs, di mana count adalah sebuah atom dan update diimpor. Letakkan loadCount di atas register, dan tambahkan panggilan loadCount ke hook session.start yang sudah Anda miliki. classic.SessionStart juga dipicu saat startup dan setelah compaction, yang tidak mengatur ulang $.state, sehingga filter pada source membatasi hook tersebut pada tiga pengaturan ulang itu:
Dengan kedua hook terpasang, panel menampilkan hitungan yang tersimpan setelah /clear, bukan 0, dan penekanan Add one berikutnya menambah hitungan yang tersimpan. loadCount menulis nilai yang tersimpan di atas nilai di $.state, dan session.start dipicu lagi setiap kali modul dimuat ulang. Agar store tidak tertinggal, simpan pada setiap perubahan, seperti yang dilakukan tombol Add one. Untuk memeriksa pemuatan ulang tanpa sesi, uji gambar setelah /clear.

Menyimpan dari lebih dari satu sesi

Setiap sesi di mesin Anda yang menjalankan mod Anda berbagi satu $.store. get yang diikuti set tidak bersifat atomik. Ketika dua sesi masing-masing membaca sebuah nilai, mengubahnya, dan menulisnya kembali, keduanya berlomba, dan penulisan kedua menggantikan yang pertama. Untuk memperkecil kemungkinan tersebut:
  • Berikan setiap item key-nya sendiri: set hanya mengubah key-nya sendiri, sehingga sesi-sesi yang menulis key berbeda tidak saling menimpa
  • Baca lagi tepat sebelum Anda menulis: untuk nilai yang diubah oleh beberapa sesi, lakukan get pada key di dalam callback dan bangun nilai baru dari situ, bukan dari salinan yang Anda muat pada session.start. Penulisan dari sesi lain tetap hilang jika terjadi di antara get dan set Anda.
Tombol ini menambahkan satu ke apa pun yang saat ini disimpan oleh store, lalu memperbarui gambar:
Jika sesi kedua telah menekan tombolnya sendiri tiga kali sejak sesi ini dimulai, penekanan ini menampilkan dan menyimpan hitungan yang mencakup ketiga penekanan tersebut.

Langkah berikutnya