الانتقال إلى المحتوى الرئيسي

نظرة عامة

يوفر CountrySelect منتقيًا كاملًا للبلدان مع مشغّل مُسمّى وأعلام للزينة وبحث وخيار عدم اختيار بلد. تعرض CountrySelect.Root وCountrySelect.Trigger وCountrySelect.Options التنفيذ نفسه للتركيب مع القائمة المنسدلة. يوفر تطبيقك بيانات البلدان والنصوص المترجمة ويحدد كيفية ربط المعرّفات المحددة بالقيم المخزنة.

استخدام

وفّر خيارات مُعدّة مع معرّفات نصية فريدة وثابتة وتسميات عرض. يُبلغ المنتقي عن المعرّفات دون تغيير، بغض النظر عن اللغة المعروضة. الأعلام عُقد React زخرفية اختيارية. يمكن للخيار تعيين disabled: true ليبقى مرئيًا من دون السماح بالتحديد.
يهيئ defaultValue التحديد غير المتحكم فيه. استخدم value وonValueChange للتحديد المتحكم فيه. يؤدي تحديث value خارجيًا إلى تحديث كل من المشغّل والخيار المحدد، بما في ذلك أثناء فتح النافذة المنبثقة.

الأجزاء المشتركة

يمتلك Root الخيارات المُعَدّة والمُعرّف المحدد. لا يضيف أي عنصر DOM. يقرأ Trigger ذلك التحديد ويعرض تسميته وعلمه. يقرأ Options البيانات نفسها ويُصيّر صفوفًا قابلة للبحث داخل Dropdown.SelectionGroup. يمتلك Dropdown الفتح وموضع النافذة المنبثقة والصفحات والتنقل والتركيز.
يجمع الاختصار هذه الأجزاء داخليًا. يشترك كلا الشكلين في التحديد والمسح وسلوك التعطيل ومطابقة البحث وعرض الخيار المحدد. القيمة الافتراضية لـ closeOnSelect هي true. عيّنها إلى false في الاختصار أو Options عندما يجب أن يبقي التحديد النافذة المنبثقة مفتوحة.

المسح والإلغاء

يمثل null عدم وجود بلد. يُبلغ تحديد صف عدم وجود بلد عن null؛ ويؤدي تمرير value={null} إلى مسح منتقٍ متحكم فيه. السلسلة الفارغة ('') مُعرّف خيار مُقدَّم صالح وتبقى مميزة عن null. يتلقى onValueChange المعرّف التالي أو null وتفاصيل حدث تحديد Dropdown: event وreason وtrigger وcancel وisCanceled. استدعِ details.cancel() قبل تحديث الحالة المتحكم فيها للحفاظ على التحديد الحالي وإبقاء النافذة المنبثقة مفتوحة. لا يؤدي التحديد المتكرر للمعرّف الحالي إلى إصدار تغيير آخر للقيمة. يعرض المعرّف غير الموجود في countries القيمة noCountryLabel وأيقونة عدم وجود بلد. لا يؤدي تصييره إلى إصدار تغيير أو استبدال قيمة المضيف. يقرر التطبيق كيفية التعامل مع القيم المخزنة غير الموجودة ضمن الخيارات الحالية.

البحث والتفاعل

