# 轮播 · Carousel

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

## API 与上游详细参考

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

## Carousel

Carousel 在项目超出可用宽度时将一行项目水平滚动。适用于卡片网格、图片画廊、产品列表，或任何希望无需占据整页即可浏览的项目集合。

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| children * | ReactNode |  | 在水平滚动容器中渲染的轮播项目。 |
| gap | 0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 | 1 | 使用间距令牌比例的项目间距。 |
| hasButtons | boolean | true | 内容可滚动时显示上一个/下一个导航按钮。 |
| hasEdgeFade | boolean | true | 内容溢出时显示渐变边缘遮罩，提示屏幕外还有更多项目。 |
| hasLoop | boolean | false | 环绕滚动：在末尾按"下一个"回到开头，在开头按"上一个"跳到末尾。按钮在两端始终可见。仅在内容溢出时生效。 |
| hasSnap | boolean | false | 启用滚动吸附，使每个子元素吸附到起始边缘。 |
| padding | 0 \| 0.5 \| 1 \| 1.5 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 |  | 滚动容器内的内联内边距，并设置匹配的 scroll-padding，使吸附点与内容边缘对齐。 |
| aria-label | string | 'Carousel' | 轮播区域的无障碍标签。 |
| ref | React.Ref<HTMLDivElement> |  | Ref forwarded to the root element. |
| handleRef | React.Ref<CarouselHandle> |  | 命令式句柄，暴露 scrollNext()、scrollPrev()、scrollTo(index)、canScrollNext() 和 canScrollPrev() 以进行编程式滚动控制。 |
| xstyle | StyleXStyles |  | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value. |
| className | string |  | CSS class name for the root element. Prefer xstyle for styling. |
| style | CSSProperties |  | Inline styles for the root element. Prefer xstyle. |
| data-testid | string |  | Test selector for automated testing frameworks. |

### 使用建议

- 当每个项目应精确对齐到起始边缘时启用滚动吸附，例如画廊或产品列表。
- 在小型可循环的集合（如照片画廊）上使用 hasLoop，此时从最后一项绕回第一项的滚动更自然。
- 始终提供描述轮播内容的 aria-label，例如"精选产品"或"团队成员"。
- Carousel 实现不含自动轮播的 WAI-ARIA APG carousel 模式（https://www.w3.org/WAI/ARIA/apg/patterns/carousel/）：区域带有标签和 aria-roledescription="carousel"，每个项目是名为“第 N 张，共 M 张”的 group，滚动容器可获得焦点，键盘用户可用方向键平移。
- 使用一致的间距和项目宽度，让轮播看起来是有意为之，而不是内容意外溢出。
- 信任内置导航：触控板用户可水平滑动，鼠标用户可按住 Shift 滚动滚轮来浏览项目。
- 避免：将每位用户都必须看到的内容放入轮播。并非所有人都会水平滚动，关键内容应放在首屏。
- 避免：自动轮播项目。让用户按自己的节奏滚动。
- 避免：嵌套轮播。轮播中嵌套轮播会造成困惑并破坏键盘导航。

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-carousel"
    },
    {
      "className": "astryx-carousel-scroller",
      "visualProps": [
        "gap",
        "padding",
        "snap",
        "edgeFade"
      ]
    }
  ]
}
```

### 组件结构

- **Scroll container**: The horizontal overflow area that holds all items.
- **Items**: The children rendered in a row inside the scroll container. With hasSnap, each item snaps to the start edge.
- **Fade edges**: Gradient fades on the left and right edges that indicate more content is available. Enabled by default, disable with hasEdgeFade={false}.
- **Navigation buttons**: Prev/next buttons that appear when the content can scroll in that direction. Enabled by default, disable with hasButtons={false}.

---

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