نظرة عامة
يقيسOverflowingList عرضه المتاح، ويُبقي العناصر الملائمة في صف مضغوط، ويوفر زر +N يفتح القائمة الكاملة في نافذة منبثقة. يتم تحديث العدد عند تغيّر الحاوية أو محتوى العنصر أو القائمة المرتبة. لا تحتوي القوائم الفارغة والقوائم الملائمة على زر تجاوز أو نافذة منبثقة ظاهرة.
وفّر القائمة المرتبة الكاملة كعناصر ذات مفاتيح. يتولى تطبيقك محتوى كل عنصر وإجراءاته وبياناته. يبقى الصف المضغوط مرئيًا عند فتح النافذة المنبثقة. تكرر النافذة المنبثقة القائمة الكاملة، بما في ذلك العناصر التي تتسع في الصف.
استخدام
رؤية العدد
يبقي الوضع الافتراضي رؤية العدد الحالية أثناء تركيز عنصر مضمن، بحيث لا يؤدي إظهار العدد إلى دفع ذلك العنصر خارج الصف. يؤدي تركيز زر العدد إلى جعل العدد مرئيًا.
استخدم
false عندما توفر الواجهة المحيطة طريقة أخرى للوصول إلى العناصر المخفية. يؤدي تغييره إلى false إلى إخفاء العدد من دون إغلاق نافذة منبثقة مفتوحة بالفعل. يمكن لـ open وdefaultOpen مع ذلك إظهار القائمة الكاملة عند تجاوز العناصر للسعة. تؤدي إزالة العناصر الزائدة أو توسيع القائمة حتى تتسع لكل العناصر إلى إغلاق النافذة المنبثقة وإزالة زر العدد. يصف العدد دائمًا العناصر خارج الصف المضغوط.
يحدد maxInlineCount الحد الأقصى لعدد عناصر الصف المرئية. يمكن للعرض المتاح أن يقلل هذا العدد أكثر. تظل النافذة المنبثقة تحتوي على القائمة الكاملة. لا يجلب العناصر المفقودة ولا يستخدم المحاكاة الافتراضية للنافذة المنبثقة.
حالة النافذة المنبثقة
تمتلك القائمة حالة نافذتها المنبثقة عندما يتم حذفopen. استخدم defaultOpen لحالتها الأولية. القيمة الافتراضية هي false؛ وما زالت النافذة المنبثقة المفتوحة في البداية تتطلب عناصر زائدة.
مرر open وحدّثه في onOpenChange لامتلاك حالة النافذة المنبثقة. تتلقى دالة الاستدعاء القيمة المنطقية المطلوبة وتفاصيل حدث Popover المثبّتة، بما في ذلك reason وevent وtrigger وcancel() وpreventUnmountOnClose(). يمنع استدعاء cancel() تغيير الحالة المطلوب. في الاستخدام المتحكم به، حدّث حالتك للتغييرات التي تقبلها فقط.
مرر actionsRef لتلقي طريقتي close() وunmount() الخاصتين بـ Popover. تطلب close() الإغلاق عبر onOpenChange وتحترم الإلغاء. إذا كانت دالة الاستدعاء لديك تستدعي preventUnmountOnClose() لتشغيل خروج يملكه المستدعي، فاستدعِ actionsRef.current?.unmount() عند انتهاء ذلك الخروج. يحرر هذا النافذة المنبثقة المحتفَظ بها من دون إزالة القائمة ويسمح بفتحها مجددًا.
الأهداف الأصلية والتركيب
تستهدف سماتdiv الأصلية والمعالجات والأنماط وأسماء الفئات والمراجع على OverflowingList جذر الصف المضغوط. استخدم triggerProps لزر العدد وpopupProps لعنصر div لمحتوى النافذة المنبثقة. يحتفظ كلاهما بالخصائص الأصلية والمعالجات والمرجع وتركيب render للعنصر/الدالة لجزء Popover الخاص به.
خصص المشغّل باستخدام triggerProps.render، كما في المثال المتحكم به، أو وفّر triggerProps.children لاستبدال +N. يجب أن تمرر المكونات المخصصة الخصائص والمرجع الموفّرين. يجب أن تعرض مكونات النوافذ المنبثقة المخصصة أيضًا العناصر الفرعية الموفرة؛ إذ يمتلك OverflowingList محتوى العنصر. القيمة الافتراضية لـ overflowLabel هي “إظهار كل العناصر”. يجمع الاسم المتاح للزر الافتراضي بين عدده وذلك التصنيف، على سبيل المثال “+3 إظهار كل الفرق”. تجاوز triggerProps['aria-label'] أو popupProps['aria-label'] عندما يحتاج محتواهما إلى اسم مختلف.
يوقف OverflowingList انتشار click وmousedown وpointerdown وkeydown وkeyup على المشغّل والنافذة المنبثقة افتراضيًا. يمنع هذا فتح النافذة المنبثقة والتفاعل مع عناصرها من تنشيط حقل أو منتقي محيط. يستبدل معالج مقدَّم عبر triggerProps أو popupProps الإعداد الافتراضي لذلك الحدث. استدعِ event.stopPropagation() في معالجك للاحتفاظ بالمنع، أو احذفه للسماح لذلك الحدث بالانتشار. تحتفظ الأحداث الأخرى بإعداداتها الافتراضية. تُركّب المعالجات على عنصر render مخصص مع الخصائص الموفرة كالمعتاد.
عندما يسمح تجاوز نقرة النافذة المنبثقة بالانتشار، يمكن لبوابة Base UI المثبّتة إرسال تلك النقرة إلى سلف React محيط مرتين بالحدث الأصلي نفسه. يحدث هذا أيضًا مع Popover عادي. يحافظ OverflowingList على هذا السلوك السابق؛ ولا يضمن استدعاءً واحدًا للسلف لكل حدث أصلي للنافذة المنبثقة عند تمكين الانتشار.
لوحة المفاتيح والتركيز
يفتح Enter وSpace والتنشيط بالمؤشر نافذة منبثقة غير مشروطة. يؤدي Escape والتفاعل الخارجي إلى إغلاقها. يستعيد الإغلاق العادي التركيز إلى زر العدد. يتم الاحتفاظ بالتركيز الموجود مسبقًا على عنصر مضمن مرئي أو عنصر تحكم خارجي. تدعم النافذة المنبثقة المحتوى والروابط والأزرار بسلوك لوحة المفاتيح الأصلي الخاص بها؛ ولا تحولها إلى عناصر قائمة أو تضيف تنقلًا بأسهم القائمة. استخدمpopupProps.initialFocus وpopupProps.finalFocus لتخصيص التركيز عند الفتح والإغلاق عبر عقد Popover المثبّت.
تمتلك كل قائمة قياساتها المتجاوبة بشكل مستقل. تؤدي إزالة تحميل إحدى القوائم إلى تحرير مراقباتها وإبقاء القوائم الأخرى عاملة.
العرض من الخادم والإماهة
تتضمن ترميزات الخادم أول عناصرmaxInlineCount، أو كل العناصر عند حذف الحد الأقصى. يصبح قياس العرض ومحتوى النافذة المنبثقة متاحين بعد التركيب على العميل.
تعيد الإماهة استخدام الصف المؤقت وتطبق القياس المتجاوب بعد التركيب على العميل. العناصر الفرعية للصف والنافذة المنبثقة هي مثيلات معروضة منفصلة. احتفظ بالحالة مشتركة بين هذين الموضعين في المستدعي.
الترحيل
تستمر النافذة المنبثقة في عرض القائمة الكاملة وتستخدم “إظهار كل العناصر” افتراضيًا. يحافظshowOverflowCount={false} على الصف المقتطع ويخفي العدد. لا يؤدي إلى إغلاق نافذة منبثقة مفتوحة بالفعل. يحتفظ المشغّل والنافذة المنبثقة بمنعهما الافتراضي للنقر وmousedown وpointerdown وkeydown وkeyup. تجاوز معالجًا فرديًا عبر triggerProps أو popupProps عندما ينبغي للواجهة المحيطة تلقي ذلك الحدث.
الخصائص
RefObject<PopoverRootActions | null>
Ref exposing the Popover close() and unmount() methods. After preventUnmountOnClose(), call unmount() when the caller-owned exit finishes.
ReactElement<unknown, string | JSXElementConstructor<any>>[]
مطلوب
Complete ordered list of elements, each with a stable key. The popup contains the complete list, including items visible in the compact row.
boolean
افتراضي:"false"
Initial popup visibility when uncontrolled. Defaults to false.
number
Maximum number of items visible in the compact row. Available width can reduce this count further. The popup still contains the complete list.
((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)
Receives the requested open state and unchanged Base UI event details, including reason, event, trigger, cancel() and preventUnmountOnClose().
boolean
Controlled popup visibility. A popup can appear only when items overflow.
string
افتراضي:"Show all items"
Accessible label for the popup. The default overflow button is named by its visible count followed by this label. Defaults to Show all items.
Omit<PopoverPopupProps, "children">
Popover.Popup native props, handlers, ref, render composition and focus options for the overflow content. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default.
Ref<HTMLDivElement>
Ref forwarded to the compact row root div.
boolean
Shows the count on hover, keyboard focus or while open by default. Use true to keep it visible whenever items overflow, or false to hide the count and clip the row. An already-open popup stays open until dismissed. Empty lists and lists that fit have no trigger.
Omit<
ComponentPropsWithRef<typeof Popover.Trigger>,
'handle' | 'payload' | 'ref'
> & { ref?: Ref<HTMLElement> }
Popover.Trigger native props, handlers, ref, children and render composition for the count button. Click, mousedown, pointerdown, keydown and keyup stop propagation by default. Each supplied event handler replaces its default. Custom components must forward supplied props and ref.