Vai al contenuto principale

Panoramica

NumberField espone tutte e sette le parti del campo numerico Base UI installato: Root, Group, Input, Decrement, Increment, ScrubArea e ScrubAreaCursor. Importalo da twenty-ui/primitives/input. Mantiene lo stato numerico, la formattazione, gli incrementi, i dettagli degli eventi e l’integrazione con i moduli nativi di Base UI, con lo stile di Twenty UI per i controlli di input, gruppo e regolazione. Per il preset compatto con formattazione fissa e valori predefiniti dei passaggi modificatori, usa NumberStepper da twenty-ui/components/input.

Utilizzo

Root gestisce lo stato numerico. Input è l’input di testo visibile. Usa Group per disporre attorno a esso i controlli facoltativi di decremento e incremento. Fornisci contenuto e nomi accessibili per i controlli; il componente primitivo non inserisce icone né etichette.
Field.Label, Field.Description e Field.Error si associano all’input visibile. In alternativa, passa aria-label o aria-labelledby a Input. Il valore predefinito di aria-roledescription è Number field; non fornisce un nome accessibile.

Valori e callback

Ometti value per un campo non controllato e fornisci un defaultValue numerico quando è necessario un valore iniziale. Omettendo defaultValue, il campo inizia vuoto. Per un campo controllato, passa un numero o null tramite value e aggiornalo da onValueChange.
La cancellazione restituisce null, incluso quando è impostato min. Bozze incomplete come - rimangono modificabili senza segnalare un numero non valido. La digitazione analizzabile aggiorna il valore numerico prima che la modifica venga confermata. Il primo passaggio da un valore vuoto inizia da zero, vincolato ai limiti; i passaggi successivi usano l’incremento attivo. onValueChange(value, details) mantiene event, reason, cancel, allowPropagation, isCanceled, isPropagationAllowed, trigger nativi e direction facoltativo. I motivi distinguono la digitazione (input-change), la cancellazione (input-clear), la normalizzazione alla perdita del focus (input-blur), l’incollamento (input-paste), tastiera, pressioni di incremento o decremento, rotellina, scrubbing e riempimento automatico nativo (none). La chiamata a cancel() impedisce l’aggiornamento dello stato numerico; i chiamanti controllati scelgono comunque il valore accettato. onValueCommitted(value, details) viene eseguito alla perdita del focus dopo la modifica, al rilascio del puntatore dopo il passaggio o lo scrubbing e immediatamente per le regolazioni tramite tastiera e rotellina. La cancellazione conferma null alla perdita del focus. I dettagli del commit contengono event e reason; sono dettagli generici senza metodi di annullamento delle modifiche. Mettere e togliere il focus a un campo non modificato non conferma di per sé un valore quando non è necessaria alcuna normalizzazione numerica. Le opzioni esplicite di arrotondamento possono normalizzare e confermare un valore non modificato.

Lingua e formattazione

Imposta locale e format su Root. Mantengono il contratto Base UI installato: locale accetta Intl.LocalesArgument e format accetta Intl.NumberFormatOptions. La formattazione visualizzata è separata dal valore numerico non elaborato inviato dal modulo. Il componente primitivo non impone cifre latine, raggruppamento, precisione o passaggi modificatori.
La digitazione e l’incollamento usano la lingua configurata e i simboli di formato supportati. La perdita del focus normalizza il testo visualizzato. Le opzioni esplicite di precisione o arrotondamento possono inoltre normalizzare il numero confermato; senza tali opzioni, la sola formattazione non sostituisce un valore numerico non modificato con testo visualizzato arrotondato.

Passaggi e limiti

step è predefinito a 1, smallStep a 0.1 mentre si tiene premuto Alt e largeStep a 10 mentre si tiene premuto Shift. Il passaggio attivo si applica a pulsanti, Freccia su e Freccia giù, rotellina e movimento nell’area di scrubbing. snapOnStep è predefinito a false; abilitalo per allineare le regolazioni al passaggio attivo. Home ed End selezionano il limite esplicito corrispondente. I gestori di tasti nativi possono chiamare event.preventBaseUIHandler() quando il proprietario deve sovrascrivere il comportamento della tastiera di Base UI. min e max sono inclusivi. Le interazioni di passaggio rimangono entro i limiti. Per impostazione predefinita, anche i valori digitati e incollati vengono limitati numericamente, con la bozza normalizzata alla perdita del focus. Imposta allowOutOfRange per accettare modifiche dirette al di fuori di tali limiti e lasciare che la convalida nativa dell’intervallo o dell’applicazione segnali il problema. step="any" disabilita la convalida nativa del passaggio, mentre il passaggio interattivo usa 1 e i passaggi modificatori configurati. Con un passaggio numerico, fornisci esplicitamente min quando l’invio nativo deve convalidare l’allineamento al passaggio. Il passaggio numerico non arrotonda ogni valore digitato a un passaggio.

