溢出列表 · OverflowList
溢出列表用于表格与列表场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。
安装与前置条件
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。
示例与使用方式
- 溢出列表 · 综合展示 / 溢出处理 1：首先体验这个示例，再查看代码理解组件的组合方式。
- 溢出列表 · 溢出处理 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- 溢出列表 · 溢出处理 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- 溢出列表 · 溢出处理 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- 溢出列表 · 溢出处理 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- 溢出列表 · 溢出处理 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
API 与上游详细参考
优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。
Overflow List
A horizontal list that automatically hides items when they exceed the available width. Use OverflowList for breadcrumbs, toolbars, tag lists, or any row that needs to collapse gracefully at smaller sizes.
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| children * | ReactNode | 要渲染的项目，每个子元素应为单一元素。 | |
| overflowRenderer | (overflowItems: OverflowItem[]) => ReactNode | 溢出指示器的渲染函数。接收隐藏项目列表（每项包含 child 和 index）。仅在有溢出项时调用。 | |
| onOverflowChange | (overflowItems: OverflowItem[]) => void | 折叠项集合变化时调用：发生折叠时传入折叠项，行重新变宽、全部放得下时传入空数组。没有溢出时（包括挂载时）不会调用。用于将折叠项交给周围界面已有的菜单，避免列表再挂载一个自己的指示器。 | |
| gap | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 2 | 项目间距，使用间距步进值（0、0.5、1、1.5、2、3、4、5、6、8、10）。 |
| minVisibleItems | number | 0 | 溢出时始终显示的最小项目数。 |
| maxVisibleItems | number | undefined (no cap) | 始终显示的最大项目数（即使全部都能放下）。它是 minVisibleItems 的上限伙伴；多余项目会折叠进溢出指示器。若小于 minVisibleItems，则以下限为准。 |
| maxRows | number | undefined (single line) | 在将其余项目折叠进溢出指示器之前，允许项目换行到的最大行数。是数字而非布尔值。留空（或设为 1）表示单行。假定行高一致。 |
| collapseFrom | 'start' | 'end' | 'end' | 溢出时从哪一端开始折叠项目。 |
| behavior | 'observeSelf' | 'observeParent' | 'observeSelf' | 控制测量可用宽度的元素。'observeSelf' 使用容器自身宽度；'observeParent' 观察父元素，适用于需要内容尺寸但仍检测可用空间的场景。 |
| xstyle | StyleXStyles | 用于布局自定义的 StyleX 样式（外边距、定位、尺寸）。必须使用 stylex.create() 的值，而非内联样式对象。 |
使用建议
- Provide a meaningful overflowRenderer: a "+N more" badge, a dropdown, or a count indicator.
- When the row already has its own menu, use onOverflowChange to feed the collapsed items into it instead of adding a second anchor with overflowRenderer.
- Set minVisibleItems to keep key items visible, and maxVisibleItems to cap the row at a fixed count regardless of available width.
- Use maxRows to let items wrap onto a bounded number of rows (e.g. a two-row tag cloud) before collapsing the rest into the indicator.
- 避免：Use OverflowList for a vertical stack; horizontal multi-row wrap is supported via maxRows, but items still flow left-to-right, not top-to-bottom.
主题 API
{
"targets": [
{
"className": "astryx-overflow-list"
}
]
}
组件结构
- List: Visible horizontal list container for the currently shown content.
- Items: Caller-supplied items selected for visible display by the current width and count limits.
- Overflow indicator: Optional caller-rendered indicator for items collapsed by width or count limits.