Salt la conținutul principal

Prezentare generală

PhoneCountryPicker combină un declanșator cu steagul țării, o fereastră pop-up, căutarea și opțiuni pentru codurile de apelare. Folosește componenta completă pentru selectarea obișnuită sau compune Root, Trigger și Options cu Dropdown atunci când ai nevoie de o fereastră pop-up personalizată. Ambele forme partajează aceleași țări pregătite și aceeași selecție.

Utilizare

Furnizează propriile date despre țări și un nume accesibil pentru declanșator. Folosește value cu onValueChange pentru selecția controlată sau defaultValue pentru selecția necontrolată. null reprezintă absența unei țări selectate.
Fiecare PhoneCountryOption are un value unic și stabil, un label localizat pentru țară, un callingCode format numai din cifre, fără semnul plus de la început, și un nod flag decorativ. Poate fi și disabled. Valorile sunt identificatori deținuți de apelant, precum codurile de țară ISO, și sunt returnate nemodificate. Etichetele, steagurile și codurile de apelare sunt date de prezentare și nu devin identificatorul selectat. Selectorul adaugă semnul plus și izolează codurile de apelare de la stânga la dreapta în rândurile opțiunilor și în indicațiile de instrumente pentru depășire, inclusiv în interfețele de la dreapta la stânga. Furnizează țările în ordinea în care dorești să fie afișate. Țara selectată apare prima cât timp corespunde interogării; celelalte potriviri își păstrează ordinea furnizată.

Compunere compusă

Aceasta este o modificare incompatibilă a API-ului pentru apelanții compuși existenți. Adaugă PhoneCountryPicker.Root în jurul lui Dropdown.Root, mută countries, value și onValueChange din Options în Root și elimină Trigger.country. Ambele părți necesită acum Root și derivă din acesta țara selectată. Root gestionează țările și selecția controlată sau necontrolată. Plasează Dropdown.Root partajat în interiorul său și compune declanșatorul, conținutul și opțiunile. Trigger își derivă steagul selectat și descrierea accesibilă din Root; Options citește aceleași date și aceeași selecție. Nu furniza altă țară sau altă valoare selectată acelor părți.
Păstrează o singură rădăcină pentru fiecare selector. Dropdown-ul partajat gestionează deschiderea, poziționarea ferestrei pop-up, paginile, focalizarea și navigarea prin căutare. Folosește dropdownProps și contentProps pe selectorul complet sau configurează direct părțile Dropdown în utilizarea compusă.

Căutare și selectare

Căutarea găsește subșiruri în etichetele furnizate ale țărilor, identificatorii stabili și codurile de apelare. Etichetele și identificatorii folosesc normalizarea partajată normalizeSearchText: text cu litere mici, descompunere Unicode NFD și gestionarea accentelor care ține cont de sistemul de scriere. De exemplu, reunion corespunde cu Réunion, iar gb corespunde cu un identificator GB. Distincțiile semnificative din sistemele de scriere sunt păstrate conform acelui ajutor. Spațiile albe din jurul interogării sunt eliminate; spațiile albe interne sunt păstrate. Pentru căutarea după codul de apelare, un semn plus la început este opțional, astfel încât 44, +44 și " +44 " corespund codului de apelare furnizat 44. Căutarea nu analizează un număr de telefon complet și nu deduce o țară din acesta. onValueChange(value, eventDetails) primește identificatorul solicitat și detaliile partajate ale Dropdown.SelectionGroup: reason, event nativ, trigger al opțiunii selectate, cancel() și isCanceled. Apelează cancel() înainte de actualizarea stării controlate pentru a respinge solicitarea. O solicitare anulată păstrează selecția necontrolată și lasă fereastra pop-up deschisă. Setează closeOnSelect={false} pentru a o menține deschisă după o selecție acceptată. Modificările selecției nu schimbă nicio valoare a câmpului de introducere a numărului de telefon. Setează disabled pe selectorul complet sau pe Root pentru a-i dezactiva declanșatorul, căutarea și selecția. O țară dezactivată rămâne vizibilă și nu poate fi selectată. Trigger.disabled și Options.disabled pot dezactiva suplimentar acele părți individuale.

Ținte și etichete native

Atributele native, gestionarele de evenimente, className, style, ref, render și children opțional ale selectorului complet vizează declanșatorul său. children înlocuiește steagul implicit sau pictograma globului și indicatorul chevron. contentProps vizează Dropdown.Content; optionsProps vizează div-ul rădăcină al opțiunilor și furnizează searchLabel, listLabel și emptyLabel. În utilizarea compusă, proprietățile native, referințele și compunerea de randare vizează butonul Trigger sau div-ul Options corespunzător. Root nu redă niciun nod DOM. Furnizează etichete localizate pentru țări și aria-label necesar pentru declanșator. Eticheta țării selectate descrie declanșatorul, în timp ce steagul și indicatorul chevron sunt decorative. O selecție goală afișează o pictogramă cu globul. Fereastra pop-up preia numele declanșatorului, cu excepția cazului în care un Dropdown.Title sau o etichetă explicită pentru conținut îi atribuie un nume. searchLabel are implicit valoarea Search și denumește atât câmpul de căutare, cât și substituentul acestuia. listLabel are implicit valoarea Countries și denumește independent caseta cu listă. emptyLabel are implicit valoarea No results.

Integrarea câmpului de introducere a numărului de telefon

