نظرة عامة
يجمعPhoneCountryPicker بين مشغّل علم البلد ونافذة منبثقة وخيارات البحث ورمز الاتصال. استخدم المكوّن الكامل للاختيار العادي، أو ركّب Root وTrigger وOptions مع Dropdown عندما تحتاج إلى نافذة منبثقة مخصّصة. يشترك الشكلان في البلدان المُعَدّة نفسها والاختيار نفسه.
استخدام
وفّر بيانات بلدك الخاصة واسمًا متاحًا للمشغّل. استخدمvalue مع onValueChange للاختيار المتحكَّم به، أو defaultValue للاختيار غير المتحكَّم به. تمثّل null عدم اختيار أي بلد.
PhoneCountryOption على value فريد وثابت، وlabel محلي للبلد، وcallingCode مؤلف من أرقام فقط من دون علامة الجمع البادئة، وعقدة flag زخرفية. قد يكون أيضًا disabled. القيم هي معرّفات يملكها المستدعي، مثل رموز بلدان ISO، وتُعاد دون تغيير. التسميات والأعلام ورموز الاتصال هي بيانات عرض ولا تصبح المعرّف المحدد.
يضيف المنتقي علامة الجمع ويعزل رموز الاتصال من اليسار إلى اليمين في صفوف الخيارات وتلميحات الأدوات الفائضة، بما في ذلك الواجهات من اليمين إلى اليسار. وفّر البلدان بالترتيب الذي تريد عرضه. يظهر البلد المحدد أولًا ما دام يطابق الاستعلام؛ وتحتفظ التطابقات المتبقية بالترتيب الذي وفّرته.
التركيب المركب
هذا تغيير واجهة برمجة تطبيقات غير متوافق مع الإصدارات السابقة للمستدعين المركبين الحاليين. أضفPhoneCountryPicker.Root حول Dropdown.Root، وانقل countries وvalue وonValueChange من Options إلى Root، وأزل Trigger.country. يتطلب الجزآن الآن Root ويستمدان البلد المحدد منه.
يملك Root البلدان والاختيار المتحكَّم به أو غير المتحكَّم به. ضع Dropdown.Root المشترك داخله وركّب المشغّل والمحتوى والخيارات. يستمد Trigger علمه المحدد ووصفه المتاح من Root؛ ويقرأ Options البيانات والاختيار نفسيهما. لا توفّر بلدًا آخر أو قيمة محددة إلى تلك الأجزاء.
dropdownProps وcontentProps في المنتقي الكامل، أو هيّئ أجزاء Dropdown مباشرةً في الاستخدام المركب.
البحث والاختيار
يطابق البحث السلاسل الفرعية لتسميات البلدان الموفّرة والمعرّفات الثابتة ورموز الاتصال. تستخدم التسميات والمعرّفات تسويةnormalizeSearchText المشتركة: نص بأحرف صغيرة، وتحليل Unicode NFD، ومعالجة اللكنات المراعية للنص. على سبيل المثال، يطابق reunion القيمة Réunion ويطابق gb معرّف GB. تُحفظ الفروق ذات المعنى في النصوص وفقًا لتلك الدالة المساعدة. تُزال المسافات البيضاء المحيطة بالاستعلام؛ وتُحفظ المسافات البيضاء الداخلية. للبحث برمز الاتصال، تكون علامة جمع واحدة بادئة اختيارية، لذا تطابق 44 و+44 و" +44 " رمز الاتصال الموفّر 44. لا يحلل البحث رقم هاتف كاملًا ولا يستنتج بلدًا منه.
يتلقى onValueChange(value, eventDetails) المعرّف المطلوب وتفاصيل Dropdown.SelectionGroup المشتركة: reason وevent الأصلي وtrigger للخيار المحدد وcancel() وisCanceled. استدعِ cancel() قبل تحديث الحالة المتحكَّم بها لرفض الطلب. يحافظ الطلب الملغى على الاختيار غير المتحكَّم به ويترك النافذة المنبثقة مفتوحة. اضبط closeOnSelect={false} لإبقائها مفتوحة بعد اختيار مقبول. لا تعدّل تغييرات الاختيار أي قيمة لإدخال الهاتف.
اضبط disabled على المنتقي الكامل أو Root لتعطيل مشغّله وبحثه واختياره. يبقى البلد المعطل مرئيًا ولا يمكن اختياره. يمكن لـ Trigger.disabled وOptions.disabled أيضًا تعطيل هذين الجزأين على حدة.
الأهداف والتسميات الأصلية
تستهدف السمات الأصلية للمنتقي الكامل ومعالجات الأحداث وclassName وstyle وref وrender وchildren الاختياري مشغّله. يستبدل children العلم الافتراضي أو أيقونة العالم والشيفرون. يستهدف contentProps Dropdown.Content؛ ويستهدف optionsProps عنصر div الجذر للخيارات ويوفّر searchLabel وlistLabel وemptyLabel. في الاستخدام المركب، تستهدف الخصائص الأصلية والمراجع وتركيب العرض زر Trigger أو عنصر div الخاص بـ Options المقابل. لا يعرض Root أي عقدة DOM.
وفّر تسميات محلية للبلدان وaria-label المطلوب للمشغّل. تصف تسمية البلد المحدد المشغّل، بينما علمه والشيفرون زخرفيان. يعرض الاختيار الفارغ أيقونة عالم. تأخذ النافذة المنبثقة اسم المشغّل ما لم يسمّها Dropdown.Title أو تسمية محتوى صريحة. القيمة الافتراضية لـsearchLabel هي Search، وهي تسمّي حقل البحث وعنصره النائب كليهما. تكون القيمة الافتراضية لـ listLabel هي Countries وتسمّي مربع القائمة بشكل مستقل. القيمة الافتراضية لـemptyLabel هي No results.
تكامل إدخال الهاتف
يأتي المنتقي دون كتالوج للبلدان أو حزمة أصول للأعلام أو وقت تشغيل لإدخال الهاتف. يمتلك محوّل الواجهة الأمامية تحليل الهاتف والتحقق من صحته وتنسيقه ومسودات التحرير والاستمرارية. اربط البلد المحدد في مكتبة الهاتف بـRoot.value أو value للمنتقي الكامل، واربط تغييرات البلد مرة أخرى عبر دالة رد واحدة. احتفظ بنص الهاتف في مالكه الحالي عند تغيير بلد أو مسحه، أو عند تطبيق تحديث خارجي للبلد المحدد.
يُؤجَّل تقديم النموذج الأصلي وإعادة التعيين وrequired والقراءة فقط وتكامل Field لهذا المنتقي المخصص. يمرر المنتقي الكامل سمات المشغّل الأصلية وفقًا لعقد زر Dropdown.
عارض مكوّن الواجهة الأمامية
تتضمن تجهيزات معرض React وPreact المنتقي الكامل والتركيب المركب. ينتمي موضع البوابة والهندسة والتمرير والرفض والتركيز إلى Dropdown المشترك وتكامل العارض. لا يقدّم المنتقي وقت تشغيل منفصلًا للعارض.الخصائص
string
مطلوب
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
افتراضي:"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[]
مطلوب
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
افتراضي:"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
افتراضي:"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
افتراضي:"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
مطلوب
A Dropdown.Root with type=“picker”, its Trigger, Content and Options. Root shares prepared data and selection and renders no DOM node.
boolean
افتراضي:"true"
Closes the composed Dropdown after an accepted selection. Defaults to true.
readonly PhoneCountryOption[]
مطلوب
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
افتراضي:"null"
Initial uncontrolled country identifier. Omit it or use null to start empty.
boolean
افتراضي:"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
مطلوب
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
افتراضي:"0"
How long to wait before closing the popover that was opened on hover.
Specified in milliseconds.Requires the
openOnHover prop.number
افتراضي:"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
افتراضي:"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
افتراضي:"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
افتراضي:"No results"
Status message shown when no country label, identifier or calling code matches. Defaults to No results.
string
افتراضي:"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
افتراضي:"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.