Salt la conținutul principal

Prezentare generală

NumberStepper este presetarea convenabilă compactă creată din NumberField. Combină o intrare de text numeric cu butoane opționale de decrementare și incrementare. Importați-l din twenty-ui/components/input. Utilizați NumberField atunci când aveți nevoie de opțiuni de localizare sau formatare, pași modificatori diferiți, ajustare prin glisare sau compunerea independentă a părților.

Utilizare

Opțiuni vizuale

Comparați stările implicite, cu limite, dezactivate, doar în citire și nevalide, cu sau fără butoane de incrementare.

Valoare necontrolată

Utilizați defaultValue pentru a seta cantitatea inițială. Câmpul de intrare gestionează modificările ulterioare.

Valoare controlată

Transmiteți un număr sau null prin value și actualizați-l în onValueChange pentru a gestiona aceeași cantitate în starea React. Callbackul primește următoarea valoare numerică și detaliile evenimentului.
Golirea câmpului raportează null. Textul incomplet, precum - sau +, rămâne editabil fără a raporta un număr nevalid până când este înlocuit sau modificat cu un pas. În mod implicit, editările numerice analizabile raportează valoarea încadrată în limite; schița afișată este normalizată la pierderea focalizării. Valorile egale cu valoarea curentă nu apelează din nou onValueChange. onValueCommitted(value, details) raportează valoarea după confirmarea unei editări: la pierderea focalizării după tastare sau golire, la eliberarea indicatorului după o ajustare prin buton și imediat pentru ajustările de la tastatură. Detaliile sale conțin event nativ și reason. onValueChange păstrează detaliile modificării, inclusiv metodele de anulare și direcția opțională de ajustare cu pas.

Validarea aplicației

Setați allowOutOfRange atunci când aplicația are nevoie de valoarea analizată înainte de a aplica propriile limite sau propria validare. onValueChange primește apoi numere tastate și lipite din afara intervalului. Câmpurile necontrolate sau câmpurile controlate care acceptă acele valori le păstrează la pierderea focalizării. Câmpurile controlate care le resping revin la valoarea lor acceptată la pierderea focalizării. De exemplu, înlocuirea lui 60 cu 45 raportează 4 și apoi 45, chiar și atunci când min={30}. Aplicația poate ignora valoarea intermediară fără a salva accidental valoarea minimă. Butoanele și ajustările de la tastatură se opresc totuși la min și max. Validarea nativă a formularului împiedică trimiterea cât timp o valoare acceptată este în afara acelui interval. allowOutOfRange este implicit false.

Limite și interacțiune

min și max sunt incluzive. Butoanele de incrementare și decrementare se opresc la limita corespunzătoare. Săgeată sus și Săgeată jos ajustează câmpul de intrare focalizat cu step, care este implicit 1. Home și End selectează limita corespunzătoare atunci când este furnizată; apelați event.preventBaseUIHandler() în onKeyDown pentru a păstra în schimb comportamentul de editare a textului al unei taste. Același pas se aplică atunci când Shift sau Alt este apăsată. Valorile afișate acceptă până la 15 cifre fracționare; utilizați un pas pozitiv în cadrul acestei precizii pentru ajustări zecimale. Valorile folosesc cifre latine și afișează separatori de grupare începând de la cinci cifre întregi, precum 12,500. Sunt acceptați separatorii de grupare ai localizării browserului, tastați și lipiți. step controlează ajustările; nu rotunjește valorile tastate la un pas. Când min este setat, validarea nativă a formularului necesită și min plus un multiplu de step: cu step implicit de 1, un 2.5 tastat blochează trimiterea. Setați showButtons={false} pentru editarea textului cu același comportament de la tastatură. Fiecare buton are un nume accesibil implicit. Utilizați decrementLabel și incrementLabel pentru a oferi nume contextuale sau traduse. Oferiți câmpului de intrare un Field.Label vizibil, aria-label sau aria-labelledby.

Formulare și focalizare

Utilizați name pentru a include valoarea numerică într-un formular. form îl asociază cu un formular din altă parte a documentului. Butoanele de ajustare utilizează type="button", astfel încât ajustarea unei valori nu trimite formularul. required participă la validarea nativă. Utilizați un value controlat atunci când aplicația trebuie să reseteze câmpul. O resetare nativă a formularului nu resetează starea numerică. disabled împiedică modificările și exclude valoarea din trimiterea formularului. readOnly împiedică modificările, păstrând în același timp câmpul de intrare focalizabil și valoarea sa disponibilă pentru formular. Atributele și gestionarii de evenimente ai câmpului de intrare nativ, className, style, ref și render se aplică câmpului de intrare de text vizibil. Referința primește un HTMLInputElement; apelați ref.current?.focus() pentru a-l focaliza. Când compuneți prin render, transmiteți props și referința furnizate către un câmp de intrare nativ. Personalizați aspectul înconjurător cu un element separat sau utilizați părțile NumberField.Root și NumberField.Group atunci când este necesar accesul la înveliș. Combinați câmpul de intrare cu Field.Description și Field.Error pentru mesaje de orientare și validare. Presetarea utilizează în mod deliberat stil compact, cifre latine, până la 15 cifre fracționare, grupare de la cinci cifre întregi și același step pentru ajustările obișnuite, cu Shift și cu Alt. Aceste opțiuni se aplică numai la NumberStepper. Primitiva completă NumberField păstrează opțiunile de formatare și ajustare cu pași ale Base UI.

Renderer de componente Front

Sandboxurile rendererului React și Preact acceptă tastarea, ajustările de la tastatură, limitele, valorile formularului, ajustarea cu indicatorul și lipirea peste textul selectat. Galeria rendererului verifică aceste interacțiuni în ambele runtime-uri. Ca și în cazul NumberField, ajustările cu indicatorul raportează modificări, dar sandboxul nu livrează în prezent callbackul de confirmare corespunzător la eliberarea indicatorului. Gazdele React obișnuite păstrează comportamentul complet de confirmare.

Proprietăți

boolean
implicit:"false"
Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded.
string
implicit:"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
implicit:"Decrease value"
Accessible name for the decrement button.
number
Initial number when the field owns its value.
boolean
implicit:"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
implicit:"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
implicit:"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
implicit:"false"
Requires a numeric value for native form submission.
boolean
implicit:"true"
Shows the decrement and increment buttons.
number
implicit:"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.