npm package: @qqxiaobin/film-carousel
Description: Vue 3 film-strip style auto-scrolling carousel component
Latest version: 0.1.16

# Film Carousel (Vue 3)

## 安装

```bash
npm i @qqxiaobin/film-carousel
# 或者使用 pnpm
pnpm add @qqxiaobin/film-carousel
```

## 使用

```ts
// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import FilmCarouselPlugin from '@qqxiaobin/film-carousel'
import '@qqxiaobin/film-carousel/style'

createApp(App).use(FilmCarouselPlugin).mount('#app')
```

```vue
<template>
  <FilmCarousel
    :items="items"
    :speed="0.9"
    background="black"
    :show-grain="true"
    aspect-ratio="4:3"
    height="300"
    width="100%"
    gap="15px"
  />
</template>

<script setup lang="ts">
import type { FilmCarouselItem } from '@qqxiaobin/film-carousel'

const url =
  'https://java-ai-888.oss-cn-beijing.aliyuncs.com/2025/09/05c567fc-2820-417c-9b60-939d04aa2a8f.jpg'
const items: FilmCarouselItem[] = [
  { id: 1, src: url, overlayText: '北极熊' },
  { id: 2, src: url, overlayText: '北极熊2' },
  { id: 3, src: url },
  { id: 4, src: url, overlayText: '北极熊4' },
  { id: 5, src: url, overlayText: '北极熊5' },
]
</script>
```

## 配置项说明

- `items: FilmCarouselItem[]` 必填

  - 结构：`{ id?: string | number; src: string; title?: string; alt?: string; overlayText?: string }`
  - 建议提供稳定的 `id` 以提升渲染性能。
  - `overlayText` 为每个项目独立的闪动文字内容，如果设置则会在该图片上显示闪动文字。

- `speed?: number` 可选，默认 `0.9`

  - 胶片横向滚动的速度（像素/帧）。数值越大滚动越快。

- `overlayText?: string` 可选

  - 全局闪动文案内容。当项目自身没有设置 `overlayText` 时，会使用此配置和下面的索引配置来显示闪动文字。

- `overlayIndex?: number` 可选，默认 `1`

  - 单张闪动文案显示的帧索引（从 0 开始）。仅在项目自身没有设置 `overlayText` 时生效。

- `overlayIndices?: number[]` 可选

  - 多张显示闪动文案时的帧索引数组，存在时将覆盖 `overlayIndex`。仅在项目自身没有设置 `overlayText` 时生效。
  - 注意：组件为实现无缝滚动会将 `items` 复制一份用于渲染，`overlayIndices` 按渲染序列的索引判断（例如 `[0,2]` 表示第 1、3 张）。

- `background?: string` 可选

  - 容器背景（任意合法 CSS `background` 值），如纯色或渐变。

- `showGrain?: boolean` 可选，默认 `false`

  - 是否叠加轻微“颗粒”质感的视觉效果。

- `aspectRatio?: string` 可选，默认 `"4:3"`

  - 帧容器宽高比，格式如 `"16:9"`、`"3:4"`。
  - 组件使用 CSS `aspect-ratio` + `object-fit: cover` 实现等比裁剪填充，因此图片会按该比例居中裁切。

- `height?: string | number` 可选

  - 轮播图容器的高度。可以是数字（像素值）或字符串（如 `"300px"`、`"50vh"`、`"100%"`）。

- `width?: string | number` 可选

  - 轮播图容器的宽度。可以是数字（像素值）或字符串（如 `"800px"`、`"100%"`、`"50vw"`）。
  - 组件会根据容器宽度和图片数量自动计算每张图片的显示宽度，确保图片内容不会被截断。
  - 图片帧宽度会在 200px-500px 之间自适应调整，移动端会有相应的响应式调整。

- `gap?: string | number` 可选，默认 `"10px"`
  - 图片之间的间距。可以是数字（像素值）或字符串（如 `"15px"`、`"1rem"`）。
  - 设置图片帧之间的右边距，控制图片之间的视觉间距。

## 使用注意事项

- 外链图片：建议使用可稳定访问的 HTTPS 链接；若图源较慢可考虑本地或 CDN 加速。
- 尺寸与清晰度：由于使用 `object-fit: cover` 进行裁剪，建议提供较高分辨率的图片以获得更好观感。
- 闪动文案配置：优先使用项目自身的 `overlayText`，如果没有设置则使用全局的 `overlayText` 和索引配置。当启用 `overlayIndices` 时请基于渲染序列的索引设置（组件会将 `items` 复制一遍以实现无缝滚动）。
- 尺寸自适应：组件会根据设置的容器宽度和图片数量自动调整每张图片的显示宽度，确保图片内容完整显示。建议根据实际需求设置合适的容器尺寸。
- 预览：点击图片会打开内置预览层，点击遮罩或右上角关闭按钮可退出。
- 性能：`speed` 较大或图片数量过多可能增加 GPU 占用；建议控制在合理范围。

## 按需引入（不使用全局插件）

你也可以直接按需导入组件（例如在局部注册或渲染函数中使用）：

```ts
// 以渲染函数为例（与 dev/prod.html 类似）
import { createApp, h } from 'vue'
import FilmCarouselPlugin, { FilmCarousel } from '@qqxiaobin/film-carousel'
import '@qqxiaobin/film-carousel/style'

const items = [
  { id: 1, src: url, overlayText: '北极熊' },
  { id: 2, src: url, overlayText: '北极熊2' },
  { id: 3, src: url },
  { id: 4, src: url, overlayText: '北极熊4' },
  { id: 5, src: url, overlayText: '北极熊5' },
]

createApp({
  setup() {
    return () =>
      h('div', [
        h(FilmCarousel, {
          items,
          speed: 0.9,
          background: 'black',
          showGrain: true,
          aspectRatio: '4:3',
          height: 300,
          width: '100%',
          gap: 15px,
        }),
      ])
  },
})
  .use(FilmCarouselPlugin) // 可选：若想全局注册 <FilmCarousel/>
  .mount('#app')
```

在 SFC 模板中使用时，`props` 请使用 `kebab-case`：例如 `overlayText` → `overlay-text`、`overlayIndices` → `overlay-indices`、`showGrain` → `show-grain`、`aspectRatio` → `aspect-ratio`、`height` → `height`、`width` → `width`、`gap` → `gap`（README 中示例已如此书写）。