> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OverflowingList

> احتوِ صفًا من العناصر ضمن المساحة المتاحة واعرض القائمة الكاملة في نافذة منبثقة.

## نظرة عامة

يقيس `OverflowingList` عرضه المتاح، ويُبقي العناصر الملائمة في صف مضغوط، ويوفر زر `+N` يفتح القائمة الكاملة في نافذة منبثقة. يتم تحديث العدد عند تغيّر الحاوية أو محتوى العنصر أو القائمة المرتبة. لا تحتوي القوائم الفارغة والقوائم الملائمة على زر تجاوز أو نافذة منبثقة ظاهرة.

**Light**

[مثال على قائمة متجاوزة (light)](https://storybook.twenty.com/iframe.html?id=ui-components-overflowinglist--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مثال على قائمة متجاوزة (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-overflowinglist--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-overflowinglist--display)

وفّر القائمة المرتبة الكاملة كعناصر ذات مفاتيح. يتولى تطبيقك محتوى كل عنصر وإجراءاته وبياناته. يبقى الصف المضغوط مرئيًا عند فتح النافذة المنبثقة. تكرر النافذة المنبثقة القائمة الكاملة، بما في ذلك العناصر التي تتسع في الصف.

## استخدام

```tsx theme={null}
import { OverflowingList, Section } from 'twenty-ui/components/layout';
import { Tag } from 'twenty-ui/primitives/data-display';

const TAGS = ['Customer', 'Partner', 'Priority', 'Renewal'];

export const CompanyTags = () => (
  <Section.Root>
    <Section.Header
      title="Company tags"
      description="Open the count to see all tags."
    />
    <OverflowingList
      style={{ width: 180 }}
      showOverflowCount
      overflowLabel="Show all company tags"
    >
      {TAGS.map((label) => (
        <Tag
          key={label}
          color="blue"
          truncate={false}
          style={{ width: 80, minWidth: 'fit-content' }}
        >
          {label}
        </Tag>
      ))}
    </OverflowingList>
  </Section.Root>
);
```

## رؤية العدد

| `showOverflowCount` | السلوك عند تجاوز العناصر للسعة |
| - | - |
| محذوف | يعرض العدد عند تمرير المؤشر أو تركيز لوحة المفاتيح أو أثناء فتح النافذة المنبثقة. |
| `true` | يبقي العدد مرئيًا. |
| `خاطئ` | يخفي العدد ويقتطع الصف. تبقى النافذة المنبثقة المفتوحة مفتوحة إلى أن يتم إغلاقها. |

يبقي الوضع الافتراضي رؤية العدد الحالية أثناء تركيز عنصر مضمن، بحيث لا يؤدي إظهار العدد إلى دفع ذلك العنصر خارج الصف. يؤدي تركيز زر العدد إلى جعل العدد مرئيًا.

استخدم `false` عندما توفر الواجهة المحيطة طريقة أخرى للوصول إلى العناصر المخفية. يؤدي تغييره إلى `false` إلى إخفاء العدد من دون إغلاق نافذة منبثقة مفتوحة بالفعل. يمكن لـ `open` و`defaultOpen` مع ذلك إظهار القائمة الكاملة عند تجاوز العناصر للسعة. تؤدي إزالة العناصر الزائدة أو توسيع القائمة حتى تتسع لكل العناصر إلى إغلاق النافذة المنبثقة وإزالة زر العدد. يصف العدد دائمًا العناصر خارج الصف المضغوط.

يحدد `maxInlineCount` الحد الأقصى لعدد عناصر الصف المرئية. يمكن للعرض المتاح أن يقلل هذا العدد أكثر. تظل النافذة المنبثقة تحتوي على القائمة الكاملة. لا يجلب العناصر المفقودة ولا يستخدم المحاكاة الافتراضية للنافذة المنبثقة.

## حالة النافذة المنبثقة

تمتلك القائمة حالة نافذتها المنبثقة عندما يتم حذف `open`. استخدم `defaultOpen` لحالتها الأولية. القيمة الافتراضية هي `false`؛ وما زالت النافذة المنبثقة المفتوحة في البداية تتطلب عناصر زائدة.

مرر `open` وحدّثه في `onOpenChange` لامتلاك حالة النافذة المنبثقة. تتلقى دالة الاستدعاء القيمة المنطقية المطلوبة وتفاصيل حدث [Popover](https://docs.twenty.com/ar/ui/primitives/surfaces/popover.md) المثبّتة، بما في ذلك `reason` و`event` و`trigger` و`cancel()` و`preventUnmountOnClose()`. يمنع استدعاء `cancel()` تغيير الحالة المطلوب. في الاستخدام المتحكم به، حدّث حالتك للتغييرات التي تقبلها فقط.

مرر `actionsRef` لتلقي طريقتي `close()` و`unmount()` الخاصتين بـ Popover. تطلب `close()` الإغلاق عبر `onOpenChange` وتحترم الإلغاء. إذا كانت دالة الاستدعاء لديك تستدعي `preventUnmountOnClose()` لتشغيل خروج يملكه المستدعي، فاستدعِ `actionsRef.current?.unmount()` عند انتهاء ذلك الخروج. يحرر هذا النافذة المنبثقة المحتفَظ بها من دون إزالة القائمة ويسمح بفتحها مجددًا.

```tsx theme={null}
import { useState } from 'react';
import { OverflowingList } from 'twenty-ui/components/layout';
import { Tag } from 'twenty-ui/primitives/data-display';
import { Button } from 'twenty-ui/primitives/input';

const TEAMS = ['Design', 'Engineering', 'Support', 'Operations'];

export const ControlledTeamList = () => {
  const [open, setOpen] = useState(false);

  return (
    <OverflowingList
      open={open}
      onOpenChange={setOpen}
      showOverflowCount
      overflowLabel="Show all teams"
      style={{ width: 220 }}
      triggerProps={{ render: <Button variant="outline" size="sm" /> }}
    >
      {TEAMS.map((team) => (
        <Tag key={team} color="blue">
          {team}
        </Tag>
      ))}
    </OverflowingList>
  );
};
```

**Light**

[حالة متحكم بها مع مشغّل مخصص (light)](https://storybook.twenty.com/iframe.html?id=ui-components-overflowinglist--controlled\&viewMode=story\&globals=colorScheme:light)

**Dark**

[حالة متحكم بها مع مشغّل مخصص (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-overflowinglist--controlled\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-overflowinglist--controlled)

## الأهداف الأصلية والتركيب

تستهدف سمات `div` الأصلية والمعالجات والأنماط وأسماء الفئات والمراجع على `OverflowingList` جذر الصف المضغوط. استخدم `triggerProps` لزر العدد و`popupProps` لعنصر div لمحتوى النافذة المنبثقة. يحتفظ كلاهما بالخصائص الأصلية والمعالجات والمرجع وتركيب `render` للعنصر/الدالة لجزء Popover الخاص به.

خصص المشغّل باستخدام `triggerProps.render`، كما في المثال المتحكم به، أو وفّر `triggerProps.children` لاستبدال `+N`. يجب أن [تمرر المكونات المخصصة الخصائص والمرجع الموفّرين](https://docs.twenty.com/ar/ui/primitives/overview#custom-components). يجب أن تعرض مكونات النوافذ المنبثقة المخصصة أيضًا العناصر الفرعية الموفرة؛ إذ يمتلك 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` عندما ينبغي للواجهة المحيطة تلقي ذلك الحدث.

## الخصائص

**actionsRef** `RefObject\<PopoverRootActions | null\>`

Ref exposing the Popover close() and unmount() methods. After preventUnmountOnClose(), call unmount() when the caller-owned exit finishes.

**children** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\>[]` *required*

Complete ordered list of elements, each with a stable key. The popup contains the complete list, including items visible in the compact row.

**defaultOpen** `boolean` (default: false)

Initial popup visibility when uncontrolled. Defaults to false.

**maxInlineCount** `number`

Maximum number of items visible in the compact row. Available width can reduce this count further. The popup still contains the complete list.

**onOpenChange** `((open: boolean, eventDetails: PopoverRootChangeEventDetails) =\> void)`

Receives the requested open state and unchanged Base UI event details, including reason, event, trigger, cancel() and preventUnmountOnClose().

**open** `boolean`

Controlled popup visibility. A popup can appear only when items overflow.

**overflowLabel** `string` (default: 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.

**popupProps** `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** `Ref\<HTMLDivElement\>`

Ref forwarded to the compact row root div.

**showOverflowCount** `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.

**triggerProps** `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.