# 溢出列表 · OverflowList

- 页面: https://jiguang132.com/zh/resources/astryx/docs/overflow-list
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

溢出列表用于表格与列表场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **溢出列表 · 综合展示 / 溢出处理 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

```json
{
  "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.

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt