ball-swiper

ball-swiper

Vue3 球面 3D 轮播组件：卡片沿球面排布、鼠标拖拽旋转、箭头翻页，也可退化为平面排布（ball3D=false）——适合首页头图、产品展廊、作品集等「视觉焦点」轮播展示。

English: Vue3 spherical 3D carousel — cards are laid out along a sphere with perspective scaling, rotated by mouse drag or arrow clicks (flat mode optional). Ideal for hero banners, product galleries and portfolio showcases.

快速开始

npm i ball-swiper -S

注：样式需手动引入 import 'ball-swiper/index.css'。 注：rem 布局前置要求——组件内部按 px→rem 换算尺寸，宿主页面必须设置 html 的 font-size（如 document.documentElement.style.fontSize = document.documentElement.clientWidth / 120 + 'px'），否则卡片尺寸失真。

快速应用

全局注入

import 'ball-swiper/index.css'; // ⚠️ 样式需手动引入
import BallSwiper from 'ball-swiper'
app.use(BallSwiper);

局部注入

import BallSwiperLib from 'ball-swiper';
import 'ball-swiper/index.css';
// 注：产物为 default 导出，具名导入依赖 CJS 互操作、部分构建工具（如 Vite）下不可靠，请 default 导入后解构
const { BallSwiper } = BallSwiperLib;

TypeScript 与 AI 支持

• 自带 index.d.ts 类型声明（package.json types 字段已配置），安装后编辑器/AI 直接获得完整类型提示。
• 配套 AI.md：面向 AI 助手的使用指南（API 速查、最小示例、典型错误对照），AI 编码工具可直接读取。

与同类的区别（选型参考）

适用：大屏 / 展示页的头像墙、商品墙、作品集、首页头图等「视觉焦点」轮播展示。 不适用：移动端触摸交互（只支持鼠标拖拽，无 touch 事件）；需要自动播放（无 autoplay）；数据频繁变动（每次全量重排）；SSR 渲染（内部依赖 DOM 测量）。

主参数

事件与插槽

示例

<template>
  <!-- rem 前置：组件内部 px→rem 换算依赖 html font-size -->
  <BallSwiper
    :data="data"
    :showNum="7"
    height="300px"
    @itemClick="itemClick">
    <template #default="{ row }">
      <div class="name">{{ row.name }}</div>
      <div class="img">
        
      </div>
    </template>
  </BallSwiper>
</template>

<script setup>
import { ref, onMounted } from 'vue';
import 'ball-swiper/index.css'; // ⚠️ 样式需手动引入
import BallSwiperLib from 'ball-swiper';
// 注：产物为 default 导出，具名导入依赖 CJS 互操作、部分构建工具（如 Vite）下不可靠，请 default 导入后解构
const { BallSwiper } = BallSwiperLib;

const data = ref([
  { name: 'A', url: 'a.png' },
  { name: 'B', url: 'b.png' },
  { name: 'C', url: 'c.png' },
]);
const itemClick = (row) => console.log(row);

onMounted(() => {
  // rem 前置：按视口宽度设置根字号
  document.documentElement.style.fontSize = document.documentElement.clientWidth / 120 + 'px';
});
</script>

版本以 package.json 为准。