# React Vegas Demo

**Repository Path**: Dracowyn/react-vegas-demo

## Basic Information

- **Project Name**: React Vegas Demo
- **Description**: [Vegas Background SlideShow] 的 React 实现 Demo，提供强大而灵活的幻灯片组件，支持具有平滑​​过渡和可自定义效果的图像和视频。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-02-13
- **Last Updated**: 2025-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: React, TypeScript

## README

# React Vegas 幻灯片组件

基于 [Vegas Background SlideShow](https://github.com/jaysalvat/vegas) 实现的React组件，提供强大灵活的幻灯片展示功能，支持图片和视频，具有平滑过渡效果和可定制化功能。

简体中文 | [English](./README.EN.md)

## 功能特性

- 🖼️ 支持图片和视频
- 🎬 多种过渡效果
- 🔄 可配置间隔时间的自动播放
- 🎯 自定义对齐方式
- 🔀 随机播放模式
- ⚡ 预加载功能
- 📱 响应式设计
- 🎨 可定制的遮罩层和进度条
- 🎮 手动控制功能
- 🎯 TypeScript 支持

## 安装说明

当前暂未发布npm包，使用方法：
1. 将Vegas.tsx文件复制到项目中
2. 安装必要依赖：

```bash
npm install motion
# 或
yarn add motion
```

## 基础用法

```tsx
import Vegas from '@your-org/vegas-slideshow';

const App = () => {
  const slides = [
    {
      src: '/images/slide1.jpg',
      transition: 'fade'
    },
    {
      src: '/images/slide2.jpg',
      transition: 'slideLeft'
    }
  ];

  return (
    <Vegas
      slides={slides}
      delay={5000}
      autoplay={true}
    />
  );
};
```

## 高级用法

```tsx
const slides = [
  {
    src: '/images/slide1.jpg',
    align: 'center',                        // 水平对齐
    valign: 'center',                       // 垂直对齐
    transition: 'fade',                     // 过渡效果
    transitionDuration: 2000,               // 过渡时长
    delay: 5000                             // 本页停留时间
  },
  {
    src: '/videos/video1.mp4',
    video: {
      src: [                                // 多格式支持
        '/videos/video1.mp4',
        '/videos/video1.webm'
      ],
      muted: true,                          // 静音播放
      loop: false                           // 是否循环
    },
    transition: 'zoomIn'                    // 缩放进入效果
  }
];

<Vegas
  slides={slides}
  overlay={true}                            // 启用遮罩层
  timer={false}                             // 隐藏进度条
  delay={7000}                              // 全局停留时间
  shuffle={true}                            // 随机播放
  transitionDuration={3000}                 // 全局过渡时长
  firstTransitionDuration={5000}            // 初始过渡时长
  defaultBackground="/images/loading.jpg"   // 加载背景图
  defaultBackgroundDelay={2000}             // 加载背景显示时间
  debug={false}                              // 调试模式
  color="#000"                              // 背景色
/>
```

## 组件属性

### 基础属性

| 属性       | 类型      | 默认值   | 说明          |
|----------|---------|-------|-------------|
| slides   | Array   | 必填    | 幻灯片对象数组     |
| delay    | number  | 5000  | 幻灯片切换间隔(毫秒) |
| autoplay | boolean | true  | 启用自动播放      |
| loop     | boolean | true  | 循环播放        |
| shuffle  | boolean | false | 随机播放顺序      |

### 过渡效果

| 属性                      | 类型     | 默认值    | 说明         |
|-------------------------|--------|--------|------------|
| transition              | string | 'fade' | 过渡效果类型     |
| transitionDuration      | number | 1000   | 过渡时长(毫秒)   |
| firstTransitionDuration | number | 3000   | 初始过渡时长(毫秒) |

### 视觉属性

| 属性      | 类型      | 默认值   | 说明     |
|---------|---------|-------|--------|
| overlay | boolean | false | 显示遮罩层  |
| timer   | boolean | true  | 显示进度条  |
| color   | string  | null  | 背景颜色   |
| cover   | boolean | true  | 图片覆盖模式 |

### 加载配置

| 属性                     | 类型      | 默认值       | 说明       |
|------------------------|---------|-----------|----------|
| preload                | boolean | false     | 启用资源预加载  |
| preloadImage           | boolean | false     | 预加载图片    |
| preloadVideo           | boolean | false     | 预加载视频    |
| defaultBackground      | string  | undefined | 加载背景图    |
| defaultBackgroundDelay | number  | 2000      | 加载背景显示时长 |

### 回调函数

| 属性      | 类型         | 说明       |
|---------|------------|----------|
| onInit  | () => void | 初始化完成时触发 |
| onPlay  | () => void | 播放开始时触发  |
| onPause | () => void | 暂停时触发    |
| onWalk  | () => void | 幻灯片切换时触发 |

## 幻灯片对象属性

```typescript
interface Slide {
	src: string;                            // 资源路径
	color?: string;                         // 背景色
	delay?: number;                         // 单独设置停留时间
	align?: 'left' | 'center' | 'right';    // 水平对齐
	valign?: 'top' | 'center' | 'bottom';   // 垂直对齐
	transition?: string;                    // 单独过渡效果
	transitionDuration?: number;            // 单独过渡时长
	cover?: boolean;                        // 是否覆盖模式
	video?: {                               // 视频配置
		src: string[];                      // 多格式源
		muted?: boolean;                    // 静音
		loop?: boolean;                     // 循环
	};
}
```

## 可用过渡效果

- `fade`: 淡入淡出
- `slideLeft`: 左滑进入
- `slideRight`: 右滑进入
- `zoomIn`: 放大进入
- `zoomOut`: 缩小退出
- `zoomInOut`: 组合缩放

## 组件方法

通过ref可调用以下方法：

```tsx
const vegasRef = useRef();

// 可用方法
vegasRef.current.play();        // 开始播放
vegasRef.current.pause();       // 暂停播放
vegasRef.current.next();        // 下一张
vegasRef.current.previous();    // 上一张
```

## 浏览器支持

- Chrome (最新版)
- Firefox (最新版)
- Safari (最新版)
- Edge (最新版)

## 性能优化建议

1. 使用前优化图片体积
2. 选择合适的视频格式和分辨率
3. 启用预加载提升性能
4. 推荐使用WebP格式图片
5. 适当压缩视频文件

## 已知问题

- 部分浏览器需用户交互后才允许视频自动播放
- Safari对某些视频格式支持有限

## 致谢

本组件灵感来源于Jay Salvat开发的[jQuery版Vegas背景轮播插件](https://github.com/jaysalvat/vegas)，使用React和TypeScript进行了现代化重构。