# multigallery

**Repository Path**: axel666/multigallery

## Basic Information

- **Project Name**: multigallery
- **Description**: MultiGallery 是一个支持图片和视频展示的 Vue 3 组件，结合了 PhotoSwipe 插件，提供灵活的媒体浏览体验。支持自动播放、暂停、导航控制以及自定义样式等功能。此组件允许展示图片和视频资源，支持通过手势或按钮进行控制。
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-04-07
- **Last Updated**: 2025-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue 3 多媒体画廊组件 (MultiGallery)

## 简介

`MultiGallery` 是一个支持图片和视频展示的 Vue 3 组件，结合了 PhotoSwipe 插件，提供灵活的媒体浏览体验。支持自动播放、暂停、导航控制以及自定义样式等功能。此组件允许展示图片和视频资源，支持通过手势或按钮进行控制。

## 功能特点

- **支持图片与视频**：可以同时展示图片和视频，并支持视频的自动播放与暂停。
- **自定义样式**：可以设置背景不透明度、箭头显示、导航样式等。
- **自动播放和计时器**：支持自动播放视频并使用计时器控制切换。
- **事件回调**：通过 `@changed` 事件回调当前索引，便于外部控制。
- **跳转控制**：可以直接跳转到指定的索引，方便用户控制展示的媒体资源。
- **支持手势操作**：支持通过触摸手势控制切换和关闭。

## 使用示例

### 组件导入

在 Vue 文件中导入并使用 `MultiGallery` 组件。

```
vue复制编辑<script setup>
import { ref } from 'vue'
import MultiGallery from './components/multigallery/index.vue'

const images =  [
  { src: 'https://example.com/image1.jpg', type: 'image', width: 0, height: 0, duration: 5 },
  { src: 'https://example.com/video.mp4', type: 'video', width: 0, height: 0, duration: 5 },
]

const galleryRef = ref(null)

const onChange = (index) => {
  console.log('Current index changed to:', index)
}
</script>

<template>
  <MultiGallery
    :images="images"
    galleryID="my-gallery"
    :psw="960"
    :psh="540"
    :bgOpacity="0.5"
    :showArrow="true"
    :showNavigation="false"
    :navigationStyle="{ size: 30, color: 'white', activeColor: 'red', spacing: 10 }"
    :useChanged="true"
    @changed="onChange"
    ref="galleryRef"
  />
</template>
```

### 控制按钮

提供了暂停、播放、跳转等控制按钮，用户可以方便地控制当前显示的媒体资源。

```
vue复制编辑<template>
  <!-- 控制按钮 -->
  <div style="margin-top: 20px; text-align: center;">
    <button @click="pauseSlide">暂停</button>
    <button @click="playSlide">播放</button>
  </div>

  <!-- 跳转控制 -->
  <div style="margin-top: 20px; text-align: center;">
    <label for="indexInput">跳转到索引：</label>
    <input id="indexInput" type="number" min="0" :max="images.length - 1" placeholder="输入索引"><br/>
    <button @click="goToSlide">跳转</button>
    <p>当前索引：{{ currentIndex }}</p>
  </div>
</template>

<script setup>
const currentIndex = ref(0)

const pauseSlide = () => {
  if (galleryRef.value) {
    galleryRef.value.manageSlide(false) // false 表示暂停
  }
}

const playSlide = () => {
  if (galleryRef.value) {
    galleryRef.value.manageSlide(true) // true 表示播放
  }
}

const goToSlide = () => {
  const index = parseInt(document.getElementById("indexInput").value) || 0;
  if (galleryRef.value && !isNaN(index)) {
    galleryRef.value.gotoSlide(index);
  }
}
</script>
```

## 属性说明

| 属性              | 类型    | 默认值                                                       | 是否必须配置项 | 说明                                                         | 备注                                                         |
| ----------------- | ------- | ------------------------------------------------------------ | -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `galleryID`       | String  | -                                                            | 是             | 画廊容器的 ID，必须是唯一的 ID。                             | 该 ID 用于在 DOM 中标识画廊容器。                            |
| `images`          | Array   | -                                                            | 是             | 图像数据数组，包含每个资源的 `src`、`type`、`width`、`height` 和 `duration` 等信息。 | `src`：资源路径 `type`：资源类型（`image` 或 `video`） `width` 和 `height`：预留字段，设置为 `0` 即可 `duration`：轮播时长（单位：秒），适用于图片自动播放或视频播放时计时。 |
| `psw`             | Number  | -                                                            | 是             | 画廊容器的宽度，单位为像素。                                 | -                                                            |
| `psh`             | Number  | -                                                            | 是             | 画廊容器的高度，单位为像素。                                 | -                                                            |
| `autoplay`        | Boolean | `true`                                                       | 否             | 是否启用视频自动播放。                                       | 启用后，视频将按照 `duration` 播放，自动播放策略。           |
| `startIndex`      | Number  | `0`                                                          | 否             | 初始展示的资源索引。                                         | 默认展示第一个资源。                                         |
| `bgOpacity`       | Number  | `0.5`                                                        | 否             | 画廊背景的透明度，取值范围 `0` 到 `1`。                      | 控制背景的透明度，`0` 为完全透明，`1` 为完全不透明。         |
| `showArrow`       | Boolean | `true`                                                       | 否             | 是否显示左右箭头。                                           | 设置为 `false` 时隐藏左右箭头。                              |
| `showNavigation`  | Boolean | `false`                                                      | 否             | 是否显示底部导航。                                           | 显示或隐藏底部导航按钮。                                     |
| `navigationStyle` | Object  | `{ size: 20, color: '#fff', activeColor: '#008000', spacing: 5 }` | 否             | 定义底部导航按钮的样式，包括大小、颜色、激活颜色和按钮间距。 | `showNavigation` 启用后才有效。`size`：按钮大小，`color`：按钮默认颜色，`activeColor`：激活按钮的颜色，`spacing`：按钮间距。 |
| `useChanged`      | Boolean | `false`                                                      | 否             | 是否触发 `changed` 事件回调，传递当前索引。                  | 设置为 `true` 后，`@changed` 事件将被触发，外部可监听索引变化。 |

## 方法说明

- `gotoSlide(index)`：跳转到指定索引的资源。
- `manageSlide(isPlay)`：控制当前资源的播放状态。`isPlay` 为 `true` 时播放，`false` 时暂停。

## 事件

- `@changed`：当当前资源的索引发生变化时触发，传递当前索引作为参数。

## 运行时

在运行时，组件会根据提供的图像数据初始化每个图片或视频的尺寸，并支持点击导航、手势操作和自动播放等功能。

## 样式自定义

通过 `navigationStyle` 属性可以自定义底部导航按钮的样式，支持自定义大小、颜色、间距等设置。

```
js复制编辑{
  size: 30,           // 按钮大小
  color: 'white',     // 按钮颜色
  activeColor: 'red', // 激活按钮的颜色
  spacing: 10         // 按钮之间的间距
}
```

## 注意事项

1. 视频自动播放可能需要用户交互才能生效，特别是在移动设备上。
2. 确保图片和视频的 URL 可访问，避免加载失败。
3. `images` 数组中的每个项必须包含有效 `src` 、和 `type` 字段，`type` 只能是 `image` 或 `video`； `width` 、 `height`，字段必须有，数值后续会有对应更新。