Galleria dell'interfaccia per le mod

Una mod disegna la sua interfaccia a partire da elementi: testo, riquadri, pulsanti, campi e alcuni che formattano il contenuto per te. Gli esempi qui mostrano il codice che disegna un elemento e la maggior parte include uno screenshot del risultato in un pannello del terminale, così puoi scegliere un elemento in base al suo aspetto. Per capire come funziona il disegno, inizia da Disegnare nell’interfaccia. Per le prop principali e per sapere quali app disegnano ciascun elemento, consulta il riferimento degli elementi. Le dichiarazioni di tipo elencano tutte le prop.

Provare un esempio

Gli esempi in questa pagina sono frammenti, non mod complete. Ciascuno è il codice di un elemento e di tutto ciò che vi è annidato. Per vedere un esempio nel tuo terminale, crea la piccola mod descritta in questi passaggi e incollaci l’esempio. La mod aggiunge un comando /gallery che apre un pannello e vi disegna l’esempio. Un pannello è una barra laterale accanto alla trascrizione in un terminale a schermo intero sufficientemente largo, altrimenti è un’area incorniciata sopra il prompt.

Creare la mod

Crea una directory chiamata gallery con al suo interno le directory .claude-plugin e hooks. Creare una mod spiega i file.Salva il manifest come gallery/.claude-plugin/plugin.json:

gallery/.claude-plugin/plugin.json

{
  "name": "gallery",
  "version": "0.1.0",
  "description": "Opens a pane that draws one sample",
  "author": { "name": "Your Name" }
}

Indica il tuo entry point in gallery/hooks/hooks.json:

gallery/hooks/hooks.json

{
  "modules": ["./register.js"]
}

Salva il codice come gallery/hooks/register.js. Aggiunge un comando /gallery che apre un pannello e disegna Plain text in quel pannello:

gallery/hooks/register.js

// Stands in for your own callback in the samples that take one
const noop = () => {}
// The Select sample keeps its choice here
let picked = 'md'

// The Raster sample packs its cells with this function
const DEFAULT_COLOR = 0x01000000
function cellsOf(rows) {
  const numbers = rows.flat().flatMap(([char, color]) => [char.codePointAt(0), color, DEFAULT_COLOR])
  return new Uint8Array(Uint32Array.from(numbers).buffer).toBase64()
}

export function register(on) {
  on('session.start', async ($, e, next) => {
    await $.command.register({ name: 'gallery', description: 'Open the sample pane' })
    return next(e)
  })

  on('command.run', { command: 'gallery' }, async ($) => {
    await $.ui.open({ id: 'gallery', focus: true, closeOnEscape: true })
    return {}
  })

  on('ui.render', { component: 'Pane' }, async ($, e, next) => {
    if (e.requestId !== 'gallery') return next(e)
    const { Box, Text, Button, Input, Select, Link, Markdown, Code, Raster, Svg } = $.ui.resolve(e)
    // Replace the element after return with a sample
    return Text({ children: ['Plain text'] })
  })
}

Eseguire la mod

Nella tua shell, avvia Claude Code dalla directory che contiene gallery:

claude --plugin-dir ./gallery

Al prompt di Claude Code, esegui /gallery. Si apre un pannello con Plain text al suo interno.

Sostituire con un esempio

Copia un esempio da questa pagina. In register.js, incollalo al posto di Text({ children: ['Plain text'] }), in modo che segua return, e salva il file. Claude Code ricarica il modulo ogni volta che salvi, quindi esegui di nuovo /gallery per vedere il nuovo esempio.

Scegliere un elemento

Gli esempi sono raggruppati in base a ciò che vuoi mostrare sullo schermo:

Mostrare testo: Text, Markdown e Link
Mostrare codice e modifiche: Code
Disporre gli elementi: Box
Ricevere input: Button, Input e Select
Disegnare immagini: Raster, Svg, Image e Client

Mostrare testo

Tre elementi mostrano parole sullo schermo: Text per uno stile personalizzato, Markdown per contenuti già formattati e Link per un URL.

`Text`

Text disegna una stringa con gli stili che gli assegni. Questo esempio mostra una riga per ogni stile:

Box({
  flexDirection: 'column',
  children: [
    Text({ children: ['Plain text'] }),
    Text({ bold: true, children: ['bold'] }),
    Text({ italic: true, children: ['italic'] }),
    Text({ underline: true, children: ['underline'] }),
    Text({ strikethrough: true, children: ['strikethrough'] }),
    Text({ dimColor: true, children: ['dimColor'] }),
    Text({ inverse: true, children: ['inverse'] }),
    Text({ color: 'red', children: ["color: 'red'"] }),
    Text({ backgroundColor: 'blue', children: ["backgroundColor: 'blue'"] }),
  ],
})

Un pannello con nove righe di testo, ciascuna con il nome del proprio stile: normale, grassetto, corsivo, sottolineato, barrato, dimColor in grigio, inverse, color rosso e backgroundColor blu.

dimColor disegna il testo in grigio. backgroundColor riempie solo la larghezza del testo.

`Markdown`

Markdown formatta il testo nello stesso modo in cui sono formattate le risposte di Claude. Passa il contenuto in text, non in children:

Markdown({
  text: '## Release notes\n\nThis build has **two** fixes and one `flag`:\n\n- Faster start\n- Fewer prompts\n\n> Quoted text',
})

Un pannello con un'intestazione in grassetto, Release notes, seguita da una frase con una parola in grassetto e una parola di codice colorata, un elenco di due voci e una citazione in corsivo con una barra sulla sinistra.

Un’intestazione viene disegnata in grassetto senza i segni #. Il codice inline viene disegnato a colori senza i backtick. Una citazione viene disegnata in corsivo con una barra sulla sinistra.

`Link`

Link disegna un’etichetta seguita dal suo URL:

Link({ href: 'https://code.claude.com/docs', label: 'Claude Code docs' })

Un pannello con una riga: l'etichetta Claude Code docs, seguita dall'URL in grigio.

Il terminale disegna l’URL come testo dopo l’etichetta. Che un clic lo apra o meno dipende dal terminale dell’utente.

Mostrare codice e modifiche

Code disegna il codice sorgente con i colori di sintassi di Claude Code, oppure un diff.

`Code`

Indica il language, oppure passa un path da cui Claude Code possa dedurlo. Con startLine, le righe vengono numerate a partire da quel numero:

Code({
  language: 'javascript',
  startLine: 1,
  source: "const name = 'mods'\nconsole.log('hello ' + name)",
})

Un pannello con due righe numerate di JavaScript con i colori di sintassi.

I colori provengono dal tema dell’utente.

`Code` come diff

Con format: 'diff', source è costituito da uno o più hunk di unified diff:

Code({
  format: 'diff',
  source: '@@ -1,3 +1,3 @@\n # Mods\n-A mod is a plugin.\n+A mod is a plugin that runs code.\n Read on.',
})

Un pannello con un diff di quattro righe. La riga rimossa è ombreggiata in rosso e quella aggiunta in verde, ciascuna con il proprio numero di riga. Nella riga aggiunta, le parole that runs code hanno un'ombreggiatura più intensa.

Claude Code disegna i numeri di riga al posto della riga @@. Quando una riga rimossa e una riga aggiunta sono simili, le parole modificate ricevono un’ombreggiatura più intensa.

Disporre gli elementi

`Box`

Box dispone il suo contenuto in una riga o in una colonna e può disegnare un bordo. Questo esempio mette una riga di parole sopra un riquadro con bordo:

Box({
  flexDirection: 'column',
  gap: 1,
  children: [
    Box({
      flexDirection: 'row',
      columnGap: 4,
      children: [Text({ children: ['a row'] }), Text({ children: ['of three'] }), Text({ children: ['items'] })],
    }),
    Box({
      borderStyle: 'round',
      paddingX: 1,
      children: [Text({ children: ["borderStyle: 'round'"] })],
    }),
  ],
})

Un pannello con tre parole in una riga, distanziate di quattro colonne, poi una riga vuota, poi un bordo arrotondato attorno a una riga di testo. Il bordo occupa l'intera larghezza del pannello.

Il bordo si estende fino alla larghezza del pannello.

Ricevere input

Button, Input e Select sono controlli: l’utente si sposta tra di essi con Tab e usa quello che ha il focus. Focus della tastiera e tasti di scelta rapida spiega quali tasti li raggiungono. Aprire un pannello con focus: true assegna al pannello il focus della tastiera. Le lettere digitate raggiungono un Input solo quando ha il focus, quindi aggiungi autoFocus: true a un campo che deve ricevere la digitazione non appena si apre il pannello.

`Button`

Un pulsante esegue onPress. Questo esempio mostra la forma predefinita, un pulsante plain con un tasto di scelta rapida e uno attenuato:

Box({
  flexDirection: 'column',
  children: [
    Button({ key: 'save', label: 'Save', onPress: noop }),
    Button({ key: 'next', label: 'Next', hotkey: 'n', plain: true, onPress: noop }),
    Button({ key: 'skip', label: 'Skip', dimColor: true, onPress: noop }),
  ],
})

Un pannello con tre pulsanti, uno per riga: Save tra parentesi quadre, n: Next senza parentesi e con la n a colori, e Skip tra parentesi quadre in grigio.

Un pulsante che ha il focus viene disegnato in video inverso. Qui l’utente ha premuto Tab due volte:

Gli stessi tre pulsanti, con il secondo, n: Next, disegnato in video inverso.

`Input`

Un Input è un campo di testo su una riga che esegue onSubmit quando l’utente preme Invio:

Input({
  key: 'title',
  label: 'Title',
  placeholder: 'Type a title and press Enter',
  value: '',
  submitLabel: 'save',
  onSubmit: noop,
})

Senza il focus, il campo mostra la sua etichetta e il suo placeholder:

Un pannello con una riga: l'etichetta Title, seguita dal placeholder Type a title and press Enter in grigio.

Con il focus, l’etichetta diventa in grassetto, compare un cursore e il submitLabel viene mostrato dopo ⏎:

Lo stesso campo con l'etichetta in grassetto, un cursore a blocco sulla prima lettera del placeholder e un simbolo di invio seguito dalla parola save.