Selectorul este livrat fără un catalog de țări, un pachet de resurse pentru steaguri sau un mediu de execuție pentru câmpul de introducere a numărului de telefon. Adaptorul frontend gestionează analiza, validarea, formatarea numerelor de telefon, schițele de editare și persistența. Mapează țara selectată din biblioteca de telefonie la Root.value sau la value al selectorului complet și mapează înapoi modificările țării printr-un singur callback. Păstrează textul numărului de telefon în proprietarul său existent atunci când modifici sau ștergi o țară ori aplici o actualizare externă a țării selectate. Trimiterea nativă a formularului, resetarea, obligatoriu, doar pentru citire și integrarea cu Field pentru acest selector personalizat sunt amânate. Selectorul complet transmite atributele native ale declanșatorului conform contractului pentru buton Dropdown.

Rendererul componentei Front

Exemplele din galerie pentru React și Preact includ selectorul complet și compunerea compusă. Poziționarea portalului, geometria, derularea, închiderea și focalizarea aparțin Dropdown-ului partajat și integrării cu renderer-ul. Selectorul nu introduce un mediu de execuție separat pentru renderer.

Proprietăți

string
obligatoriu
Required accessible name for the country selector trigger.
ReactNode
Optional trigger content replacing the default country flag or world icon and chevron.
string | ((state: PopoverTriggerState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
number
implicit:"0"
How long to wait before closing the popover that was opened on hover. Specified in milliseconds.Requires the openOnHover prop.
boolean
Closes the dropdown after an accepted selection. Defaults to true.
Omit<DropdownContentProps, "children">
Props for the internally assembled Dropdown.Content, including its accessible name, placement, width and popup ref.
readonly PhoneCountryOption[]
obligatoriu
Prepared choices with a unique stable value, localized label, digits-only calling code without a plus sign, decorative flag node and optional disabled state. Matching choices retain their supplied order after the selected country.
string | null
Initial uncontrolled country identifier. Omit it or use null to start empty.
number
implicit:"300"
How long to wait before the popover may be opened on hover. Specified in milliseconds.Requires the openOnHover prop.
boolean
Disables the trigger, search and country selection.
Omit<DropdownRootProps, "children" | "type" | "multiple">
Props for the internally assembled Dropdown.Root, including controlled open state and open-change events. The picker fixes its type to picker.
string
ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot triggerId prop).
boolean
implicit:"true"
Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).
((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)
Receives the requested country identifier or null and Dropdown.SelectionGroup event details, including reason, event, trigger and cancel(). Cancel before updating controlled state to reject a selection.
boolean
implicit:"false"
Whether the popover should also open when the trigger is hovered.
PhoneCountryPickerOptionsProps
Props for the options root div, including native attributes, ref, render, searchLabel, listLabel and emptyLabel. Search matches normalized labels and identifiers, or calling codes with an optional leading plus sign. Surrounding query whitespace is trimmed.
Ref<HTMLButtonElement>
Ref to the trigger button, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>
Composes the trigger with an element or render callback. Native attributes, handlers, className, style and ref target the trigger.
CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
string | null
Controlled country identifier. Use null to clear the selection. Labels and calling codes do not replace this value.

PhoneCountryPicker.Root

ReactNode
obligatoriu
A Dropdown.Root with type=“picker”, its Trigger, Content and Options. Root shares prepared data and selection and renders no DOM node.
boolean
implicit:"true"
Closes the composed Dropdown after an accepted selection. Defaults to true.
readonly PhoneCountryOption[]
obligatoriu
Prepared choices shared by Trigger and Options, with unique stable values, localized labels, digits-only calling codes without a plus sign, decorative flag nodes and optional disabled states.
string | null
implicit:"null"
Initial uncontrolled country identifier. Omit it or use null to start empty.
boolean
implicit:"false"
Disables the composed trigger, search and country selection.
((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)
Receives the requested identifier or null and Dropdown.SelectionGroup event details, including reason, event, trigger and cancel(). Cancel before updating controlled state to reject a selection.
string | null
Controlled country identifier shared by the parts. Use null to clear the selection.

PhoneCountryPicker.Trigger

string
obligatoriu
Required accessible name for the country selector button.
ReactNode
Optional trigger content replacing the selected country flag or empty world icon and chevron. The selected label comes from Root.
string | ((state: PopoverTriggerState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
number
implicit:"0"
How long to wait before closing the popover that was opened on hover. Specified in milliseconds.Requires the openOnHover prop.
number
implicit:"300"
How long to wait before the popover may be opened on hover. Specified in milliseconds.Requires the openOnHover prop.
boolean
Disables the native trigger button in addition to Root.disabled.
string
ID of the trigger. In addition to being forwarded to the rendered element, it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot triggerId prop).
boolean
implicit:"true"
Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).
boolean
implicit:"false"
Whether the popover should also open when the trigger is hovered.
Ref<HTMLButtonElement>
Ref to the trigger button, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>
Composes the Dropdown trigger with an element or render callback. Native attributes, handlers, className, style and ref target this element.
CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.

PhoneCountryPicker.Options

boolean
Disables search and selection in addition to Root.disabled.
string
implicit:"No results"
Status message shown when no country label, identifier or calling code matches. Defaults to No results.
string
implicit:"Countries"
Accessible name of the country listbox, separate from the search field. Defaults to Countries.
Ref<HTMLDivElement>
Ref to the options root div, or the element composed through render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Composes the non-interactive options root with an element or render callback. Native attributes, handlers, className, style and ref target this element. searchLabel names the internal search input.
string
implicit:"Search"
Accessible name and placeholder of the country search field. Defaults to Search. Search matches normalized labels and identifiers, or calling codes with an optional leading plus sign. Surrounding query whitespace is trimmed.