Panoramica
PhoneCountryPicker combina un attivatore con bandiera del paese, popup, ricerca e scelte del prefisso telefonico. Usa il componente completo per la selezione ordinaria oppure componi Root, Trigger e Options con Dropdown quando ti serve un popup personalizzato. Entrambe le forme condividono gli stessi paesi preparati e la stessa selezione.
Utilizzo
Fornisci i tuoi dati sui paesi e un nome accessibile per l’attivatore. Usavalue con onValueChange per una selezione controllata oppure defaultValue per una selezione non controllata. null rappresenta l’assenza di un paese selezionato.
PhoneCountryOption ha un value stabile univoco, un label del paese localizzato, un callingCode composto solo da cifre senza il segno più iniziale e un nodo flag decorativo. Può anche essere disabled. I valori sono identificatori di proprietà del chiamante, come i codici paese ISO, e vengono restituiti invariati. Etichette, bandiere e prefissi telefonici sono dati di presentazione e non diventano l’identificatore selezionato.
Il selettore aggiunge il segno più e isola i prefissi telefonici da sinistra a destra nelle righe delle opzioni e nei tooltip di overflow, incluse le interfacce da destra a sinistra. Fornisci i paesi nell’ordine in cui desideri visualizzarli. Il paese selezionato appare per primo finché corrisponde alla query; le restanti corrispondenze mantengono l’ordine fornito.
Composizione composta
Questa è una modifica API incompatibile per gli utilizzatori esistenti della composizione composta. AggiungiPhoneCountryPicker.Root attorno a Dropdown.Root, sposta countries, value e onValueChange da Options a Root e rimuovi Trigger.country. Entrambe le parti ora richiedono Root e ne derivano il paese selezionato.
Root gestisce i paesi e la selezione controllata o non controllata. Inserisci al suo interno il Dropdown.Root condiviso e componi l’attivatore, il contenuto e le opzioni. Trigger deriva la bandiera selezionata e la descrizione accessibile da Root; Options legge gli stessi dati e la stessa selezione. Non fornire un altro paese o valore selezionato a tali parti.
dropdownProps e contentProps sul selettore completo oppure configura direttamente le parti Dropdown nell’uso composto.
Ricerca e selezione
La ricerca trova sottostringhe delle etichette dei paesi fornite, degli identificatori stabili e dei prefissi telefonici. Etichette e identificatori usano la normalizzazione condivisanormalizeSearchText: testo in minuscolo, decomposizione Unicode NFD e gestione degli accenti consapevole della scrittura. Ad esempio, reunion corrisponde a Réunion e gb corrisponde a un identificatore GB. Le distinzioni significative nelle scritture sono preservate in base a tale helper. Gli spazi bianchi attorno alla query vengono rimossi; gli spazi bianchi interni vengono preservati. Per la ricerca del prefisso telefonico, un segno più iniziale è facoltativo, quindi 44, +44 e " +44 " corrispondono al prefisso telefonico fornito 44. La ricerca non analizza un numero di telefono completo né ne deduce un paese.
onValueChange(value, eventDetails) riceve l’identificatore richiesto e i dettagli condivisi di Dropdown.SelectionGroup: reason, l’event nativo, il trigger dell’opzione selezionata, cancel() e isCanceled. Chiama cancel() prima di aggiornare lo stato controllato per rifiutare la richiesta. Una richiesta annullata preserva la selezione non controllata e lascia aperto il popup. Imposta closeOnSelect={false} per mantenerlo aperto dopo una selezione accettata. Le modifiche alla selezione non modificano alcun valore dell’input telefonico.
Imposta disabled sul selettore completo o su Root per disabilitarne l’attivatore, la ricerca e la selezione. Un paese disabilitato rimane visibile e non può essere selezionato. Trigger.disabled e Options.disabled possono inoltre disabilitare tali singole parti.
Destinazioni ed etichette native
Gli attributi nativi, i gestori di eventi,className, style, ref, render e l’elemento children facoltativo del selettore completo si applicano al relativo attivatore. children sostituisce la bandiera o l’icona del mondo predefinita e il chevron. contentProps si applica a Dropdown.Content; optionsProps si applica al div radice delle opzioni e fornisce searchLabel, listLabel e emptyLabel. Nell’uso composto, le proprietà native, i riferimenti e la composizione del rendering si applicano al pulsante Trigger o al div Options corrispondente. Root non esegue il rendering di alcun nodo DOM.
Fornisci etichette dei paesi localizzate e l’aria-label richiesto per l’attivatore. L’etichetta del paese selezionato descrive l’attivatore, mentre la relativa bandiera e il chevron sono decorativi. Una selezione vuota mostra un’icona del mondo. Il popup prende il nome dell’attivatore, a meno che non venga denominato da un Dropdown.Title o da un’etichetta esplicita del contenuto. searchLabel ha come valore predefinito Search e denomina sia il campo di ricerca sia il relativo segnaposto. listLabel è impostato per impostazione predefinita su Countries e denomina la casella di riepilogo in modo indipendente. emptyLabel ha come valore predefinito No results.
Integrazione dell’input telefonico
Il selettore viene fornito senza un catalogo di paesi, un pacchetto di risorse per le bandiere o un runtime per input telefonico. L’adattatore frontend gestisce l’analisi, la convalida e la formattazione dei numeri telefonici, le bozze di modifica e la persistenza. Mappa il paese selezionato della libreria telefonica suRoot.value o sul value del selettore completo e rimappa le modifiche del paese tramite un solo callback. Mantieni il testo telefonico nel relativo proprietario esistente quando modifichi o cancelli un paese oppure applichi un aggiornamento esterno del paese selezionato.
L’invio e il ripristino nativi del modulo, l’obbligatorietà, la modalità di sola lettura e l’integrazione con Field per questo selettore personalizzato sono rinviati. Il selettore completo inoltra gli attributi nativi dell’attivatore secondo il contratto del pulsante Dropdown.
Renderer dei componenti front-end
I fixture della galleria React e Preact includono il selettore completo e la composizione composta. Il posizionamento del portale, la geometria, lo scorrimento, la chiusura e lo stato attivo appartengono al Dropdown condiviso e all’integrazione del renderer. Il selettore non introduce un runtime del renderer separato.Props
string
obbligatorio
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
predefinito:"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[]
obbligatorio
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
predefinito:"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
predefinito:"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
predefinito:"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
obbligatorio
A Dropdown.Root with type=“picker”, its Trigger, Content and Options. Root shares prepared data and selection and renders no DOM node.
boolean
predefinito:"true"
Closes the composed Dropdown after an accepted selection. Defaults to true.
readonly PhoneCountryOption[]
obbligatorio
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
predefinito:"null"
Initial uncontrolled country identifier. Omit it or use null to start empty.
boolean
predefinito:"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
obbligatorio
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
predefinito:"0"
How long to wait before closing the popover that was opened on hover.
Specified in milliseconds.Requires the
openOnHover prop.number
predefinito:"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
predefinito:"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
predefinito:"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
predefinito:"No results"
Status message shown when no country label, identifier or calling code matches. Defaults to No results.
string
predefinito:"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
predefinito:"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.