Scorrimento

ScrubArea modifica il valore numerico mentre il puntatore si muove. Supporta il movimento orizzontale o verticale, pixelSensitivity e teleportDistance facoltativo. Il passaggio attivo e i limiti si applicano anche allo scrubbing. Usa un’etichetta visibile come destinazione dello scrubbing mantenendo disponibile l’input per la modifica tramite tastiera. Componi ScrubAreaCursor all’interno di ScrubArea per un cursore personalizzato durante lo scrubbing con blocco del puntatore. Quando è attivo, viene inserito tramite portale nel corpo del documento. Base UI usa il cursore normale come fallback per l’input touch, il blocco del puntatore negato e WebKit. Imposta allowWheelScrub su Root per consentire la regolazione tramite rotellina mentre l’input ha il focus e il puntatore è sopra di esso; il valore predefinito è false.

Moduli e stato disabilitato

Root esegue il rendering di un input type="number" nativo nascosto per l’invio numerico non elaborato e la convalida nativa. Imposta name, form, required, min, max e step su Root. form può associare il campo a un modulo in un’altra posizione del documento. I controlli di regolazione predefiniti usano type="button", quindi il passaggio non invia il modulo. disabled impedisce l’interazione ed esclude il valore dall’invio. readOnly impedisce le modifiche mantenendo l’input visibile selezionabile tramite focus e rendendo disponibile il suo valore del modulo. Usa un valore controllato quando l’applicazione deve reimpostare lo stato numerico; il reimpostazione del modulo nativo non lo reimposta.

Destinazioni DOM e personalizzazione

Gli attributi nativi, className, style e render hanno come destinazione la parte che li riceve. La personalizzazione dell’input si applica al controllo visibile; la personalizzazione del wrapper va applicata a Root o Group. Per mettere a fuoco il controllo, usa Input.ref anziché Root.inputRef. Ogni parte accetta un elemento o un callback tramite render, con il tipo di stato pubblico corrispondente. Inoltra le props e il ref forniti all’elemento DOM appropriato affinché modifica, focus, etichette e convalida continuino a funzionare. Quando un controllo di passaggio esegue il rendering di un elemento che non è un pulsante, imposta nativeButton={false}. Anche className e style accettano callback di stato. Lo stato include value numerico, inputValue formattato, required, disabled, readOnly, scrubbing e lo stato Field ereditato. I punti di ingresso pubblici esportano le props e il tipo di stato per ogni parte, oltre a NumberFieldRootChangeEventDetails, NumberFieldRootChangeEventReason, NumberFieldRootCommitEventDetails e NumberFieldRootCommitEventReason.

Renderer del componente front-end

Le fixture sandbox di React e Preact verificano la formattazione iniziale della lingua, l’incollamento localizzato, i valori numerici non elaborati del modulo, le etichette accessibili, i ref, la composizione del rendering, i commit alla perdita del focus, i dettagli di modifica e commit tramite tastiera e i dettagli di modifica tramite puntatore. La digitazione sequenziale dopo aver cancellato un campo localizzato controllato attualmente reimposta il cursore nel renderer: digitare 2 e poi 3 può produrre 32. Una regolazione formattata tramite puntatore può anche entrare in conflitto con la perdita del focus e lasciare l’input visibile con il valore precedente. Le regolazioni tramite puntatore segnalano le modifiche, ma il rilascio del puntatore non invia il callback di commit corrispondente; la successiva perdita del focus può invece confermare con input-blur. Anche il trascinamento dell’area di scrubbing e l’uso del relativo cursore personalizzato non sono disponibili nella sandbox. Queste limitazioni non influiscono sugli host React ordinari.

Props

Il riferimento è generato dai tipi pubblici del componente installato. Gli attributi nativi e i gestori di eventi sono accettati anche sulle parti che eseguono il rendering di elementi.

NumberField.Root

