# 列表 · List

- 页面: https://jiguang132.com/zh/resources/astryx/docs/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**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **列表 · 交互示例 7**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **列表 · 交互示例 8**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **列表 · 交互示例 9**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## List

A vertical collection of items with consistent spacing, dividers, and optional markers. Supports headers, icons, avatars, badges, and interactive items with click or link behavior. Use it to display ordered or unordered groups of related content.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| children | ReactNode |  | List items (ListItem components). |
| density | 'compact' \| 'balanced' \| 'spacious' | 'balanced' | Spacing density for items. |
| hasDividers | boolean | false | Show dividers between items. |
| edgeCompensation | 'inline' |  | Compensate for item content inset on each inline edge by cancelling the smaller of each item's built-in horizontal inset and the container's published inline padding. The margin reads the same variable the items derive their inline padding from, so it tracks density and theme padding overrides automatically without pulling rows outside zero-padding or full-bleed surfaces. Use under a section heading to bring row text toward the heading text. Content aligns when container padding is at least the item inset; smaller padding leaves some inset uncompensated. Omit to leave item positions unchanged. |
| header | ReactNode |  | Header content, associated with the list via aria-labelledby. |
| listStyle | 'none' \| 'disc' \| 'decimal' \| 'circle' | 'none' | List marker style. 'decimal' renders an <ol> element instead of <ul>. |
| start | number | 1 | Starting number for ordered lists (listStyle='decimal'). Sets the CSS counter to begin at this value. |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}. |

### 使用建议

- Provide a header to label the list and give context to screen readers.
- Use start and end content slots to add icons, avatars, or badges to each item.
- 避免：Place interactive elements inside an interactive list item; it creates nested click targets and confusing focus behavior.
- 避免：Use a list for a single item or for laying out unrelated content; lists imply a meaningful collection.
- 避免：Mix clickable and non-clickable items in the same list without clear visual distinction.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-list",
      "visualProps": [
        "density",
        "listStyle"
      ]
    },
    {
      "className": "astryx-list-item"
    }
  ]
}
```

## ListItem



### 组件结构

- **List title**: Heading that labels the list.
- **Description**: Supplementary text below the title.
- **List items**: Individual entries, which may include icons or images.
- **Item description**: Additional detail for an individual list item.

## List Item

列表项，包含标签、描述、起始/结束内容插槽和交互模式。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | 主要文本。 |
| description | ReactNode |  | 标签下方的次要内容。纯字符串会自动应用单行截断；ReactNode 允许子组件自行控制换行和多行截断行为。 |
| startContent | ReactNode |  | 在标签区域之前渲染的内容（如图标、头像）。 |
| endContent | ReactNode |  | 在标签区域之后渲染的内容（如徽章、箭头）。 |
| onClick | (e: MouseEvent) => void |  | 点击处理函数；启用隐形按钮模式。 |
| interactiveRef | RefObject<HTMLElement \| null> |  | 指向嵌套控件（如 startContent 中的复选框）的 ref，该控件承载项目的键盘访问和操作。行成为更大的点击/触摸目标，将表面点击委托给该控件（useClickableContainer），且不渲染不可见按钮/锚点，因此行不会增加第二个 Tab 停留点（WCAG 4.1.2）。与 onClick/href 互斥——设置后二者将被忽略。 |
| href | string |  | 链接 URL；启用隐形锚点模式。 |
| target | string |  | 链接 target 属性，仅在提供 href 时适用。target="_blank" 会自动添加 noopener noreferrer。 |
| rel | string |  | 链接关系标记。target="_blank" 会自动合并 noopener noreferrer。 |
| isDisabled | boolean | false | 禁用状态；在项目上设置 aria-disabled。 |
| isSelected | boolean | false | 选中状态；在项目上设置 aria-selected。 |
| swipeActions | {leading?: ItemSwipeAction[]; trailing?: ItemSwipeAction[]} |  | 触摸滑动操作，原样传递给 Item：横向拖动在每一侧揭示的操作，每项为 `{id?, label, icon?, onActivate, isDisabled?, variant?: 'neutral' \| 'accent' \| 'destructive', hasRemoval?}`。参见 Item.swipeActions；List 会在行内轴上裁剪行。 |
| swipeBehavior | 'reveal' \| 'commit' | 'reveal' | 滑动的行为，原样传递给 Item。参见 Item.swipeBehavior。 |

---

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