---
title: "useCycleList 用法与示例"
description: "循环浏览项目列表。"
canonical: https://reactuse.com/zh-Hans/state/usecyclelist/
---

# useCycleList

循环浏览项目列表


`useCycleList` 接受一个项目数组，返回一个 `[currentItem, next, prev]` 元组。调用 `next()` 前进到列表中的下一项，到达末尾时回到开头。调用 `prev()` 以相同的循环行为向后移动。你可以选择传入起始索引，也可以通过向 `next` 或 `prev` 传入偏移量一次跳过多项。

### 使用场景

- 循环切换主题选项、颜色方案或显示模式
- 构建循环播放一组项目的轮播或幻灯片
- 轮换一组预定义值（例如字体大小、排序顺序）

### 注意事项

- **泛型类型**：该 hook 是完全泛型的；列表可以包含任何类型（字符串、数字、对象等）。
- **SSR 安全**：内部仅使用 React 状态，无浏览器 API 依赖。
- 参见 `useCounter` 了解在带有最小/最大边界的数值范围内循环。

## Usage

```tsx live

function Demo() {
  const [state, next, prev] = useCycleList([
    "Dog",
    "Cat",
    "Lizard",
    "Shark",
    "Whale",
    "Dolphin",
    "Octopus",
    "Seal",
  ]);

  return (
    <div>
      <div>{state}</div>
      <div>
        <button onClick={() => next()}>下一个</button>
        <button onClick={() => prev()}>上一个</button>
      </div>
    </div>
  );
};

```

%%API%%