Prezentare generală
NumberField expune toate cele șapte componente ale câmpului numeric Base UI instalat: Root, Group, Input, Decrement, Increment, ScrubArea și ScrubAreaCursor. Importați-l din twenty-ui/primitives/input. Păstrează starea numerică, formatarea, incrementarea, detaliile evenimentelor și integrarea formularelor native din Base UI, cu stilizarea Twenty UI pentru comenzile de introducere, grupare și ajustare.
Pentru presetarea compactă cu formatare fixă și valori implicite pentru pașii modificatori, utilizați NumberStepper din twenty-ui/components/input.
Utilizare
Root gestionează starea numerică. Input este introducerea de text vizibilă. Utilizați Group pentru a aranja în jurul acestuia controalele opționale de decrementare și incrementare. Furnizați conținut și nume accesibile pentru controale; primitiva nu inserează pictograme sau etichete.
Field.Label, Field.Description și Field.Error se asociază cu introducerea vizibilă. Alternativ, transmiteți aria-label sau aria-labelledby către Input. Valoarea implicită pentru aria-roledescription este Number field; aceasta nu oferă un nume accesibil.
Valori și callbackuri
Omitețivalue pentru un câmp necontrolat și furnizați un defaultValue numeric atunci când este necesară o valoare inițială. Omiterea lui defaultValue pornește cu un câmp gol. Pentru un câmp controlat, transmiteți un număr sau null prin value și actualizați-l din onValueChange.
null, inclusiv când este setat min. Schițele incomplete, precum -, rămân editabile fără a raporta un număr nevalid. Tastarea care poate fi analizată actualizează valoarea numerică înainte ca editarea să fie confirmată. Primul pas de la o valoare goală pornește de la zero, limitat la granițe; pașii următori folosesc valoarea pasului activ.
onValueChange(value, details) păstrează event, reason, cancel, allowPropagation, isCanceled, isPropagationAllowed, trigger și direction opțional. Motivele disting tastarea (input-change), golirea (input-clear), normalizarea la pierderea focalizării (input-blur), lipirea (input-paste), apăsările de taste, incrementarea sau decrementarea, rotița, ajustarea prin glisare și completarea automată nativă (none). Apelarea cancel() împiedică actualizarea stării numerice; apelanții controlați aleg în continuare valoarea acceptată.
onValueCommitted(value, details) se execută la pierderea focalizării după editare, la eliberarea indicatorului după incrementare/decrementare sau ajustare prin glisare și imediat pentru ajustările prin tastatură și rotiță. Golirea confirmă null la pierderea focalizării. Detaliile confirmării conțin event și reason; sunt detalii generice fără metode de anulare a modificării. Focalizarea și pierderea focalizării unui câmp neatins nu confirmă prin ele însele o valoare atunci când nu este necesară nicio normalizare numerică. Opțiunile explicite de rotunjire pot normaliza și confirma o valoare neatinsă.
Setări regionale și formatare
Setațilocale și format pe Root. Acestea păstrează contractul Base UI instalat: locale acceptă Intl.LocalesArgument, iar format acceptă Intl.NumberFormatOptions. Formatarea afișării este separată de valoarea numerică brută transmisă de formular. Primitiva nu impune cifre latine, grupare, precizie sau pași modificatori.
Pași și limite
step are implicit valoarea 1, smallStep are valoarea 0.1 cât timp Alt este apăsată, iar largeStep are valoarea 10 cât timp Shift este apăsată. Pasul activ se aplică butoanelor, tastelor Săgeată sus și Săgeată jos, rotiței și deplasării în zona de ajustare prin glisare. snapOnStep are implicit valoarea false; activați-l pentru a alinia ajustările la pasul activ. Home și End selectează limita explicită corespunzătoare. Gestionarii nativi ai tastelor pot apela event.preventBaseUIHandler() atunci când proprietarul trebuie să suprascrie comportamentul de tastatură al Base UI.
min și max sunt incluzive. Interacțiunile de incrementare/decrementare rămân în limite. În mod implicit, valorile tastate și lipite sunt și ele limitate numeric, iar schița este normalizată la pierderea focalizării. Setați allowOutOfRange pentru a accepta editări directe în afara acelor limite și pentru a permite validării native a intervalului sau validării aplicației să raporteze problema.
step="any" dezactivează validarea nativă a pașilor, în timp ce incrementarea/decrementarea interactivă utilizează 1 și pașii modificatori configurați. Cu un pas numeric, furnizați explicit min atunci când transmiterea nativă trebuie să valideze alinierea la pas. Pasul numeric nu rotunjește fiecare valoare tastată la un pas.
Ajustare prin glisare
ScrubArea modifică valoarea numerică pe măsură ce indicatorul se deplasează. Acceptă deplasarea orizontală sau verticală, pixelSensitivity și teleportDistance opțional. Pasul activ și limitele se aplică și ajustării prin glisare. Utilizați o etichetă vizibilă ca țintă pentru ajustarea prin glisare, păstrând în același timp introducerea disponibilă pentru editare cu tastatura.
Compuneți ScrubAreaCursor în interiorul ScrubArea pentru un cursor personalizat în timpul ajustării prin glisare cu blocarea indicatorului. Acesta este portalizat în corpul documentului cât timp este activ. Base UI revine la cursorul normal pentru introducerea tactilă, blocarea indicatorului refuzată și WebKit. Setați allowWheelScrub pe Root pentru a permite ajustarea cu rotița cât timp introducerea este focalizată și sub indicator; valoarea implicită este false.
Formulare și stare dezactivată
Root redă un input type="number" nativ ascuns pentru transmiterea numerică brută și validarea nativă. Setați name, form, required, min, max și step pe Root. form poate asocia câmpul cu un formular din altă parte a documentului. Controalele de ajustare implicite utilizează type="button", astfel încât incrementarea/decrementarea nu transmite formularul.
disabled împiedică interacțiunea și exclude valoarea de la transmitere. readOnly împiedică modificările, păstrând în același timp introducerea vizibilă focalizabilă și valoarea sa de formular disponibilă. Utilizați o valoare controlată atunci când aplicația trebuie să reseteze starea numerică; resetarea nativă a formularului nu o resetează.
Ținte DOM și personalizare
Atributele native,
className, style și render vizează partea care le primește. Personalizarea introducerii se aplică controlului vizibil; personalizarea învelișului aparține lui Root sau Group. Pentru a focaliza controlul, utilizați Input.ref, nu Root.inputRef.
Fiecare parte acceptă un element sau un callback prin render, cu tipul de stare public corespunzător. Transmiteți proprietățile și referința furnizate către elementul DOM corespunzător, astfel încât editarea, focalizarea, etichetele și validarea să continue să funcționeze. Când un control de incrementare/decrementare redă un element care nu este buton, setați nativeButton={false}. className și style acceptă și callbackuri de stare. Starea include value numeric, inputValue formatat, required, disabled, readOnly, scrubbing și starea Field moștenită.
Punctele de intrare publice exportă proprietățile și tipul de stare pentru fiecare parte, plus NumberFieldRootChangeEventDetails, NumberFieldRootChangeEventReason, NumberFieldRootCommitEventDetails și NumberFieldRootCommitEventReason.
Rendererul componentei Front
Fixture-urile sandbox React și Preact verifică formatarea inițială a setărilor regionale, lipirea localizată, valorile brute numerice ale formularului, etichetele accesibile, referințele, compunerea redării, confirmările la pierderea focalizării, detaliile modificării și confirmării prin tastatură și detaliile modificării prin indicator. Tastarea secvențială după golirea unui câmp localizat controlat resetează în prezent cursorul de inserare în renderer: tastarea lui2 și apoi a lui 3 poate produce 32. O ajustare formatată cu indicatorul poate, de asemenea, să intre în concurență cu pierderea focalizării și să lase introducerea vizibilă afișând valoarea anterioară. Ajustările cu indicatorul raportează modificări, dar eliberarea indicatorului nu furnizează callbackul de confirmare corespunzător; pierderea focalizării ulterioară poate confirma în schimb cu input-blur. Glisarea zonei de ajustare și utilizarea cursorului său personalizat nu sunt disponibile nici în sandbox. Aceste limitări nu afectează gazdele React obișnuite.
Proprietăți
Referința este generată din tipurile publice ale componentelor instalate. Atributele native și gestionarii de evenimente sunt, de asemenea, acceptați în părțile care redau elemente.NumberField.Root
boolean
implicit:"false"
Allows typed, pasted, and autofilled values outside min and max. Native range validation still applies; step interactions remain bounded.
boolean
implicit:"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
implicit:"empty"
Initial uncontrolled number. Omit to start empty; the public type accepts a number.
boolean
implicit:"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
implicit:"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
implicit:"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
implicit:"false"
Requires a numeric value for native form submission.
number
implicit:"0.1"
Amount used while Alt is held. Defaults to 0.1.
boolean
implicit:"false"
Snaps step interactions to multiples of the active step. Defaults to false.
number | "any"
implicit:"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
implicit:"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
implicit:"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
implicit:"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"
implicit:"horizontal"
Pointer movement direction used for scrubbing.
number
implicit:"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.