Resumen
PhoneCountryPicker combina un activador de bandera de país, una ventana emergente, búsqueda y opciones de códigos de llamada. Use el componente completo para la selección habitual, o componga Root, Trigger y Options con Dropdown cuando necesite una ventana emergente personalizada. Ambas formas comparten los mismos países preparados y la selección.
”Uso”
Proporcione sus propios datos de países y un nombre accesible para el activador. Usevalue con onValueChange para la selección controlada, o defaultValue para la selección no controlada. null representa que no hay ningún país seleccionado.
PhoneCountryOption tiene un value único y estable, una label de país localizada, un callingCode de solo dígitos sin el signo más inicial y un nodo flag decorativo. También puede estar disabled. Los valores son identificadores propiedad del llamador, como los códigos de país ISO, y se devuelven sin cambios. Las etiquetas, las banderas y los códigos de llamada son datos de presentación y no se convierten en el identificador seleccionado.
El selector añade el signo más y aísla los códigos de llamada de izquierda a derecha en las filas de opciones y en las descripciones emergentes de desbordamiento, incluso en interfaces de derecha a izquierda. Proporcione los países en el orden en que desea mostrarlos. El país seleccionado aparece primero mientras coincide con la consulta; las coincidencias restantes conservan el orden proporcionado.
Composición compuesta
Este es un cambio incompatible de la API para los llamadores compuestos existentes. AñadaPhoneCountryPicker.Root alrededor de Dropdown.Root, mueva countries, value y onValueChange de Options a Root, y elimine Trigger.country. Ahora ambas partes requieren Root y derivan de él el país seleccionado.
Root gestiona los países y la selección controlada o no controlada. Coloque el Dropdown.Root compartido dentro de él y componga el activador, el contenido y las opciones. Trigger deriva su bandera seleccionada y su descripción accesible de Root; Options lee los mismos datos y selección. No proporcione otro país ni valor seleccionado a esas partes.
dropdownProps y contentProps en el selector completo, o configure las partes de Dropdown directamente en el uso compuesto.
Búsqueda y selección
La búsqueda encuentra subcadenas de las etiquetas de país proporcionadas, los identificadores estables y los códigos de llamada. Las etiquetas y los identificadores usan la normalización compartidanormalizeSearchText: texto en minúsculas, descomposición Unicode NFD y manejo de acentos según la escritura. Por ejemplo, reunion coincide con Réunion y gb coincide con un identificador GB. Las distinciones significativas en las escrituras se conservan según ese auxiliar. Se recortan los espacios en blanco alrededor de la consulta; se conservan los espacios en blanco internos. Para la búsqueda de códigos de llamada, un signo más inicial es opcional, por lo que 44, +44 y " +44 " coinciden con el código de llamada proporcionado 44. La búsqueda no analiza un número de teléfono completo ni infiere un país a partir de él.
onValueChange(value, eventDetails) recibe el identificador solicitado y los detalles compartidos de Dropdown.SelectionGroup: reason, el event nativo, el trigger de la opción seleccionada, cancel() e isCanceled. Llame a cancel() antes de actualizar el estado controlado para rechazar la solicitud. Una solicitud cancelada conserva la selección no controlada y deja abierta la ventana emergente. Establezca closeOnSelect={false} para mantenerla abierta después de una selección aceptada. Los cambios de selección no modifican ningún valor de entrada telefónica.
Establezca disabled en el selector completo o en Root para deshabilitar su activador, búsqueda y selección. Un país deshabilitado permanece visible y no se puede seleccionar. Trigger.disabled y Options.disabled también pueden deshabilitar esas partes individuales.
Destinos y etiquetas nativos
Los atributos nativos, controladores de eventos,className, style, ref, render y children opcionales del selector completo se aplican a su activador. children reemplaza la bandera o el icono de mundo predeterminados y el chevrón. contentProps se aplica a Dropdown.Content; optionsProps se aplica al div raíz de las opciones y proporciona searchLabel, listLabel y emptyLabel. En el uso compuesto, las props nativas, las refs y la composición de renderizado se aplican al botón Trigger o al div Options correspondiente. Root no renderiza ningún nodo DOM.
Proporcione etiquetas de país localizadas y el aria-label obligatorio del activador. La etiqueta del país seleccionado describe el activador, mientras que su bandera y chevrón son decorativos. Una selección vacía muestra un icono de mundo. La ventana emergente toma el nombre del activador, a menos que la nombre un Dropdown.Title o una etiqueta de contenido explícita. searchLabel tiene como valor predeterminado Search y nombra tanto el campo de búsqueda como su marcador de posición. listLabel usa de forma predeterminada Countries y nombra el cuadro de lista de forma independiente. emptyLabel tiene como valor predeterminado No results.
Integración de entrada telefónica
El selector se distribuye sin un catálogo de países, un paquete de recursos de banderas ni un tiempo de ejecución de entrada telefónica. El adaptador de frontend gestiona el análisis, la validación, el formato, los borradores de edición y la persistencia del teléfono. Asigne el país seleccionado de la biblioteca telefónica aRoot.value o al value del selector completo, y asigne los cambios de país de vuelta mediante una devolución de llamada. Mantenga el texto telefónico en su propietario existente al cambiar o borrar un país, o al aplicar una actualización externa del país seleccionado.
Se aplazan el envío y restablecimiento nativos de formularios, la integración de requerido, solo lectura y Field para este selector personalizado. El selector completo reenvía los atributos nativos del activador según el contrato del botón Dropdown.
Renderizador de componentes frontales
Los ejemplos de la galería de React y Preact incluyen el selector completo y la composición compuesta. La ubicación del portal, la geometría, el desplazamiento, el descarte y el foco pertenecen al Dropdown compartido y a la integración del renderizador. El selector no introduce un tiempo de ejecución de renderizador independiente.”Props”
string
requerido
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
predeterminado:"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[]
requerido
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
predeterminado:"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
predeterminado:"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
predeterminado:"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
requerido
A Dropdown.Root with type=“picker”, its Trigger, Content and Options. Root shares prepared data and selection and renders no DOM node.
boolean
predeterminado:"true"
Closes the composed Dropdown after an accepted selection. Defaults to true.
readonly PhoneCountryOption[]
requerido
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
predeterminado:"null"
Initial uncontrolled country identifier. Omit it or use null to start empty.
boolean
predeterminado:"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
requerido
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
predeterminado:"0"
How long to wait before closing the popover that was opened on hover.
Specified in milliseconds.Requires the
openOnHover prop.number
predeterminado:"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
predeterminado:"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
predeterminado:"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
predeterminado:"No results"
Status message shown when no country label, identifier or calling code matches. Defaults to No results.
string
predeterminado:"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
predeterminado:"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.