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:
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:
1
Buat plugin
Mod adalah plugin dengan manifest, Beri nama titik masuk Anda di
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
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:Setiap hook juga melakukan sesuatu yang tidak jelas dari 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
tab dan count, menyimpan status panel.Simpan ini sebagai hello-tabs/hooks/register.js:hello-tabs/hooks/register.js
session.startjuga membaca hitungan yang disimpan dari$.store, penyimpanan kunci-nilai yang bertahan antar sesi.command.runhanya memberi tahu Claude Code bahwa panel ada. Membuka panel tidak menggambar apa pun dengan sendirinya: Claude Code kemudian menaikkanui.renderuntuk menanyakan apa yang ada di dalamnya.ui.rendermengembalikan pohon elemen,Boxyang menyimpan kotak lain, teks, dan tombol, dan membangunnya lagi daritabdancountsetiap kali berjalan.
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 hookui.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
- Pita di atas prompt
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.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 hookui.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.
- Mengubah detail
- Mengganti gambar
- Membiarkannya
Untuk mempertahankan gambar Claude Code dan mengubah satu bagiannya, berikan kepada Spinner mempertahankan animasi dan katanya, dan teks Anda mengikuti kata tersebut:
next salinan event dengan props yang diubah. Hook ini mengubah teks setelah kata spinner: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:
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.
$.ui.close dengan id yang Anda gunakan saat membukanya:
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:
immediate: true saat Anda mendaftarkan perintah. Tanpanya, perintah yang diketik selama giliran berlangsung akan menunggu hingga giliran berakhir.
Menahan toast di balik dialog
BerikanholdToasts: 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.
$.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 hookui.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.placementbernilai'dock', dane.viewport.isFullscreenbernilaitrue. Pada panel chat yang lebih sempit, panel-panel digambar di atas kotak prompt,placementbernilai'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: truedari 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 kenexttidak mengubah kartu tersebut. - Saran prompt:
$.prompt.suggestdi-resolve denganisShown: falsedan 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./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:
/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,isPlacedbernilaifalsedanreasonmenjelaskan alasannya, sepertino attached surface draws placed rows yet. Salah satu alasannya adalah batas jumlah baris yang dapat dimiliki sebuah mod pada satu waktu. - Panggilan kedua dengan
idyang sama: selama baris pertama masih ada di transkrip, panggilan tersebut tidak menambahkan baris dan di-resolve denganrequestIddari 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.
--resumetidak mengembalikan baris tersebut. Untuk menampilkan baris lagi, panggil$.ui.placelagi.
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.$.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./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:sceneadalah nama yang Anda pilih untuk latar belakang yang digambar oleh hook Anda. Untuk field lainnya danoverrideColorScheme, lihat tipe untuk build Anda. - Apakah latar belakang digambar:
$.theme.setdi-resolve denganisDrawn: trueketika aplikasi Desktop atau seluler yang terhubung ke sesi menyatakan bahwa aplikasi tersebut menggambar latar belakang. Jika tidak,isDrawnbernilaifalsedanreasonmenjelaskan alasannya. - Satu tema untuk setiap sesi: mod yang memanggil
$.theme.setmenggantikan 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 Untuk menggunakan warna Anda sendiri, ganti nilai hex dengan warna hex enam digit lainnya.
~/.claude/skills/paper/hooks/register.js. Saat sesi dimulai, kode ini memanggil $.theme.set dengan warna untuk mode terang dan mode gelap: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
makeColorsmilik mod. Jika panggilan tersebut memunculkan error, atau daftarproblems-nya memiliki entri yang diawali denganDesktop won't paint this theme, minta Claude memperbaiki tema tersebut. Jika Anda menginstal mod tersebut, kirimkan temuan Claude kepada pembuatnya. - Panggilan
$.themelain: ketika mod mana pun dalam sesi memanggil$.theme.setatau$.theme.clear(), warna dan latar belakang dari panggilan sebelumnya menghilang. Dalam mod Anda sendiri, berikancolorsdanbackdropdalam panggilan$.theme.setyang 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
- Claude yang menulis mod tersebut: pindahkan direktorinya keluar dari folder mod sesi tempat Claude menulisnya.
- Anda meletakkan mod di bawah
~/.claude/skills/: pindahkan direktorinya, seperti~/.claude/skills/paper/, ke tempat di luar~/.claude/skills/. - Anda menginstal mod tersebut: di aplikasi Desktop, nonaktifkan atau hapus instalan plugin-nya dari Manage plugins. Jika Anda tidak melihat Manage plugins dan Anda memiliki CLI, Anda dapat menonaktifkan atau menghapus instalan plugin marketplace dari shell Anda.
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 hookui.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
- Box
- Input
Text menggambar string, dengan gaya opsional seperti bold dan color:
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:
Link di aplikasi Desktop dan VS Code
Di aplikasi Desktop dan ekstensi VS Code, Link digambar sebagai teks biasa kecuali href-nya memenuhi persyaratan berikut:
- Skema dan host: URL
https:, atau URLhttp://localhostsepertihttp://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:443pada URLhttps:.
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 satuRaster 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:
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: mengambilonPress(e), di manae.surfaceadalah aplikasi tempat penekanan berasalInput: mengambilonSubmit(value)danonInput(value)Select: mengambilonSelect(value)dengan pilihan dalamoptions, 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, atauui.selectdengan key kontrol dalame.elementsebelum menjalankan callback kontrol tersebut. Hook mod lain juga dapat berjalan untuk event tersebut. Hook itu melihat apa yang pengguna ketik keInputAnda dan dapat mengubah teks itu atau mencegah callback Anda berjalan. API mods tidak memberi mod tersebut metode untuk menekan tombol Anda.
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 pengikatanaction, 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: truedari perintah atau penekanan - Pengguna menekan Ctrl+X kemudian Tab
- Pengguna mengkliknya, yang di terminal memerlukan rendering layar penuh
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 menekanButtondengan satu kunci, berikanhotkeydari satu digit atau satu huruf kecil, seperti dalamhotkey: 'a'autoFocus: untuk memilih kontrol mana yang memiliki fokus saat panel terbuka, tambahkanautoFocus: trueke dalamnya. Di ekstensi VS Code,autoFocustidak melakukan apa-apa: kontrol digambar seolah-olah Anda tidak menyertakannya, dan Anda tidak perlu mengubah apa pun. Prop ini hanya menerimatrue, jadi hilangkan pada kontrol lainnya.
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.
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 tombolx 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:
InputmemanggilonSubmit(value)dengan teks bidang saat pengguna menekan Enter, danonInput(value)pada setiap perubahan - Gambar daftar: petakan data Anda ke satu baris masing-masing, dan berikan setiap tombol baris
key-nya sendiri
- Tambahkan catatan: ketik baris dan tekan Enter. Baris muncul sebagai baris baru, dan bidang kosong.
- Hapus catatan: tekan Tab sampai tombol
xcatatan memiliki fokus, kemudian tekan Enter.xadalah label tombol dan bukan pintasan keyboard, jadi mengetik huruf tidak menekan itu.
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 hookui.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 hookui.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:
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 hooksession.start modul. Jika modul sudah memiliki satu, seperti hello-tabs, tambahkan baris $.clock.every ke dalamnya:
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 sebagaihello-tabs/types/index.d.ts:
hello-tabs/types/index.d.ts
Mengarahkan manifest ke deklarasi
Agarclaude 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:
ui.render membaca count, Claude Code menjalankan hook tersebut lagi setiap kali tombol menulisnya.
Aturan berikut berlaku untuk kode tersebut:
- Tulis
plugindankeysebagai string literal:claude plugin validatemembacanya dari source Anda - Simpan hasil setiap panggilan
atomdalamconst: jika Anda mendeklarasikancountdenganlet, validasi gagal dengantakes 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.renderdapat membaca state tetapi tidak dapat menulisnya, jadi tulislah darionPress,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 gantilet count = 0dengan barisatom - Di hook
ui.render: tambahkan barisreadsebelumtabButton, dan gambar'Count: ' + ndi dalamText - Di tombol Add one: ganti
onPressdengan yang ada di Menyimpan dari lebih dari satu sesi, yang menyimpan hitungan sekaligus menulisnya - Di hook
session.start: ganti dua baris yang membacasaveddengan panggilanloadCountdari Memuat ulang nilai yang tersimpan setelah/clear
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:
/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:
sethanya 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
getpada key di dalam callback dan bangun nilai baru dari situ, bukan dari salinan yang Anda muat padasession.start. Penulisan dari sesi lain tetap hilang jika terjadi di antaragetdansetAnda.
Langkah berikutnya
- Bereaksi terhadap event: umpan gambar Anda dari panggilan alat dan giliran
- Gunakan API mods: umpan gambar Anda dari timer dan panggilan model
- Uji gambar: tekan tombol Anda dari tes, di lebih dari satu permukaan
- Render sites dan elemen: prop setiap situs dan prop setiap elemen