La digitazione sostituisce il placeholder:

Lo stesso campo contenente le lettere digitate Rel, seguite dal simbolo di invio e dalla parola save.

`Select`

Un Select permette all’utente di scegliere una tra diverse opzioni ed esegue onSelect con il value dell’opzione:

Select({
  key: 'format',
  label: 'Format',
  value: picked,
  options: [
    { value: 'md', label: 'Markdown' },
    { value: 'html', label: 'HTML' },
    { value: 'txt', label: 'Plain text' },
  ],
  onSelect: (value) => {
    picked = value
  },
})

Chiuso, mostra la sua etichetta e l’opzione corrente:

Un pannello con una riga: l'etichetta Format, l'opzione corrente Markdown e una piccola freccia verso il basso.

Aperto, elenca le sue opzioni e ne evidenzia una:

Il selettore aperto, con le sue tre opzioni elencate sotto l'etichetta. La seconda opzione, HTML, è disegnata in video inverso.

Dopo che l’utente ha scelto un’opzione, l’elenco si chiude:

Il selettore di nuovo chiuso, che ora mostra HTML come opzione corrente.

Disegnare immagini

`Raster`

Un Raster è una griglia di celle di caratteri colorate, per una mappa di calore, una sparkline o una scacchiera di gioco. Lo disegna il terminale. Questo esempio usa la funzione cellsOf del modulo iniziale, che comprime le celle nella stringa accettata da un Raster. Disegnare una griglia di celle colorate la spiega:

Raster({
  key: 'grid',
  columns: 3,
  rows: 2,
  cells: cellsOf([
    [['█', 0x2e7d32], ['█', 0xf9a825], ['█', 0xc62828]],
    [['█', 0x2e7d32], ['█', 0x2e7d32], ['█', 0xf9a825]],
  ]),
})

Un pannello con una piccola griglia di blocchi colorati, due righe da tre: verde, ambra e rosso, poi verde, verde e ambra.

Un Raster arrotonda ogni colore a una tavolozza più ridotta, quindi 0x2e7d32 viene disegnato come #337733.

`Svg`

Un Svg disegna un documento SVG nell’app Desktop:

Svg({
  alt: 'Three bars of rising height',
  width: 120,
  height: 60,
  source:
    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 60"><rect x="10" y="40" width="20" height="20" fill="#2e7d32"/><rect x="50" y="25" width="20" height="35" fill="#f9a825"/><rect x="90" y="5" width="20" height="55" fill="#c62828"/></svg>',
})

Nel terminale, un pannello che restituisce solo un Svg si apre vuoto. Per disegnare qualcos’altro lì, controlla e.surface e restituisci un albero diverso.

`Image` e `Client`

Altri due elementi non hanno un esempio qui. Image disegna un PNG o pixel grezzi nel terminale. Client è un’area disegnata da un tuo secondo file, per animazioni e input del puntatore. Il riferimento degli elementi elenca le loro prop.

Vedere dove può disegnare una mod

Tutti gli esempi disegnano in un pannello. Una mod può disegnare anche in altri punti e chiedere a Claude Code di mostrare qualcosa per suo conto:

Pannello e banda: Scegliere dove disegnare
Le righe proprie di Claude Code, come lo spinner: Modificare ciò che Claude Code già disegna
Toast, riga di stato e riga di log: Mostrare qualcosa senza avviare un turno
Finestra di domanda: Sospendere una chiamata a uno strumento finché l’utente non decide

Passaggi successivi

Disegnare nell’interfaccia: crea un pannello con schede, passo dopo passo
Testare un disegno: premi i tuoi pulsanti da un test
Riferimento degli elementi: le prop principali di ogni elemento e le app che lo disegnano

Plugin

Usa i plugin

Crea plugin

Mod

Gestisci un marketplace

Gestisci i plugin per la tua organizzazione

Risoluzione dei problemi

Riferimento

Galleria dell'interfaccia per le mod

Provare un esempio

Scegliere un elemento

Mostrare testo

`Text`

`Markdown`

`Link`

Mostrare codice e modifiche

`Code`

`Code` come diff

Disporre gli elementi

`Box`

Ricevere input

`Button`

`Input`

`Select`

Disegnare immagini

`Raster`

`Svg`

`Image` e `Client`

Vedere dove può disegnare una mod

Passaggi successivi

​Provare un esempio

​Scegliere un elemento

​Mostrare testo

​Text

​Markdown

​Link

​Mostrare codice e modifiche

​Code

​Code come diff

​Disporre gli elementi

​Box

​Ricevere input

​Button

​Input

​Select

​Disegnare immagini

​Raster

​Svg

​Image e Client

​Vedere dove può disegnare una mod

​Passaggi successivi

Provare un esempio

Scegliere un elemento

Mostrare testo

`Text`

`Markdown`

`Link`

Mostrare codice e modifiche

`Code`

`Code` come diff

Disporre gli elementi

`Box`

Ricevere input

`Button`

`Input`

`Select`

Disegnare immagini

`Raster`

`Svg`

`Image` e `Client`

Vedere dove può disegnare una mod

Passaggi successivi