boolean
predefinito:"false"
Allows typed, pasted, and autofilled values outside min and max. Native range validation still applies; step interactions remain bounded.
boolean
predefinito:"false"
Allows wheel adjustments while the visible input is focused and hovered. Defaults to false.
ReactNode
Composed NumberField parts and supporting content.
string | ((state: NumberFieldRootState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
number
predefinito:"empty"
Initial uncontrolled number. Omit to start empty; the public type accepts a number.
boolean
predefinito:"false"
Prevents interaction and excludes the value from form submission.
string
ID of the form owning the hidden native number input.
NumberFormatOptions
Intl.NumberFormat options for display and parsing, including currency, units, percent, grouping, and precision. Explicit rounding options can normalize the committed value on blur.
string
ID associated with the visible input. Generated when omitted.
Ref<HTMLInputElement>
Ref to the hidden native number input used for submission and validation. Use Input.ref to focus the visible text input.
number
predefinito:"10"
Amount used while Shift is held. Defaults to 10.
LocalesArgument
Locale or locale list used to format and parse numbers. Defaults to the runtime locale.
number
Inclusive maximum for stepping and native range validation.
number
Inclusive minimum for stepping and native range validation.
string
Name of the raw numeric value submitted by the hidden input.
((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) => void)
Receives the next number or null and change details with the native event, reason, cancellation and propagation methods, and optional stepping direction.
((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) => void)
Receives the committed number or null and generic details containing event and reason. Typing commits on blur; pointer steps and scrubbing commit on release; keyboard and wheel changes commit immediately.
boolean
predefinito:"false"
Prevents changes while keeping the visible input focusable.
Ref<HTMLDivElement>
Ref to the root div, or the element composed through Root.render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldRootState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
boolean
predefinito:"false"
Requires a numeric value for native form submission.
number
predefinito:"0.1"
Amount used while Alt is held. Defaults to 0.1.
boolean
predefinito:"false"
Snaps step interactions to multiples of the active step. Defaults to false.
number | "any"
predefinito:"1"
Base amount for buttons, arrow keys, wheel, and scrubbing. Use any to disable native step validation while stepping by 1.
CSSProperties | ((state: NumberFieldRootState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.
number | null
Controlled raw numeric value. Use null for an empty field.

NumberField.Group

ReactNode
The visible input and any increment or decrement controls.
string | ((state: NumberFieldGroupState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
Ref<HTMLDivElement>
Ref to the group div, or the element composed through Group.render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldGroupState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldGroupState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.

NumberField.Input

string
predefinito:"Number field"
Describes the role to assistive technology. Defaults to Number field; use Field.Label, aria-label, or aria-labelledby for the accessible name.
string | ((state: NumberFieldInputState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
Ref<HTMLInputElement>
Ref to the visible native text input.
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. Customize layout through Root or Group.
number
Native input size attribute. Use styles to customize visual dimensions.
CSSProperties | ((state: NumberFieldInputState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.

NumberField.Increment

ReactNode
Visible content for the increment control. Supply its accessible name.
string | ((state: NumberFieldIncrementState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
boolean
predefinito:"true"
Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction.
Ref<HTMLButtonElement>
Ref to the increment button, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldIncrementState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldIncrementState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.

NumberField.Decrement

ReactNode
Visible content for the decrement control. Supply its accessible name.
string | ((state: NumberFieldDecrementState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
boolean
predefinito:"true"
Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction.
Ref<HTMLButtonElement>
Ref to the decrement button, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldDecrementState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldDecrementState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.

NumberField.ScrubArea

ReactNode
Content the user can drag to adjust the number, plus an optional ScrubAreaCursor.
string | ((state: NumberFieldScrubAreaState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
"horizontal" | "vertical"
predefinito:"horizontal"
Pointer movement direction used for scrubbing.
number
predefinito:"2"
Pixels of pointer movement needed for a step. Larger values reduce sensitivity.
Ref<HTMLSpanElement>
Ref to the scrub area span, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldScrubAreaState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldScrubAreaState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.
number
Optional distance from the scrub area center at which the pointer loops around.

NumberField.ScrubAreaCursor

ReactNode
Custom cursor content shown during supported pointer-lock scrubbing.
string | ((state: NumberFieldScrubAreaCursorState) => string | undefined)
Class applied to this part, or a callback receiving its NumberField state.
Ref<HTMLSpanElement>
Ref to the cursor span portaled to the document body while active. Null while absent.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, NumberFieldScrubAreaCursorState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: NumberFieldScrubAreaCursorState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its NumberField state.