# @blossom-carousel/react 中文文档

规范地址：https://npmcn.com/package/%40blossom-carousel/react/

版本：1\.8\.0
npm 元数据更新时间：2026-11-04T16:08:40.860Z
中文译文更新时间：2026-11-08T08:03:47.031Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40blossom-carousel/react
原文对照：https://npmcn.com/package/%40blossom-carousel/react/?lang=original
项目主页：https://www.blossom-carousel.com/
源码仓库：https://github.com/jespervos/blossom-carousel

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：54.9 kB，19 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2025-04-23T11:49:51.495Z
- 最新版本发布：2026-11-04T16:08:40.671Z
- 近 30 天下载量：91265（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 20 个）

## 中文简介

原生-螺旋-第一旋转木马组件用于React.

## 安装

```sh
npm install @blossom-carousel/react
```

也可以使用：`pnpm add @blossom-carousel/react`、`yarn add @blossom-carousel/react`、`bun add @blossom-carousel/react`

## README

# 花花木马

用拖动支持 React 增强本地- 滚动- 第一台旋转木马 .

## 安装

`npm install @blossom-carousel/react`

[完全安装指令](https://www.blossom-carousel.com/docs/framework-guides/react-nextjs)

#### 反应

```jsx
import { BlossomCarousel } from "@blossom-carousel/react";
import "@blossom-carousel/react/style.css";

function App() {
  return <BlossomCarousel>{/* slides */}</BlossomCarousel>;
}
```

#### 下一个.js

添加导入到您的页面或组件 :

```jsx
import { BlossomCarousel } from "@blossom-carousel/react";
import "@blossom-carousel/react/style.css";

export default function Page() {
  return <BlossomCarousel>{/* slides */}</BlossomCarousel>;
}
```

## 使用量

```jsx
<BlossomCarousel>
  {Array.from({ length: 12 }, (_, i) => (
    <div key={i}>Slide {i + 1}</div>
  ))}
</BlossomCarousel>
```

### 作为

定义自动机根的 HTML 元素.

```jsx
<BlossomCarousel as="ul">
  {Array.from({ length: 12 }, (_, i) => (
    <li key={i}>Slide {i + 1}</li>
  ))}
</BlossomCarousel>
```

显示为

```html
<ul>
  <li>Slide 1</li>
  <li>Slide 2</li>
  <li>Slide 3</li>
  ...
</ul>
```

### 导航控制

在旋转木马外放置上一个、下一个和点控制器 `<BlossomPrev>`, (中文(简体) ), `<BlossomNext>`,以及 `<BlossomDots>`把它们和旋转木马联系起来 `id` 打开 `<BlossomCarousel>`匹配时 `for` 每个控件上的道具并用 `data-blossom-slide`。 。 。 .

```jsx
<BlossomCarousel id="my-carousel">
  {Array.from({ length: 12 }, (_, i) => (
    <div key={i} data-blossom-slide>
      Slide {i + 1}
    </div>
  ))}
</BlossomCarousel>

<BlossomPrev for="my-carousel" />
<BlossomDots for="my-carousel" />
<BlossomNext for="my-carousel" />
```

#### 前一頁/下按钮

`<BlossomPrev>` 财务报告和审定财务报表 `<BlossomNext>` 已意识到已配置的卷轴,并将在坐标点之间导航。 当没有配置卷轴后, 它们会按比例滑动旋转木马 .

传递孩子替换默认按钮图标 .

```jsx
<BlossomPrev for="my-carousel">
  <span>Previous</span>
</BlossomPrev>
```

#### 点

`<BlossomDots>` 使每张幻灯片有一个按键标记 `data-blossom-slide`。 。 。 . 默认样式可以在组件或任何祖先上带有 CSS 自定义属性:

```css
/* defaults */
--blossom-dot-size: 0.625rem;
--blossom-dot-radius: 50%;
--blossom-dot-color: currentColor;
--blossom-dot-opacity: 0.35;
--blossom-dot-hover-opacity: 0.6;
--blossom-dot-active-opacity: 1;
```

要带来自己的点, 通过一个渲染函数和渲染 `<BlossomDot>` 内在的 这将将点配置为 `<button>` 有导航线. 现在您可以随意样式点并附加任何需要的按钮属性.

```jsx
<BlossomDots for="my-carousel">
  {({ index, active }) => (
    <BlossomDot
      className="my-dot"
      data-active={active}
      aria-label={`Photo ${index + 1}`}
    >
      {index + 1}
    </BlossomDot>
  )}
</BlossomDots>
```

#### 滚动行为

默认情况下,每个导航控制会顺利地滚动. 设定 `behavior` 向 `"instant"` 或者说 `"auto"` 来改变这一点。 打开 `<BlossomDots>` 它适用于每一个点; a `<BlossomDot>` 它可以自己覆盖它.

```jsx
<BlossomPrev for="my-carousel" behavior="instant" />
<BlossomDots for="my-carousel" behavior="instant" />
<BlossomNext for="my-carousel" behavior="instant" />
```

道具作为 `data-blossom-behavior` 属性。 设定自己的属性优先于道具.

#### 正在聆听命令

听着 `command` 旋转木马上的事件,以了解何时启动导航控制或何时启动 [方法](https://npmcn.com/package/%40blossom-carousel/react/#readme-methods) 称为:

-   上一个`--blossom-prev`(中文(简体) )
-   下一个(`--blossom-next`(中文(简体) )
-   点数( n)`--blossom-goto-{index}`) (中文(简体) ).

这些事件不是通过拖放或自由滚动来发射的. 读取 `event.command` (或 `event.detail.command` 使用 Invoker 命令多填充).

`onCommand` 财务报告和审定财务报表 `onOverscroll` 需求 `@blossom-carousel/react` 1.8.0 或晚点。 更早的版本把它们传给了DOM,在那里React忽略了它们.

```jsx
<BlossomCarousel onCommand={handleCommand}>
  {Array.from({ length: 12 }, (_, i) => (
    <div key={i} data-blossom-slide>
      Slide {i + 1}
    </div>
  ))}
</BlossomCarousel>

function handleCommand(event) {
  const command = event?.command || event?.detail?.command;
}
```

## 方法

传出 a `ref` 改为 `<BlossomCarousel>` 从自己的代码导航。 裁判收到 `BlossomCarouselHandle`数字 :

-   `prev(options?)` 滚动到上一个坐标点或页面.
-   `next(options?)` 滚动到下一个坐标点或页面.
-   `goTo(index, options?)` 以零键向幻灯片滚动 `index`,以 `data-blossom-slide`。 。 。 .
-   `element` 是旋转木马的根部元素.

`options.behavior` 接受 `"smooth"` (违约), `"instant"` 或者说 `"auto"`。这些方法使用本地滚动,因此它们也用于拖放引擎未加载的触摸设备.

```tsx
import { useRef } from "react";
import { BlossomCarousel, type BlossomCarouselHandle } from "@blossom-carousel/react";

function Gallery() {
  const carousel = useRef<BlossomCarouselHandle>(null);

  return (
    <>
      <BlossomCarousel ref={carousel}>
        {Array.from({ length: 12 }, (_, i) => (
          <div key={i} data-blossom-slide>
            Slide {i + 1}
          </div>
        ))}
      </BlossomCarousel>

      <button onClick={() => carousel.current?.goTo(0, { behavior: "instant" })}>
        Back to start
      </button>
    </>
  );
}
```

## 过度滚动 API

进入Blossom的拖动引擎的过度扭曲行为来创造出自己的风格.

```jsx
<BlossomCarousel
  onOverscroll={(event) => {
    event.preventDefault();
    const overScroll = event.detail.left;

    Array.from(event.currentTarget.children).forEach((slide) => {
      slide.style.transform = `scale(${1 - overScroll * 0.1})`;
    });
  }}
>
  {Array.from({ length: 12 }, (_, i) => (
    <div key={i}>Slide {i + 1}</div>
  ))}
</BlossomCarousel>
```

## 实例

探索以复杂程度分类的现成至复制木马图案.

[参见所有实例](https://www.blossom-carousel.com/docs/examples/)

## 常见问题

### @blossom-carousel/react 是什么？

原生-螺旋-第一旋转木马组件用于React\.

### 如何安装 @blossom-carousel/react？

在项目目录运行 npm install @blossom-carousel/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @blossom-carousel/react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @blossom-carousel/react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @blossom-carousel/react 可以商用吗？

@blossom-carousel/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @blossom-carousel/react 的下载量有多少？

根据 npm 官方下载统计，@blossom-carousel/react 在 2026/10/09 – 2026/11/07 这 30 天内被下载 91,265 次，日均约 3,042 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @blossom-carousel/react 还在维护吗？

最新版本 1\.8\.0 发布于 2026/11/05（3 天前）；至今共发布 42 个版本，其中过去 12 个月发布了 20 个；首次发布于 2025/04/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。