يطابق البحث تسميات العرض المُعَدّة. يتجاهل حالة الأحرف والتشكيلات الاختيارية في النصوص اللاتينية واليونانية والعربية والعبرية، وعلامات النبر في السيريلية، ويعامل ё السيريلية كأنها е، ويحوّل أحرفًا مثل ø وæ وß إلى o وae وss. كما يتجاهل أحرف التشكيل المستقلة مثل ^ و` و´ و¨ وˇ، لذا لا يخفي مفتاح ميت معلّق المطابقات. تظل العلامات التي تكوّن أحرفًا مميزة مهمة، مثل علامات الجهر اليابانية وعلامات حروف العلة الهندية وй السيريلية. يطابق مقطع كوري مكتوب جزئيًا، مثل ㅎ أو 하، المقاطع التي تبدأ به، مثل 한. تشارك noCountryLabel في البحث نفسه. يعرض الاستعلام الذي لا يحتوي على خيارات مطابقة noResultsLabel. تنقل مفاتيح الأسهم وHome وEnd التركيز من دون تغيير المعرّف المحدد. يثبت Enter أو Space على خيار مُمكّن التحديد عبر مجموعة التحديد الخاصة به. يستخدم Escape والتفاعل الخارجي إغلاق Dropdown ومعالجة التركيز. لكل منتقٍ حالة تحديد ونافذة منبثقة مستقلة. لا يزال تنشيط بحث Dropdown وحماية IME يحتاجان إلى أعمال تكامل، وكذلك جلسات الصفحات الكسولة وسلوك الصفحات غير النشطة. يعيد كلا شكلي المنتقي ضبط بحثهما عند إعادة الفتح، بما في ذلك النوافذ المنبثقة التي تظل مركبة. لا يكتمل التنفيذ المشترك بينهما بعد دورة حياة الصفحات والتصفح في Dropdown. يمنع disabled في Root أو الاختصار الفتح والتحديد. يُعطّل أيضًا منتقٍ لا يتوفر له أي بلدان. إذا حدث أي من الشرطين أثناء فتح النافذة المنبثقة الخاصة به، يطلب المنتقي الإغلاق. يعيد الإغلاق التركيز إلى المشغّل. يجب أن تقبل المضيفات المتحكم فيها طلب الإغلاق هذا عبر onOpenChange؛ كما يمنع الاختصار النافذة المنبثقة أثناء التعطيل. بعد قبول طلب الإغلاق، لا تؤدي إعادة تمكين المنتقي إلى إعادة فتحه تلقائيًا. يبقى المشغّل قابلاً للتركيز ويعرض aria-disabled. تتجاوز المشغلات المعطلة معالجات تنشيط المستهلك. تتلقى الصيغ الدالية لـ className وstyle وrender القيمة disabled: true في حالة المشغّل.

التسميات والتخصيص

وفّر label مرئيًا، أو استخدم aria-label أو aria-labelledby على المشغّل. تكون للتسميات المُشار إليها الأولوية على aria-label غير الفارغ، الذي تكون له الأولوية على التسمية المرئية. مع أحد هذه الأسماء، يصف البلد المحدد المشغّل. وإلا فإن البلد المحدد يسميه. ترث النافذة المنبثقة اسم المشغّل ما لم تسمّها تسميات النافذة المنبثقة المملوكة للمستدعي أو عنوان Dropdown. يسمي الاختصار أيضًا مربع قائمة الخيارات الخاص به انطلاقًا من تسميات المشغّل تلك، ما لم توفر optionsProps اسم وصول خاصًا بها. في الاستخدام المركب، امنح Options قيمة aria-label أو aria-labelledby للحصول على اسم صريح لمربع القائمة. وإلا فإنه يشير إلى عنوان Dropdown المسجل أو محتوى المشغّل. يكشف تلميح أداة عن التسمية الكاملة المحددة عندما تكون مقتطعة. يوفر searchLabel العنصر النائب واسم الوصول لإدخال البحث، ويوفر noCountryLabel نص عدم اختيار بلد، ويوفر noResultsLabel نص النتيجة الفارغة. تكون قيمها الافتراضية Search وNo country وNo results. مرّر سلاسل مترجمة عندما يكون تطبيقك مترجمًا محليًا. يستبدل أبناء Trigger المخصصون عرض البلد المحدد؛ ويمتلك المستدعي ذلك المحتوى وعرضه القابل للوصول. تستهدف سمات المشغّل الأصلية ومعالجات الأحداث وclassName وstyle وref وrender زر المشغّل. تستهدف wrapperProps عنصر div المحيط الذي يحتوي أيضًا على التسمية المرئية. تستهدف الخصائص الأصلية لـ Options وref وrender عنصر div لمجموعة التحديد الخاصة به. تتلقى دالة render الخاصة به { value, multiple: false }، حيث تكون value هي معرّف البلد العام أو null، بدلًا من معرّف خيار داخلي. تستهدف searchProps إدخال البحث؛ وتظل قيمة البحث ومعالجة تغييره مملوكتين للمنتقي. يقبل الاختصار خصائص البحث نفسها مباشرةً وسمات المجموعة عبر optionsProps. مرّر الخصائص والمراجع المتوفرة عند استبدال عنصر عبر render.

تكامل المضيف والتخزين

يقبل الاختصار قيم Dropdown التالية: open وdefaultOpen وonOpenChange وonEscapeKeyDown وonInteractOutside وdefaultPage. يعيّن الاستخدام المركب هذه القيم على Dropdown.Root. يُبلغ onOpenChange حاليًا عن قيمة منطقية فقط، بما يتطابق مع العقد العام لـ Dropdown. لا تزال تفاصيل حدث الفتح وإلغاء الفتح العام غير متاحة في المصدر. يمكن لاستدعاءات الإغلاق عبر Escape ومن الخارج استدعاء event.preventDefault() لإبقاء النافذة المنبثقة مفتوحة. يقبل popupProps جميع خصائص Dropdown.Content باستثناء children، بما في ذلك سمات النافذة المنبثقة الأصلية وref وrender والتموضع ووجهة البوابة والأسماء القابلة للوصول وkeepMounted. في الاستخدام المركب، مررها مباشرةً إلى Dropdown.Content. احتفظ بمعرفات القائمة المنسدلة ومكدسات التركيز وبيانات الحقل واستمرارية البيانات ودورة حياة التحرير في محول المضيف. يستخدم محول الواجهة الأمامية لـ Twenty رموز بلدان مستقرة لمعرّفات المنتقي ويحوّل التحديدات الصريحة مجددًا إلى قيم أسماء البلدان المصدرية الحالية. تُعيّن السلسلة الفارغة المخزنة الخاصة به إلى null للمنتقي؛ وتظل القيم القديمة غير المتطابقة مخزنة إلى أن يغيرها تحديد صريح. لا تصبح تسميات العرض المترجمة أسماء بلدان مخزنة. ينبغي للتطبيقات ذات تنسيق تخزين آخر إجراء التحويل في المحول الخاص بها أيضًا. يبقى تقديم النموذج الأصلي وإعادة التعيين وrequired وreadOnly والتكامل مع Field لهذا المنتقي المخصص مؤجلاً.

عارض مكوّن الواجهة الأمامية

تتحقق تجهيزات مكونات الواجهة الأمامية لـ React وPreact من الفتح بالمؤشر والتصفية والتحديد عبر واجهات API المختصرة والمركبة، بما في ذلك القيم المتحكم فيها وغير المتحكم فيها، ومسح null وإعادة التحديد، والتغييرات الملغاة، والتحديثات الخارجية المتحكم فيها، والتفاعل المعطل، والتسميات المترجمة، والأعلام الزخرفية. كما تتحقق من خصائص ومراجع المشغّل الأصلي وإدخال البحث، بالإضافة إلى أهداف ومراجع تصيير المشغّل ومجموعة الخيارات. لا تزال مسائل تنشيط البحث بلوحة المفاتيح ومعالجة IME، ومدة جلسة الصفحة، وقبول البوابة والهندسة والتمرير والإغلاق الخارجي واستعادة التركيز في المصيّر الكامل مفتوحة.

الترحيل

استبدل قيمة الحارس السابقة للسلسلة الفارغة التي تعني عدم وجود بلد بـ null في القيم المتحكم فيها وحالة التحديد. السلسلة الفارغة ('') الآن معرّف خيار صالح، لذا لم تعد value="" تعني عدم وجود بلد. حافظ على استقرار كل CountryChoice.value؛ يمكن أن تظل معرّفات السلاسل الحالية دون تغيير ويمكن ترجمة تسميات العرض بشكل مستقل. حدّث معالجات onValueChange لقبول string | null. تتلقى دالة الاستدعاء الآن أيضًا eventDetails كوسيط ثانٍ، بما في ذلك cancel() لرفض تحديد. يمكن للمعالجات التي لا تحتاج إلى تفاصيل الحدث الاستمرار في استخدام الوسيط الأول فقط. إذا كان التخزين لديك يستخدم '' لعدم وجود بلد، فحوّله إلى null قبل تمريره إلى المنتقي، وحوّل null المُبلّغ عنه مجددًا إلى '' عند الاستمرار في التخزين. احتفظ بتحويل التوافق هذا في محول التطبيق، واحذفه عندما يكون '' معرّف خيار مقصودًا.

الخصائص

ReactNode
Custom trigger content. Replaces the selected country presentation while retaining shared trigger behavior.
string | ((state: PopoverTriggerState) => string | undefined)
Class applied to the trigger.
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 popup after a selection. Defaults to true. Cancelled selection keeps it open.
readonly CountryChoice[]
مطلوب
Prepared country choices with unique stable string values, caller-owned labels, and optional decorative flags and disabled states. An empty string is a valid choice value.
boolean
Whether the uncontrolled popup is initially open.
string
Dropdown page shown when the popup opens. Defaults to root.
string | null
Initial uncontrolled selected identifier. Defaults to null.
number
افتراضي:"300"
How long to wait before the popover may be opened on hover. Specified in milliseconds.Requires the openOnHover prop.
boolean
Prevents opening and selection while the trigger stays focusable. An empty country list is also disabled.
string
ID of the trigger. Generated when omitted.
string
Optional visible label that names the trigger.
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>).
string
Text of the no-country choice, also displayed when no country is selected.
string
Text displayed when no choice matches the search.
((event: DropdownDismissEvent) => void)
Called before Escape dismisses the popup. Call event.preventDefault() to keep it open.
((event: DropdownDismissEvent) => void)
Called before outside interaction or Tab dismisses the popup. Call event.preventDefault() to keep it open.
((open: boolean) => void)
Reports popup opening and closing with the next boolean state, matching Dropdown.Root.
((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)
Reports the selected identifier or null with cancellable event details. Call details.cancel() to preserve selection and keep the popup open.
boolean
Controls whether the country popup is open.
boolean
افتراضي:"false"
Whether the popover should also open when the trigger is hovered.
Omit<CountrySelectOptionsProps, "closeOnSelect" | "searchLabel" | "noResultsLabel" | "searchProps">
Native props, ref, and render for the selection group div rendered by CountrySelect.Options.
Omit<DropdownContentProps, "children">
Dropdown.Content props, including native popup attributes, ref, render, positioning, portal destination, and keepMounted. Explicit popup accessible names override the trigger name. Children are owned by the picker.
Ref<HTMLButtonElement>
Ref to the trigger element.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>
Replaces the trigger element while preserving its behavior and props.
string
Placeholder and accessible name of the search input.
Omit<DropdownSearchProps, "defaultValue" | "value" | "onValueChange">
Native search input props, ref, and render. Search value and change handling are owned by the picker.
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 selected identifier. Null selects no country; undefined leaves selection uncontrolled.
Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "children">
Native props and ref for the div around the trigger and its visible label. Children are owned by the picker.

CountrySelect.Root

ReactNode
مطلوب
Picker composition containing Dropdown.Root, CountrySelect.Trigger, and CountrySelect.Options. Root adds no DOM element.
readonly CountryChoice[]
مطلوب
Prepared country choices with unique stable string values, caller-owned labels, and optional decorative flags and disabled states. An empty string is a valid choice value.
string | null
افتراضي:"null"
Initial uncontrolled selected identifier. Defaults to null.
boolean
افتراضي:"false"
Prevents opening and selection. An empty country list is also disabled. The trigger stays focusable with aria-disabled.
string
افتراضي:"No country"
Text for the null selection and its option. Defaults to No country.
((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void)
Reports the selected identifier or null with event, reason, trigger, cancel and isCanceled details. Call cancel() to preserve selection and keep the popup open.
string | null
Controlled selected identifier. Null selects no country; undefined leaves selection uncontrolled.

CountrySelect.Trigger

ReactNode
Custom trigger content. Replaces the selected country presentation while retaining shared trigger behavior.
string | ((state: PopoverTriggerState) => string | undefined)
Class applied to the trigger button.
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.
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).
string
Optional visible label that names the trigger.
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 element.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>
Replaces the trigger element. Custom components must forward the supplied props and ref.
CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "children">
Native props and ref for the div around the trigger and its visible label. Children are owned by the picker.

CountrySelect.Options

string
Accessible name for the selection listbox. Overrides its default name.
string
Accessible name references for the selection listbox. Defaults to the registered Dropdown title or trigger element.
string
Class applied to the selection group div.
boolean
Closes the popup after a selection. Defaults to true. Cancelled selection keeps it open.
string
Text displayed when no choice matches the search. Defaults to No results.
Ref<HTMLDivElement>
Ref to the selection group element.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CountrySelectOptionsState>
Replaces the selection group div. Functions receive supplied props and { value, multiple: false } state, with the public string or null selection. Custom components must forward the supplied props and ref.
string
Search placeholder and accessible name. Defaults to Search.
Omit<DropdownSearchProps, "defaultValue" | "value" | "onValueChange">
Native search input props, ref, and render. Search value and change handling are owned by the picker.