# @blossom-carousel/web 中文文档

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

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

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

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

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

- 包体积（解压后）：116 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-05-13T15:04:55.917Z
- 最新版本发布：2026-11-04T16:08:43.152Z
- 近 30 天下载量：3136（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 20 个）

## 中文简介

网络的自来自来自来自来自来自来自来自去的组件.

## 安装

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

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

## README

# 花花木马

在Web的拖曳支持下, 本地- 滚动- 第一台旋转木马得到了增强 .

## 安装

`npm install @blossom-carousel/web`

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

```javascript
import "@blossom-carousel/web";
import "@blossom-carousel/web/style.css";
```

#### 光盘N

```html
<script src="https://unpkg.com/@blossom-carousel/web@1/dist/blossom-carousel-web.umd.js"></script>
<link
  rel="stylesheet"
  href="https://unpkg.com/@blossom-carousel/web@1/dist/blossom-carousel-web.css"
/>
```

键入主版本( P)`@1`),所以未来的大放出,没有你的选择,无法更改页面.

## 使用量

```html
<blossom-carousel>
  <div>Slide 1</div>
  <div>Slide 2</div>
  <div>Slide 3</div>
  ...
</blossom-carousel>
```

### 导航控制

`<blossom-prev>`, (中文(简体) ), `<blossom-next>`,以及 `<blossom-dots>` 使用本地的 Invoker 命令 API 自动连接 prv/ next 和 点导航 。 给木马一把 `id`幻灯片 `data-blossom-slide`,并用 `for` 属性.

```html
<blossom-carousel id="my-carousel">
  <div data-blossom-slide>Slide 1</div>
  <div data-blossom-slide>Slide 2</div>
  <div data-blossom-slide>Slide 3</div>
</blossom-carousel>

<blossom-prev for="my-carousel"></blossom-prev>
<blossom-dots for="my-carousel"></blossom-dots>
<blossom-next for="my-carousel"></blossom-next>
```

#### 前一頁/下按钮

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

在元素上设置文本或 HTML(例如 SVG 图标)来替换默认的按钮标签. 空或仅白空域内容仍会返回到 `Previous` 编号 : `Next`。 。 。 .

```html
<blossom-prev for="my-carousel">Previous</blossom-prev>
<blossom-next for="my-carousel">
  <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 4l8 8-8 8" /></svg>
</blossom-next>
```

内侧按钮默认命名为"上一张幻灯片"或"下一张幻灯片". 设定 `aria-label` 。它被移动到内部按钮上。 一个 `aria-label` 独自一人 `<button>` 儿童优先.

```html
<blossom-prev for="my-carousel" aria-label="Previous products"></blossom-prev>
<blossom-next for="my-carousel" aria-label="Next products"></blossom-next>
```

#### 点

`<blossom-dots>` 使每张幻灯片有一个按键标记 `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;
```

为了带来自己的点,提供 `<blossom-dot>` 儿童——每张幻灯片及其内部复制 `<button>` 自动接收导航属性.

```html
<blossom-dots for="my-carousel">
  <blossom-dot class="my-dot">
    <button type="button" aria-label="Custom label">•</button>
  </blossom-dot>
</blossom-dots>
```

或者让 `blossom-dot` 从它的光- DOM 子程序创建按钮 :

```html
<blossom-dots for="my-carousel">
  <blossom-dot class="my-dot">•</blossom-dot>
</blossom-dots>
```

原型 `<blossom-dot>` 隐藏;克隆在点容器中提供。 现有 `aria-label` 并保存按钮上的其他属性。 由于它是一个单一的克隆模板,每个点都会得到相同的内容——对于单一的活性/活性外观来说是罚款的,但是对于每个幻灯片(如每滑行缩略图)不同的内容则不是罚款的.

为此,设置 `renderDot` 编辑 `blossom-dots` 元素 – 每张幻灯片引用一次召回 `(index, active, forId)`它优先于任何 `<blossom-dot>` 原型并返回要渲染的元素; 导航属性合并到其上 `<button>` 自动 :

```html
<blossom-dots for="my-carousel" id="dots"></blossom-dots>

<script type="module">
  document.getElementById("dots").renderDot = (index, active) => {
    const button = document.createElement("button");
    button.setAttribute("data-blossom-dot", "");
    button.className = "dot";
    button.dataset.active = String(active);
    button.innerHTML = `<img src="/thumbs/${index}.jpg" alt="Slide ${index + 1}">`;
    return button;
  };
</script>
```

#### 滚动行为

默认情况下,每个导航控制会顺利地滚动. 设定 `behavior` 属性为 `"instant"` 或者说 `"auto"` 来改变这一点。 打开 `<blossom-dots>` 它适用于每一个点; a `<blossom-dot>` 原型可以覆盖它.

```html
<blossom-prev for="my-carousel" behavior="instant"></blossom-prev>
<blossom-dots for="my-carousel" behavior="instant"></blossom-dots>
<blossom-next for="my-carousel" behavior="instant"></blossom-next>
```

属性复制到内部按钮为 `data-blossom-behavior`。如果您自己的按钮已经有一个 `data-blossom-behavior` 属性,优先.

#### 正在聆听命令

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

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

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

```html
<blossom-carousel id="my-carousel">
  <div data-blossom-slide>Slide 1</div>
  <div data-blossom-slide>Slide 2</div>
  <div data-blossom-slide>Slide 3</div>
</blossom-carousel>

<script>
  document.getElementById("my-carousel").addEventListener("command", (event) => {
    const command = event?.command || event?.detail?.command;
  });
</script>
```

## 方法

呼叫这些 `<blossom-carousel>` 从自己的代码导航的元素 :

-   `prev(options?)` 滚动到上一个坐标点或页面.
-   `next(options?)` 滚动到下一个坐标点或页面.
-   `goTo(index, options?)` 以零键向幻灯片滚动 `index`,以 `data-blossom-slide`。 。 。 .

`options.behavior` 接受 `"smooth"` (违约), `"instant"` 或者说 `"auto"`。 。 。 .

```html
<blossom-carousel id="my-carousel">
  <div data-blossom-slide>Slide 1</div>
  <div data-blossom-slide>Slide 2</div>
  <div data-blossom-slide>Slide 3</div>
</blossom-carousel>

<button id="back">Back to start</button>

<script>
  const carousel = document.getElementById("my-carousel");
  document.getElementById("back").addEventListener("click", () => {
    carousel.goTo(0, { behavior: "instant" });
  });
</script>
```

## 过度滚动 API

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

```html
<blossom-carousel id="my-carousel">
  <div>Slide 1</div>
  <div>Slide 2</div>
  <div>Slide 3</div>
</blossom-carousel>

<script>
  document.getElementById("my-carousel").addEventListener("overscroll", (event) => {
    event.preventDefault();
    const overScroll = event.detail.left;

    Array.from(event.currentTarget.children).forEach((slide) => {
      slide.style.transform = `scale(${1 - overScroll * 0.1})`;
    });
  });
</script>
```

## 实例

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

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

## 常见问题

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

网络的自来自来自来自来自来自来自来自去的组件\.

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

在项目目录运行 npm install @blossom-carousel/web，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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