Panoramica
NumberStepper è il preset compatto e pratico basato su NumberField. Combina un input di testo numerico con pulsanti facoltativi di decremento e incremento. Importalo da twenty-ui/components/input. Usa NumberField quando ti servono opzioni relative alle impostazioni locali o alla formattazione, passaggi dei modificatori diversi, lo scrubbing o la composizione indipendente delle parti.
Utilizzo
Opzioni visive
Confronta gli stati predefinito, limitato, disabilitato, di sola lettura e non valido, con o senza pulsanti di incremento.Valore non controllato
UsadefaultValue per impostare la quantità iniziale. L’input gestisce le modifiche successive.
Valore controllato
Passa un numero onull tramite value e aggiornalo in onValueChange per gestire la stessa quantità nello stato React. Il callback riceve il valore numerico successivo e i dettagli dell’evento.
null. Il testo incompleto, come - o +, rimane modificabile senza riportare un numero non valido finché non viene sostituito o modificato a passi. Per impostazione predefinita, le modifiche numeriche analizzabili restituiscono il valore entro i limiti; la bozza visualizzata viene normalizzata alla perdita del focus. I valori uguali al valore corrente non richiamano di nuovo onValueChange.
onValueCommitted(value, details) restituisce il valore dopo la conferma di una modifica: alla perdita del focus dopo la digitazione o la cancellazione, al rilascio del puntatore dopo una regolazione tramite pulsante e immediatamente per le regolazioni da tastiera. I relativi dettagli contengono event nativo e reason. onValueChange conserva i dettagli della modifica, inclusi i metodi di annullamento e la direzione facoltativa del passo.
Convalida dell’applicazione
ImpostaallowOutOfRange quando l’applicazione necessita del valore analizzato prima di applicare i propri limiti o la propria convalida. onValueChange riceve quindi i numeri digitati e incollati al di fuori dell’intervallo. I campi non controllati, o i campi controllati che accettano tali valori, li mantengono alla perdita del focus. I campi controllati che li rifiutano tornano al valore accettato alla perdita del focus. Ad esempio, sostituendo 60 con 45 vengono restituiti 4 e poi 45, anche quando min={30}. L’applicazione può ignorare il valore intermedio senza salvare accidentalmente il minimo.
I pulsanti e le regolazioni da tastiera si fermano comunque a min e max. La convalida nativa del modulo impedisce l’invio finché un valore accettato è al di fuori di tale intervallo. allowOutOfRange è impostato su false per impostazione predefinita.
Limiti e interazione
min e max sono inclusivi. I pulsanti di incremento e decremento si fermano al limite corrispondente. Freccia su e Freccia giù regolano l’input attivo di step, che per impostazione predefinita è 1. Home e Fine selezionano il limite corrispondente quando fornito; chiama event.preventBaseUIHandler() in onKeyDown per mantenere invece il comportamento di modifica del testo di un tasto. Lo stesso passo si applica quando si tiene premuto Maiusc o Alt. I valori visualizzati supportano fino a 15 cifre frazionarie; usa un passo positivo entro tale precisione per le regolazioni decimali.
I valori utilizzano cifre latine e visualizzano separatori di raggruppamento a partire da cinque cifre intere, ad esempio 12,500. Sono accettati i separatori delle migliaia digitati e incollati delle impostazioni locali del browser.
step controlla le regolazioni; non arrotonda i valori digitati a un passo. Quando è impostato min, la convalida nativa del modulo richiede anche min più un multiplo di step: con il valore predefinito di step pari a 1, un 2.5 digitato blocca l’invio. Imposta showButtons={false} per modificare il testo con lo stesso comportamento da tastiera.
Ogni pulsante ha un nome accessibile predefinito. Usa decrementLabel e incrementLabel per fornire nomi contestuali o tradotti. Fornisci all’input un Field.Label visibile, aria-label o aria-labelledby.
Moduli e focus
Usaname per includere il valore numerico in un modulo. form lo associa a un modulo presente altrove nel documento. I pulsanti di regolazione usano type="button", quindi la regolazione di un valore non invia il modulo. required partecipa alla convalida nativa.
Usa un value controllato quando l’applicazione deve reimpostare il campo. Il ripristino nativo di un modulo non reimposta lo stato numerico.
disabled impedisce le modifiche ed esclude il valore dall’invio del modulo. readOnly impedisce le modifiche mantenendo l’input attivabile e il relativo valore disponibile per il modulo.
Gli attributi e i gestori dell’input nativo, className, style, ref e render si applicano all’input di testo visibile. Il ref riceve un HTMLInputElement; chiama ref.current?.focus() per attivarlo. Quando esegui la composizione tramite render, inoltra le props e il ref forniti a un input nativo. Personalizza il layout circostante con un elemento separato oppure usa le parti NumberField.Root e NumberField.Group quando è necessario accedere al wrapper. Combina l’input con Field.Description e Field.Error per messaggi di guida e convalida.
Il preset usa deliberatamente uno stile compatto, cifre latine, fino a 15 cifre frazionarie, raggruppamento a partire da cinque cifre intere e lo stesso step per le regolazioni normali, con Maiusc e con Alt. Queste scelte si applicano solo a NumberStepper. La primitiva completa NumberField mantiene le opzioni di formattazione e regolazione a passi di Base UI.
Renderer del componente Front
Le sandbox del renderer React e Preact supportano la digitazione, le regolazioni da tastiera, i limiti, i valori dei moduli, la regolazione tramite puntatore e l’incollaggio sul testo selezionato. La galleria del renderer verifica queste interazioni in entrambi i runtime. Come perNumberField, le regolazioni tramite puntatore restituiscono le modifiche, ma la sandbox al momento non fornisce il callback di conferma corrispondente al rilascio del puntatore. Gli host React ordinari mantengono il comportamento di conferma completo.
Props
boolean
predefinito:"false"
Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded.
string
predefinito:"Number field"
A user-friendly description of the input’s role for assistive tech. This is a role
description, not an accessible name — use
Field.Label or aria-label to name the control.string | ((state: NumberFieldInputState) => string | undefined)
Class applied to the visible input.
string
predefinito:"Decrease value"
Accessible name for the decrement button.
number
Initial number when the field owns its value.
boolean
predefinito:"false"
Disables the input and both buttons, and omits the form value.
string
ID of the form that owns the submitted numeric value.
string
ID of the visible input. Generated when omitted.
string
predefinito:"Increase value"
Accessible name for the increment button.
number
Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.
number
Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.
string
Name of the numeric value submitted with a form.
((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) => void)
Called with the next number or null and event details when the numeric value changes. Clearing reports null; incomplete text does not report a number.
((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) => void)
Called with the committed number or null and generic event details after an edit is committed. Details contain the native event and reason, without change cancellation methods.
boolean
predefinito:"false"
Prevents numeric changes while keeping the input focusable.
Ref<HTMLInputElement>
Ref to the visible input element.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, NumberFieldInputState>
Composes the visible text input with an element or render callback. Forward the supplied props and ref to an input. Use a separate element to customize the surrounding layout.
boolean
predefinito:"false"
Requires a numeric value for native form submission.
boolean
predefinito:"true"
Shows the decrement and increment buttons.
number
predefinito:"1"
Amount added or subtracted by the buttons and arrow keys.
CSSProperties | ((state: NumberFieldInputState) => CSSProperties | undefined)
Inline styles applied to the visible input.
number | null
Controlled numeric value. Use null for an empty field.