---
title: "React 可滚动栏中的筛选标签"
description: "React 中的横向筛选标签栏：标签原生滚动，新增标签会自动滚动进入视图，拖拽滚动且不影响点击。附带实时演示和源码。"
canonical: "https://react-horizontal-scrolling-menu.dev/zh-cn/filter-chips"
image: "https://react-horizontal-scrolling-menu.dev/og.png"
---

# React 中的可滚动筛选标签栏

几乎每个搜索栏下方都有这样一行标签——YouTube 的话题、商店筛选项、标签选择器——本质上是一个装满切换按钮的单行滚动容器。难的那 10% 在于边缘处发生的事：新增的标签出现在屏幕外、拖拽绝不能触发任何切换、以及箭头要知道自己何时已经没用了。

react

typescript

scrolling

menu

gallery

tabs

carousel

slider

accordion

lightbox

Add filter

添加一个筛选项——该行会自动将新标签滚动进入可视区域。

[在 Storybook 中实时编辑此示例](https://asmyshlyaev177.github.io/react-horizontal-scrolling-menu/?path=/story/examples-additemandscrolltoit--add-item-and-scroll-to-it)

## 边缘情况才是这个组件的价值所在

任何带 `overflow-x: auto` 的 flex 行都能滚动。而一个筛选标签栏的价值恰恰体现在这些细节上：

-   **在屏幕外新增的标签必须让自己被看到。** 演示中在渲染后会用 `apiRef.current.scrollToItem(el, 'smooth', 'end')` 滚动到每一个新标签——[新增项并滚动到该项示例](https://react-horizontal-scrolling-menu.dev/zh-cn/examples/add-item-and-scroll-to-it.md) 就是这套接线方式。
-   **拖拽用于滚动，点击用于切换——二者绝不能混淆。** 桌面用户会像操作触控面板一样拖拽这一行；在某个标签上松开时不能将其翻转。[拖拽方案](https://react-horizontal-scrolling-menu.dev/zh-cn/examples/mouse-drag.md) 会跟踪手势，并精确抑制那一次点击。
-   **箭头只在有用时出现。** `useLeftArrowVisible` / `useRightArrowVisible` 接到了与其他一切相同的 IntersectionObserver 上，因此箭头会在真正的边缘处禁用——即便是在标签被新增或移除之后也是如此。

## 状态始终掌握在你手中

本库负责滚动，不负责选中状态。标签是你自己的按钮——多选切换用 `aria-pressed`，单选用普通 state——菜单只要求每一个标签携带一个 `itemId`。这意味着标签状态可以与你已有的任何东西组合：URL 查询参数、表单库，或服务端驱动的筛选模型。删除一个标签就是 [移除一个项目](https://react-horizontal-scrolling-menu.dev/zh-cn/examples/add-items.md)；为其加上退场动画则参见 [项目动画示例](https://react-horizontal-scrolling-menu.dev/zh-cn/examples/items-animation.md)。

## 移动端：关于页面滚动的一个提醒

在触屏设备上，某些浏览器中在该栏内的横向滑动可能会连带把整个页面也一起拖动。如果你遇到这种情况，[阻止页面滚动示例](https://react-horizontal-scrolling-menu.dev/zh-cn/examples/prevent-body-scroll.md) 展示了如何用 `touch-action` 和 overscroll 约束来锁定这一行为——纯 CSS，不需要任何手势库。

## 最简模式

标签就是带有 `itemId` 的切换按钮；通过菜单 API 的 ref 可以将新增的标签滚动进入视图。

ChipBar.tsx

```
function ChipBar({ options }: { options: string[] }) {
  const apiRef = React.useRef<publicApiType>(null);
  const [selected, setSelected] = React.useState<string[]>([]);

  const toggle = (id: string) =>
    setSelected((cur) =>
      cur.includes(id) ? cur.filter((c) => c !== id) : [...cur, id],
    );

  // A chip appended off-screen scrolls itself into view.
  const addChip = (id: string) => {
    toggle(id);
    requestAnimationFrame(() => {
      const el = apiRef.current?.getItemElementById(id);
      if (el) apiRef.current?.scrollToItem(el, 'smooth', 'end');
    });
  };

  return (
    <ScrollMenu apiRef={apiRef}>
      {options.map((id) => (
        <Chip itemId={id} key={id} pressed={selected.includes(id)}
          onToggle={() => toggle(id)} />
      ))}
    </ScrollMenu>
  );
}
```

## 或者以 shadcn 组件的形式安装

[chip-bar](https://react-horizontal-scrolling-menu.dev/r/chip-bar.json) 注册表条目以受控组件的形式提供——`options`、`selected`、`onSelectedChange`——以 Tailwind 样式安装进你的 `components/ui/`：

shadcn

```
npx shadcn@latest add https://react-horizontal-scrolling-menu.dev/r/chip-bar.json
```

## 相关示例

-   [添加项目并滚动到它筛选标签模式：先追加，再滚入可视区。](https://react-horizontal-scrolling-menu.dev/zh-cn/examples/add-item-and-scroll-to-it.md)
-   [到达末尾时加载更多由最后一个项目的可见性驱动的无限追加。](https://react-horizontal-scrolling-menu.dev/zh-cn/examples/add-items.md)
-   [阻止页面滚动滚轮划过菜单时滚动菜单，而非页面。](https://react-horizontal-scrolling-menu.dev/zh-cn/examples/prevent-body-scroll.md)

[全部 21 个示例](https://react-horizontal-scrolling-menu.dev/zh-cn/examples.md)

---

More examples: <https://react-horizontal-scrolling-menu.dev/examples.md>
Library summary for LLMs: <https://react-horizontal-scrolling-menu.dev/llms.txt>