ui.render chaque fois qu’il s’apprête à dessiner un site de rendu, et votre hook pour cet événement retourne ce qu’il faut dessiner là.
Cette carte montre où un mod peut dessiner dans une session de terminal :
Pour rechercher une prop ou une limite, consultez la référence.
Construire un volet avec des onglets
Dans cette section, vous construisez un mod qui ajoute une commande/hello-tabs, et la commande ouvre un volet. Un volet est une barre latérale à côté de la transcription dans un terminal plein écran large, ou une région encadrée au-dessus de l’invite sinon. Ce volet affiche deux onglets, et le deuxième onglet a un bouton qui ajoute un au compteur. Le compte est toujours là après que vous redémarriez Claude Code.
Le mod fini ressemble à ceci. L’enregistrement ouvre le volet, bascule vers le deuxième onglet, appuie sur le bouton quelques fois, et revient au premier onglet :
1
Créer le plugin
Un mod est un plugin avec un manifeste, un Nommez votre point d’entrée dans
hooks.json qui pointe vers votre code, et le fichier de code. Créer un mod explique chacun. Créez un répertoire nommé hello-tabs avec des répertoires .claude-plugin et hooks à l’intérieur, puis enregistrez les deux premiers fichiers.Enregistrez le manifeste sous hello-tabs/.claude-plugin/plugin.json :hello-tabs/.claude-plugin/plugin.json
hello-tabs/hooks/hooks.json :hello-tabs/hooks/hooks.json
2
Écrire le code
Cette liste indique ce que fait chaque hook, dans l’ordre où ils apparaissent dans le code :Chaque hook fait aussi quelque chose que le code ne rend pas évident :
- Ajoute la commande
/hello-tabset charge le compte qu’une session précédente a sauvegardé - Ouvre le volet quand vous exécutez cette commande
- Dessine le contenu du volet : la ligne d’onglets et le corps de l’onglet ouvert
tab et count, conservent l’état du volet.Enregistrez ceci sous hello-tabs/hooks/register.js :hello-tabs/hooks/register.js
session.startlit aussi le compte sauvegardé depuis$.store, un magasin clé-valeur qui persiste entre les sessions.command.rundit seulement à Claude Code que le volet existe. Ouvrir un volet ne dessine rien par lui-même : Claude Code déclenche ensuiteui.renderpour demander ce qu’il faut y mettre.ui.renderretourne l’arbre d’éléments, uneBoxqui contient d’autres boîtes, du texte et des boutons, et le construit à nouveau à partir detabetcountchaque fois qu’il s’exécute.
onPress, qui change une variable et appelle redraw. Claude Code exécute ensuite le hook ui.render à nouveau, et le hook construit un nouvel arbre à partir des nouvelles valeurs. Chaque dessin interactif utilise ce cycle de rendu : un callback change l’état, et le hook dessine à nouveau à partir du nouvel état.3
Ouvrir le volet
Dans votre shell, démarrez Claude Code avec
claude --plugin-dir ./hello-tabs. À l’invite Claude Code, exécutez /hello-tabs. Un volet s’ouvre avec 1: One et 2: Two en haut. Appuyez sur 2, puis appuyez sur a, la touche de raccourci pour Add one, quelques fois. Le compte augmente.4
Vérifier que le compte a été sauvegardé
Appuyez sur Esc pour fermer le volet, puis quittez la session. Dans votre shell, démarrez Claude Code à nouveau avec la même commande
claude --plugin-dir ./hello-tabs, et à l’invite Claude Code exécutez /hello-tabs. Le compte est où vous l’avez laissé.Pour effacer le compte, faites appeler au mod $.store.delete('count'). Conserver l’état couvre combien de temps chaque type de valeur dure.Choisir où dessiner
Pour choisir le point de rendu dans lequel un hookui.render dessine, passez un filtre, appelé matcher, comme second argument de on. { component: 'Pane' } n’exécute le hook que pour les panneaux. Dans le hook, e.component nomme le point de rendu, e.surface indique quelle application dessine, et e.props contient les données propres au point de rendu. Pour un panneau, e.requestId est l’id avec lequel vous l’avez ouvert.
Le panneau et la bande restent vides tant qu’un mod ne les remplit pas. Sélectionnez un onglet pour découvrir ce qu’est chacun d’eux et comment y dessiner :
- Panneau
- Bande au-dessus du prompt
Un panneau est une barre latérale à côté de la transcription dans un terminal large en plein écran, ou sinon une zone encadrée au-dessus du prompt. Lorsque plusieurs panneaux sont ouverts, chacun dispose d’un onglet qui affiche son titre.Un panneau apparaît lorsque votre mod appelle
$.ui.open avec un id de votre choix, comme dans $.ui.open({ id: 'hello-tabs' }). Ouvrir un panneau au bon moment présente les autres champs et explique quand un panneau attend un terminal plus large.Pour dessiner dans votre panneau, filtrez sur { component: 'Pane' } et vérifiez que e.requestId correspond à votre id.Modifier ce que Claude Code dessine déjà
Claude Code dessine lui-même la plupart de son interface : les messages, les lignes d’appels d’outils, le spinner, et plus encore. Chacune de ces parties est aussi un point de rendu, qu’un mod peut donc restyler ou remplacer. Pour en modifier une, filtrez votre hookui.render sur son nom tiré de ce tableau :
Pane, AskUserQuestion, Spinner, UserMessage, AssistantMessage et les points de rendu des appels d’outils fonctionnent dans le terminal, l’application Desktop et l’extension VS Code. Le tableau des points de rendu indique où chacun des autres est déclenché.
Sur un point de rendu que Claude Code dessine déjà, votre hook peut modifier un détail, remplacer le dessin ou le laisser tel quel. Sélectionnez un onglet pour voir chaque cas appliqué au spinner. Les exemples lisent une variable calls qu’un autre hook incrémente, comme dans le mod du tutoriel.
- Modifier un détail
- Remplacer le dessin
- Le laisser tel quel
Pour conserver le dessin de Claude Code et en modifier une partie, passez à Le spinner conserve son animation et son mot, et votre texte suit le mot :
next une copie de l’événement avec des props modifiées. Ce hook modifie le texte qui suit le mot du spinner :next(e) renvoie une référence au dessin de Claude Code, { type: 'engine', ref }, sauf si un mod exécuté après le vôtre a renvoyé son propre arbre. Pour modifier le contenu de ce dessin, passez à next une copie de l’événement avec des props différentes, comme le fait l’onglet Modifier un détail. Vous pouvez renvoyer la référence telle quelle, ou la placer dans une Box à côté de vos propres éléments :
under the spinner apparaît en dessous.
La demande de permission n’est pas un point de rendu, un mod ne peut donc pas modifier ce qu’elle affiche. La boîte de dialogue de question, AskUserQuestion, en est un, un mod peut donc modifier cette boîte de dialogue lorsque Claude pose une question. Un arbre pour cette boîte de dialogue doit contenir la référence exactement une fois, avec vos éléments au-dessus. Sinon, Claude Code dessine sa propre boîte de dialogue.
Ouvrir un panneau au bon moment
Un panneau n’apparaît que lorsque votre mod l’ouvre. La manière et le moment où vous l’ouvrez déterminent s’il prend le focus clavier, l’espace qu’il demande, et s’il s’affiche ou non dans un terminal étroit. Pour ouvrir un panneau, appelez$.ui.open avec un id de votre choix. L’id est le nom du panneau : votre hook ui.render le vérifie, et vous le repassez pour fermer le panneau. Si un autre mod a un panneau ouvert avec cet id, l’appel est rejeté.
$.ui.close avec l’id avec lequel vous l’avez ouvert :
id, $.ui.open accepte ces champs facultatifs :
L’extension VS Code ignore
rows et columns et dimensionne elle-même le panneau.
focus, closeOnEscape et holdToasts sont facultatifs et n’acceptent que true. Pour ne pas en utiliser un, omettez-le. Passer false lève une erreur telle que ui.open: focus is true or left out. Pour en définir un de manière conditionnelle, n’ajoutez le champ que lorsque la condition est remplie. Cet appel ne demande le focus clavier que lorsque items n’est pas vide :
immediate: true lorsque vous enregistrez la commande. Sans cela, une commande saisie pendant un tour attend la fin du tour.
Retenir les toasts derrière une boîte de dialogue
PassezholdToasts: true à $.ui.open lorsque le panneau est une boîte de dialogue à laquelle l’utilisateur répond avant de la quitter, afin que les toasts n’apparaissent pas pendant qu’il décide. Dans le terminal, la retenue dure tant que ce panneau est celui qui est affiché, et un toast déclenché pendant ce temps attend la fin de la retenue.
Claude Code retient les toasts des autres mods et ses propres notifications éphémères, ainsi que ceux que votre mod déclenche avec $.ui.toast. N’utilisez pas ce champ pour un panneau qui reste ouvert, afin que l’utilisateur continue de les voir.
Quand un panneau attend un terminal plus large
Un panneau que votre mod ouvre sans qu’on le lui demande n’apparaît pas dans un terminal étroit, afin qu’il ne puisse pas accaparer un petit écran. Son affichage dépend de ce qui l’a ouvert :- Ouvert par une action de l’utilisateur, comme une commande qu’il a exécutée ou un bouton sur lequel il a appuyé, le panneau apparaît quelle que soit la largeur
- Ouvert par votre mod de sa propre initiative, par exemple depuis un minuteur ou un hook
turn.start, le panneau n’apparaît que dans un terminal d’au moins 144 colonnes de large. Une fois que l’utilisateur a lui-même ouvert ce panneau, 110 colonnes suffisent.
$.ui.open se résout en { isPlaced: true }. Lorsque le panneau est en attente, isPlaced vaut false et reason est une chaîne qui en indique la raison. Un panneau en attente apparaît lorsque l’utilisateur l’ouvre ou élargit le terminal. Pour signaler qu’un élément est disponible sans ouvrir de panneau, appelez $.ui.toast('Your message'), qui affiche une notification toast.
Dessiner dans l’extension VS Code
Dans l’extension VS Code, ce qu’un mod dessine apparaît dans le panneau de chat à partir de la version 2.1.299 de l’extension. Une session qui ne récupère pas les feature flags, comme une session sur Amazon Bedrock, nécessite la version 2.1.304 ou ultérieure. Dans un hookui.render pour le panneau, e.surface vaut vscode. Pour vérifier quels points de rendu et éléments le panneau dessine, et quelles props il ignore, consultez les tableaux des points de rendu et des éléments.
Pour qu’un mod fonctionne dans le panneau aussi bien que dans le terminal, tenez compte de ces différences :
- Panneaux : dans un panneau de 800 pixels de large ou plus, les panneaux s’ancrent à côté de la conversation,
e.props.placementvaut'dock'ete.viewport.isFullscreenvauttrue. Dans un panneau plus étroit, les panneaux se dessinent au-dessus de la zone de prompt,placementvaut'inline', et un panneau affiche 12 lignes avant de défiler. - Toasts et barres de statut : ils se trouvent dans une seule pile juste au-dessus de la zone de prompt, avec les panneaux lorsque le panneau est étroit, avec une barre de statut par mod. La pile est masquée pendant l’affichage d’une demande de permission ou d’une boîte de dialogue.
- Libellés : le panneau encadre ce qu’un mod dessine ou réécrit et l’étiquette avec le nom du plugin, comme dans From the token-chart plugin ou Edited by the token-chart plugin.
- Clavier : les boutons n’ont pas de raccourcis clavier, l’utilisateur clique donc sur un bouton ou appuie sur Enter une fois que celui-ci a le focus.
- Focus clavier : le panneau n’accorde la demande
focus: trued’un panneau que lorsque le panneau a le focus, que Claude est inactif sans question en attente, et que la zone de prompt est vide. - La boîte de dialogue de question : sur
AskUserQuestion, le panneau conserve sa propre carte de question et dessine vos éléments au-dessus. Les props que vous passez ànextne modifient pas la carte. - Suggestions de prompt :
$.prompt.suggestse résout avecisShown: falseet n’affiche rien, car le panneau réserve le texte de suggestion estompé de la zone de prompt aux propres suggestions de Claude. - Limites de texte : le panneau coupe une barre de statut à 200 caractères ou deux lignes, et un toast à 500 caractères.
Placer une ligne dans la transcription
Une ligne est un élément que votre mod ajoute à la transcription dans le terminal, après le dernier message. Elle reste à cet endroit au fil de la conversation, et Claude ne la voit pas.$.ui.place nécessite Claude Code v2.1.314 ou ultérieur.
1
Placer la ligne
Appelez
$.ui.place avec un id. L’id est un nom que vous inventez pour la ligne, comme build-status. Il peut comporter de 1 à 64 lettres, chiffres, _ ou -, et chaque ligne que votre mod a dans la transcription a besoin du sien.2
Dessiner la ligne
Dessinez la ligne sur le point de rendu
Placed./build-status. Lorsque l’utilisateur exécute la commande, le mod ajoute une ligne qui affiche Build: passing. Le texte est fixe pour que l’exemple reste court ; un vrai mod dessinerait son propre résultat :
/build-status dans le prompt de Claude Code. Build: passing apparaît sous forme de ligne à la fin de la transcription.
L’appel n’affiche pas toujours de ligne, et une ligne peut disparaître plus tard ; gérez donc ces cas dans votre mod :
- Le résultat :
{ isPlaced: true, requestId }lorsque le terminal dessine la ligne. Sinon,isPlacedvautfalseetreasonen indique la raison, comme dansno attached surface draws placed rows yet. L’une des raisons possibles est la limite du nombre de lignes qu’un mod peut avoir en même temps. - Un second appel avec le même
id: tant que la première ligne est encore dans la transcription, l’appel n’ajoute aucune ligne et se résout avec lerequestIdde cette ligne. Pour modifier ce qu’affiche la ligne, redessinez la ligne. - Quand la ligne disparaît : lorsque la conversation se termine, lorsque l’utilisateur revient en arrière au-delà de la ligne, ou, en dehors du rendu plein écran, lorsque la conversation est compactée.
--resumene rétablit pas la ligne. Pour afficher à nouveau la ligne, appelez de nouveau$.ui.place.
Placer un arrière-plan derrière la conversation
$.theme.set et $.theme.clear remplacent $.ui.backdrop, que Claude Code v2.1.319 a supprimé. Remplacez $.ui.backdrop({ id: 'your-backdrop' }) par un appel à $.theme.set semblable à celui de l’exemple de cette section, et $.ui.backdrop(undefined) par $.theme.clear(), qui supprime l’arrière-plan de n’importe quel mod.$.theme.set avec un backdrop, puis dessinez l’arrière-plan sur le point de rendu Backdrop. Pour retirer l’arrière-plan, appelez $.theme.clear(). Le terminal ne dessine aucun arrière-plan. $.theme.set et $.theme.clear nécessitent Claude Code v2.1.319 ou ultérieur.
Cet exemple nécessite Claude Code v2.1.323 ou ultérieur ; vérifiez donc votre version au préalable. Le mod définit un arrière-plan au démarrage de la session, dessine l’arrière-plan et ajoute une commande /plain qui retire l’arrière-plan :
Avant la v2.1.323, écrivez
id à la place de scene dans l’appel à $.theme.set et dans e.props, et déplacez overrideColorScheme dans backdrop sous le nom colorScheme./plain dans le prompt de Claude Code. La transcription affiche the theme is cleared après le nom du mod, comme dans night-sky: the theme is cleared pour un mod nommé night-sky.
Vérifiez ce qu’accepte backdrop, ce que vous indique le résultat de l’appel, et ce que les autres mods peuvent modifier :
- Les champs de
backdrop:sceneest un nom que vous choisissez pour un arrière-plan que votre hook dessine. Pour les autres champs etoverrideColorScheme, consultez les types de votre build. - Si l’arrière-plan est dessiné :
$.theme.setse résout avecisDrawn: truelorsqu’une application Desktop ou mobile connectée à la session indique qu’elle dessine les arrière-plans. Sinon,isDrawnvautfalseetreasonen indique la raison. - Un seul thème par session : un mod qui appelle
$.theme.setremplace l’arrière-plan et les couleurs de la session, et un mod qui appelle$.theme.clear()les supprime, quel que soit le mod qui les a définis. N’appelez$.theme.clear()que lorsque l’utilisateur le demande.
Modifier les couleurs de l’application Desktop
Pour modifier les couleurs de l’onglet Code de l’application Desktop avec un mod, demandez-en un à Claude ou écrivez-le vous-même. Les deux méthodes nécessitent Claude Code v2.1.324 ou ultérieur dans l’onglet Code ; vérifiez donc la version à cet endroit au préalable. Claude Code dans le terminal conserve ses propres couleurs.Demander un mod de couleurs à Claude
1
Décrire les couleurs
Démarrez une session locale dans l’onglet Code et indiquez à Claude les couleurs que vous souhaitez. Par exemple, saisissez
make a mod that makes the app cream in light mode and dark brown in dark mode. Claude écrit les fichiers du mod.2
Approuver le mod
Répondez aux questions que Claude Code pose sur les fichiers du mod et le rechargement à chaud. Pour connaître l’effet de chaque réponse, consultez Demander un mod à Claude.
3
Vérifier les couleurs
L’onglet Code change de couleur lorsque le mod se charge. Pour ajuster une couleur, indiquez à Claude ce qu’il faut modifier. Si rien ne change, consultez Corriger les couleurs de mod manquantes.
Écrire un mod de couleurs vous-même
makeColors est une fonction qui construit un thème à partir de quelques couleurs hexadécimales. Ces étapes créent un mod nommé paper qui l’utilise.
1
Faire copier makeColors par Claude
Démarrez une session locale dans l’onglet Code, et saisissez
copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/. Vérifiez que les deux fichiers se trouvent dans ce répertoire.2
Enregistrer le manifeste et hooks.json
À partir de Écrire un mod vous-même, enregistrez
.claude-plugin/plugin.json et hooks/hooks.json dans ~/.claude/skills/paper/, et remplacez first-mod par paper dans les deux fichiers. Un mod placé sous ~/.claude/skills/ se charge lorsque vous démarrez une session.3
Écrire le code
Enregistrez ce fichier sous Pour utiliser vos propres couleurs, remplacez les valeurs hexadécimales par d’autres couleurs hexadécimales à six chiffres.
~/.claude/skills/paper/hooks/register.js. Au démarrage d’une session, le code appelle $.theme.set avec les couleurs pour le mode clair et le mode sombre :4
Vérifier les couleurs
Démarrez une nouvelle session locale dans l’onglet Code. Avec les valeurs de l’exemple, l’arrière-plan est crème en mode clair et brun foncé en mode sombre. Si rien ne change, consultez Corriger les couleurs de mod manquantes.
Corriger les couleurs de mod manquantes dans l’application Desktop
Si vous utilisez un fournisseur tiers au lieu d’un compte Claude dans Claude Desktop v5.11492.5 ou antérieur, l’onglet Code conserve ses propres couleurs ; ignorez donc ces vérifications. Sinon, si les couleurs d’un mod n’apparaissent pas dans l’onglet Code, ou si elles disparaissent, recherchez ces causes :- Version obsolète : mettez à jour l’application Desktop, redémarrez-la, et démarrez une nouvelle session locale dans l’onglet Code. Si Claude a écrit le mod, redemandez-le-lui dans cette session.
- Mod non chargé : si Claude a écrit le mod, consultez à quel moment il se charge dans Demander un mod à Claude. Si vous l’avez écrit, comparez vos fichiers et leurs chemins avec Écrire un mod de couleurs vous-même.
- Thème refusé : demandez à Claude d’exécuter l’appel
makeColorsdu mod. Si l’appel lève une erreur, ou si sa listeproblemscontient une entrée commençant parDesktop won't paint this theme, faites corriger le thème par Claude. Si vous avez installé le mod, envoyez ce que Claude trouve à son auteur. - Un autre appel
$.theme: lorsqu’un mod de la session appelle$.theme.setou$.theme.clear(), les couleurs et l’arrière-plan d’un appel antérieur disparaissent. Dans votre propre mod, passezcolorsetbackdropdans le même appel à$.theme.set. N’utilisez qu’un seul mod à la fois qui définit un thème.
Supprimer les couleurs de mod de l’application Desktop
Pour retirer les couleurs d’un mod de l’onglet Code, désactivez d’abord le mod. Un mod encore activé peut redéfinir ses couleurs.1
Désactiver le mod
- Claude a écrit le mod : déplacez son répertoire hors du dossier des mods de la session dans laquelle Claude l’a écrit.
- Vous avez placé le mod sous
~/.claude/skills/: déplacez son répertoire, par exemple~/.claude/skills/paper/, vers un emplacement situé hors de~/.claude/skills/. - Vous avez installé le mod : dans l’application Desktop, désactivez ou désinstallez son plugin depuis Manage plugins. Si vous ne voyez pas Manage plugins et que vous disposez de la CLI, vous pouvez désactiver ou désinstaller un plugin de marketplace depuis votre shell.
2
Démarrer une nouvelle session
Démarrez une nouvelle session locale dans l’onglet Code.
3
Supprimer les couleurs qui persistent
Si les couleurs sont toujours présentes, ouvrez Settings depuis l’onglet Code, et recherchez-y
code appearance. Ouvrez le résultat, et sélectionnez Remove colors.Créer un arbre à partir d’éléments
Ce que renvoie un hookui.render est un arbre d’éléments : une description de ce qu’il faut dessiner, composée de boîtes, de texte et de contrôles imbriqués les uns dans les autres. Vous décrivez le dessin, et Claude Code l’affiche dans l’application que l’utilisateur a ouverte : le terminal, l’application Desktop ou l’extension VS Code.
Pour obtenir les éléments, appelez $.ui.resolve(e) dans votre hook, comme dans const { Box, Text, Button } = $.ui.resolve(e). Chaque élément est une fonction. Vous lui passez des props, et vous placez les éléments et les chaînes qui vont à l’intérieur dans children.
Sélectionnez un onglet pour voir chacun des éléments les plus courants et la façon dont le terminal le dessine :
- Text
- Box
- Input
Text dessine une chaîne, avec un style facultatif tel que bold et color :
Si votre module est un fichier
.tsx ou .jsx, vous pouvez écrire l’arbre en JSX. Déstructurez d’abord les éléments à partir de $.ui.resolve(e).
Si votre dessin ne s’affiche pas, vérifiez que son arbre ne contient pas une prop qu’un élément n’accepte pas ou un enfant là où aucun n’est permis. Un hook qui renvoie un tel arbre échoue, et une ligne hook skipped nomme votre mod et la règle que l’arbre a enfreinte. Pour un Text dans un panneau avec une prop nommée bogusProp, cette ligne indique :
Link dans l’application Desktop et VS Code
Dans l’application Desktop et l’extension VS Code, un Link s’affiche comme du texte brut, sauf si son href remplit ces conditions :
- Schéma et hôte : une URL
https:, ou une URLhttp://localhosttelle quehttp://localhost:3000 - Pas de
@: écrivez un@dans le chemin ou la requête sous la forme%40 - Orthographe : ce que renvoie
new URL(href).href, à l’exception d’un/manquant après l’hôte. Cela exclut un hôte en majuscules, un espace et:443sur une URLhttps:.
Lorsqu’un Client échoue
Dans le terminal, lorsque le fichier exécuté par un Client échoue, une ligne grisée telle que my-mod: Client client/spinner.js: boom prend la place du Client, et le reste de votre dessin reste affiché.
Si votre mod gère ui.fault, Claude Code redessine alors l’emplacement.
Dessiner une grille de cellules colorées
Pour une carte de chaleur, une sparkline ou un plateau de jeu dans le terminal, dessinez un seulRaster plutôt qu’un Box par cellule. Un Raster accepte une key, sa taille en columns et rows, et cells, une chaîne base64 qui regroupe toutes les cellules. Chaque cellule est composée de trois nombres : le point de code du caractère, sa couleur et sa couleur d’arrière-plan. Une couleur est une valeur RVB 24 bits en hexadécimal, par exemple 0xc62828 pour un rouge. La valeur 0x01000000, juste au-dessus de cette plage, désigne la couleur par défaut du terminal.
Les applications autres que le terminal n’ont pas de Raster : vérifiez donc e.surface et dessinez du texte à la place. Ce corps de panneau dessine une carte de chaleur de trois sur deux :
rows est la partie que vous modifieriez, et cellsOf le transforme en chaîne compactée. Le hook ne dessine que dans un panneau dont l’id est heat : ouvrez-en donc un avec $.ui.open({ id: 'heat' }) depuis une commande, comme l’exemple hello-tabs ouvre son panneau.
Chaque caractère doit occuper une seule cellule de largeur. Pour animer un Raster déjà affiché à l’écran, appelez $.ui.blit avec l’id du panneau comme requestId, la key du Raster, la même taille et de nouvelles cellules. Pour cet exemple, cela donne $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }). Cet appel redessine cet unique élément sans exécuter à nouveau votre hook ui.render.
Réagir aux appuis et à la saisie
Lorsque l’utilisateur appuie sur un bouton, saisit du texte dans un champ ou choisit un élément dans une liste dessinée par votre mod, Claude Code appelle le callback de ce contrôle, qui s’exécute dans votre module. Chaque contrôle accepte ses propres callbacks :Button: accepteonPress(e), oùe.surfaceest l’application d’où provient l’appuiInput: accepteonSubmit(value)etonInput(value)Select: accepteonSelect(value)avec ses choix dansoptions, une liste d’au moins un choix aux valeurs uniques, comme[{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]
Quels contrôles ont besoin d’une key
Donnez à chaque Input et Select une prop key, comme key: 'size'. Un Button peut se passer de key lorsqu’il possède une prop label ou un unique enfant de type chaîne. Sa clé est alors la valeur de label ou cette chaîne.
Les tests et les autres mods identifient un contrôle par sa clé :
- Tests : un test appuie sur un contrôle ou y saisit du texte via sa clé.
- Autres mods : Claude Code déclenche
ui.press,ui.inputouui.selectavec la clé du contrôle danse.elementavant d’exécuter le callback du contrôle. Le hook d’un autre mod peut aussi s’exécuter pour cet événement. Ce hook voit ce que l’utilisateur a saisi dans votreInputet peut modifier ce texte ou empêcher votre callback de s’exécuter. L’API des mods ne donne à ce mod aucune méthode pour appuyer sur vos boutons.
needs a key ou is drawn twice, trouvez la cause à partir de ce message.
Focus clavier et raccourcis
Votre mod ne lit jamais le clavier lui-même. L’utilisateur appuie sur une touche, Claude Code détermine à quel contrôle elle est destinée, et le callback de ce contrôle s’exécute. Hormis un raccourci numérique sur le bandeau ou une liaisonaction, cela ne se produit que lorsque votre panneau ou votre bandeau a le focus clavier. Le reste du temps, les touches vont au prompt.
Dans l’extension VS Code, les boutons n’ont pas de raccourcis : l’utilisateur clique sur un bouton ou appuie sur Enter dessus, et saisit du texte dans les champs.
Comment un panneau obtient le focus clavier
Un panneau obtient le focus clavier lorsque :- Votre mod l’ouvre avec
focus: truedepuis une commande ou un appui - L’utilisateur appuie sur Ctrl+X puis Tab
- L’utilisateur clique dessus, ce qui, dans le terminal, nécessite le rendu plein écran
focus: true que lorsque le prompt est vide et qu’aucun autre élément n’a le focus clavier. Un panneau qui s’ouvre pendant que l’utilisateur tape ne capture pas ses frappes.
Ce que fait chaque touche
Ce tableau indique ce que fait une touche lorsque votre panneau ou votre bandeau a le focus clavier :
Un mod ne peut pas associer Tab ou les touches fléchées à autre chose ; un jeu se dirige donc avec
w, a, s et d.
Définir un raccourci et le focus initial
hotkey: pour permettre à l’utilisateur d’appuyer sur unButtonavec une seule touche, donnez-lui unhotkeyd’un chiffre ou d’une lettre minuscule, comme danshotkey: 'a'autoFocus: pour choisir le contrôle qui a le focus à l’ouverture du panneau, ajoutez-luiautoFocus: true. Dans l’extension VS Code,autoFocusn’a aucun effet : le contrôle est dessiné comme si vous l’aviez omis, et vous n’avez rien à modifier. La prop n’accepte quetrue; omettez-la donc sur les autres contrôles.
Dans le terminal, nommez la touche dans le libellé d’un bouton entre crochets, ou utilisez
plain: true, afin que l’utilisateur voie sur quoi appuyer. La référence des éléments présente les autres règles de Button : action, les raccourcis numériques sur le bandeau et deux boutons sur un même raccourci.
Lorsque l’utilisateur réduit le bandeau
Dans le terminal, lorsqu’un mod dessine dans le bandeau, l’utilisateur peut réduire le bandeau à une ligne pour le mettre de côté :- Cliquer sur
[-]: lorsque le bandeau est développé, Claude Code dessine cette marque à l’extrémité droite de sa première ligne. En rendu plein écran, l’utilisateur clique dessus pour réduire le bandeau. - Appuyer sur Ctrl+X puis Ctrl+A : cela fonctionne que ce soit le prompt, le bandeau ou un panneau qui ait le focus clavier. L’utilisateur peut y associer d’autres touches via l’action
abovePrompt:toggle.
action d’un bouton. Si le bandeau a le focus clavier lorsque l’utilisateur le réduit, le focus revient au prompt, et Ctrl+X puis Tab ignore le bandeau tant qu’il est réduit.
Le bandeau reste réduit jusqu’à ce que l’utilisateur le développe, même après /clear, et il est de nouveau développé au prochain démarrage de Claude Code. Votre mod ne peut pas le développer. Ne faites pas du bandeau le seul endroit où votre mod affiche quelque chose auquel l’utilisateur doit répondre. Pour afficher cela ailleurs uniquement lorsque le bandeau est réduit, lisez e.props.isCollapsed dans votre hook ui.render, qui continue de s’exécuter. isCollapsed nécessite Claude Code v2.1.321 ou une version ultérieure.
Recevoir une saisie et dessiner une ligne par élément
De nombreux panneaux se composent d’un champ de texte avec une liste en dessous. L’exemple de cette section est un panneau de notes : vous tapez une note et appuyez sur Enter pour l’ajouter, et chaque note possède un boutonx qui la supprime. Avec deux notes ajoutées, le terminal dessine le panneau ainsi :
✕ sur la bordure supérieure est la marque propre à Claude Code pour fermer le panneau.
L’exemple utilise ces techniques :
- Recevoir une saisie : un
InputappelleonSubmit(value)avec le texte du champ lorsque l’utilisateur appuie sur Enter, etonInput(value)à chaque modification - Dessiner une liste : associez chaque donnée à une ligne, et donnez au bouton de chaque ligne sa propre
key
- Ajouter une note : tapez une ligne et appuyez sur Enter. La ligne apparaît comme une nouvelle ligne de la liste, et le champ se vide.
- Supprimer une note : appuyez sur Tab jusqu’à ce que le bouton
xde la note ait le focus, puis appuyez sur Enter. Lexest le libellé du bouton et non un raccourci ; taper la lettre n’appuie donc pas dessus.
hello-tabs : le callback modifie notes, appelle redraw et enregistre la liste dans $.store. Si votre hook redessine le panneau pendant que l’utilisateur tape une note, le champ conserve son texte tant que le hook transmet la même value à chaque fois. Pour remplacer son texte par le vôtre, transmettez une value différente.
L’exemple enregistre les notes mais ne les charge pas. Pour les retrouver lors de la session suivante, lisez-les dans un hook session.start, comme hello-tabs lit count.
Ces props composent la ligne du champ, Note: Type a note and press Enter ⏎ add :
Soumettre un
Input ne démarre pas de tour, sauf si votre callback appelle $.prompt.submit.
Redessiner un site
Un dessin est un instantané : il affiche ce que votre hookui.render a retourné la dernière fois que le hook s’est exécuté. Pour afficher quelque chose de nouveau, le hook doit s’exécuter à nouveau. Claude Code l’exécute à nouveau pour certains changements, et votre mod demande le reste.
Quand Claude Code redessine sans être demandé
Claude Code exécute votre hookui.render à nouveau quand les props du site changent ou la largeur du terminal change. Quand un Client du site échoue et que votre mod gère ui.fault, Claude Code exécute le hook une fois de plus après le retour de vos hooks ui.fault, afin que votre hook ui.render puisse omettre le Client. Il n’exécute pas le hook sur une minuterie, et il ne peut pas dire quand une variable dans votre module change.
Redessiner quand vos données changent
Pour avoir vos sites dessinés à nouveau après que vos propres données changent, appelez$.ui.invalidate('ui.render'). Ce volet compte les appuis. Le callback du bouton change count, puis demande un redessin :
hello-tabs enveloppe le même appel dans sa fonction redraw.
Une valeur que vous gardez dans $.state n’a pas besoin de l’appel, car écrire la valeur redessine les sites qui la lisent.
Redessiner sur une minuterie
Pour garder une horloge, un compte à rebours, ou une valeur de l’extérieur de la session actuelle, redessinez selon un calendrier. Démarrez une minuterie dans le hooksession.start du module. Si le module en a déjà une, comme hello-tabs le fait, ajoutez la ligne $.clock.every à celle-ci :
ui.render une fois par seconde. La minuterie s’arrête après le rechargement du module, et la nouvelle instance du module démarre la sienne.
À quelle fréquence un site peut redessiner
Claude Code limite la fréquence à laquelle il redessine un site, donc votre mod peut appeler$.ui.invalidate aussi souvent que ses données changent. Pour connaître la fréquence à laquelle chaque site peut redessiner, consultez le tableau des limites.
Les appels qui viennent plus vite que la limite sont combinés en un redessin. Ce redessin exécute votre hook une fois, et le hook lit vos données telles qu’elles sont à ce moment, donc la valeur la plus récente s’affiche et les valeurs entre les deux ne s’affichent pas. Une animation ne peut pas s’exécuter plus vite que la limite.
Conserver l’état
L’endroit où un mod garde une valeur détermine combien de temps elle dure : jusqu’à ce que le module se recharge, jusqu’à ce que la session se termine, ou d’une session à l’autre. Choisissez selon la durée pendant laquelle la valeur doit durer :$.store.get(key) se résout en la valeur ou undefined, et $.store.set(key, value) prend n’importe quelle valeur JSON.
Garder une valeur dans $.state
$.state contient des valeurs pour la durée d’une session, et il redessine pour vous. C’est un état réactif : un hook ui.render qui lit une valeur s’y abonne, donc Claude Code redessine ce site chaque fois que vous écrivez la valeur, et vous n’appelez pas $.ui.invalidate. Une valeur dans $.state survit aussi à un rechargement du module, ce qu’une variable ne fait pas.
Pour le configurer, déclarez vos valeurs, pointez votre manifeste vers la déclaration, puis définissez et utilisez chaque valeur. Les exemples déplacent le count de hello-tabs dans $.state.
Déclarer les valeurs
Déclarez les valeurs dans un fichier de déclaration de types. La clé externe est le nom de votre plugin, et chaque entrée en dessous est une valeur et son type. Enregistrez ceci soushello-tabs/types/index.d.ts :
hello-tabs/types/index.d.ts
Pointer le manifeste vers la déclaration
Pour laisserclaude plugin validate vérifier votre code par rapport à ce fichier, ajoutez un champ types au manifeste avec son chemin :
hello-tabs/.claude-plugin/plugin.json
Définir, lire et écrire une valeur
Dans votre module, définissez chaque valeur avec une valeur par défaut, lisez-la pendant le dessin, et écrivez-la à partir d’un callback.atom nomme une valeur et sa valeur par défaut, read la retourne, et update l’écrit. Les trois aides appellent $.state.get et $.state.set pour vous :
ui.render a lu count, Claude Code exécute le hook à nouveau chaque fois que le bouton l’écrit.
Ces règles s’appliquent au code :
- Écrivez
pluginetkeycomme des chaînes littérales :claude plugin validateles lit de votre source - Conservez le résultat de chaque appel
atomdans uneconst: si vous déclarezcountaveclet, la validation échoue avectakes a source the scan can read - Déclarez chaque valeur dans le fichier de déclaration de types : sinon la validation échoue avec
hello-tabs.count is not declared - Écrivez à partir d’un callback ou du hook d’un autre événement : un hook
ui.renderpeut lire l’état et ne peut pas l’écrire, donc écrivez à partir deonPress,onSubmit, ou un hook pour un autre événement
Modifier hello-tabs pour utiliser $.state
Pour déplacer count dans hello-tabs dans $.state, modifiez chaque ligne qui l’utilise :
- En haut du module : ajoutez la ligne
import, et remplacezlet count = 0par la ligneatom - Dans le hook
ui.render: ajoutez la lignereadavanttabButton, et dessinez'Count: ' + ndans leText - Dans le bouton Add one : remplacez
onPresspar celui dans Enregistrer à partir de plus d’une session, qui enregistre le compte ainsi que l’écrit - Dans le hook
session.start: remplacez les deux lignes qui lisentsavedpar l’appelloadCountde Charger une valeur sauvegardée à nouveau après/clear
redraw pour les boutons d’onglets, car tab est toujours une variable.
Charger une valeur sauvegardée à nouveau après /clear
Si votre mod copie une valeur sauvegardée de $.store dans $.state à session.start, il doit la copier à nouveau après /clear, /resume, ou /branch. Ces commandes remettent chaque valeur $.state à sa valeur par défaut, et session.start ne se déclenche pas à nouveau. classic.SessionStart se déclenche en revanche après chacune d’elles, avec e.source défini sur clear, resume, ou fork, donc copiez la valeur à nouveau dans un hook dessus. Sinon votre dessin affiche la valeur par défaut, et un callback qui enregistre la valeur $.state écrit la valeur par défaut sur ce que vous avez stocké.
Ce code charge count à partir des deux hooks. Il s’appuie sur la version $.state de hello-tabs, où count est un atome et update est importé. Mettez loadCount au-dessus de register, et ajoutez l’appel loadCount au hook session.start que vous avez déjà. classic.SessionStart se déclenche aussi au démarrage et après compaction, ce qui ne réinitialise pas $.state, donc le filtre sur source garde le hook aux trois réinitialisations :
/clear et non 0, et le prochain appui sur Add one ajoute au compte sauvegardé.
loadCount écrit la valeur stockée sur celle dans $.state, et session.start se déclenche à nouveau chaque fois que le module se recharge. Pour éviter que le magasin ne prenne du retard, enregistrez à chaque changement, comme le fait le bouton Add one.
Pour vérifier le rechargement sans une session, testez le dessin après /clear.
Enregistrer à partir de plus d’une session
Chaque session sur votre machine qui exécute votre mod partage un$.store. Un get suivi d’un set n’est pas atomique. Quand deux sessions lisent chacune une valeur, la modifient et l’écrivent, elles font la course, et la deuxième écriture remplace la première.
Pour rendre cela moins probable :
- Donnez à chaque élément sa propre clé : un
setchange seulement sa propre clé, donc les sessions qui écrivent des clés différentes ne s’écrasent pas mutuellement - Lisez à nouveau juste avant d’écrire : pour une valeur que plusieurs sessions changent,
getla clé dans le callback et construisez la nouvelle valeur à partir de cela, pas à partir d’une copie que vous avez chargée àsession.start. L’écriture d’une autre session est toujours perdue si elle atterrit entre votregetet votreset.
Prochaines étapes
- Réagir aux événements : alimentez votre dessin à partir d’appels d’outils et de tours
- Utiliser l’API des mods : alimentez votre dessin à partir de minuteries et d’appels de modèle
- Tester un dessin : appuyez sur vos boutons à partir d’un test, sur plus d’une surface
- Sites de rendu et éléments : les props de chaque site et les props de chaque élément