Film Carousel (Vue 3)

安装

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

使用

// 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')

<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 占用；建议控制在合理范围。

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

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

// 以渲染函数为例（与 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 中示例已如此书写）。