mirror of
https://github.com/pengzhanbo/vuepress-theme-plume.git
synced 2026-04-23 10:58:13 +08:00
291 lines
7.4 KiB
Markdown
291 lines
7.4 KiB
Markdown
---
|
|
title: Swiper
|
|
icon: dashicons:images-alt2
|
|
createTime: 2025/10/08 22:00:22
|
|
permalink: /en/guide/components/swiper/
|
|
---
|
|
|
|
## Overview
|
|
|
|
Use the `<Swiper>` component to display image carousels on pages.
|
|
|
|
## Usage
|
|
|
|
To use this component, first manually install the `swiper` library:
|
|
|
|
::: npm-to
|
|
|
|
```sh
|
|
npm install swiper
|
|
```
|
|
|
|
:::
|
|
|
|
Then, manually import the `Swiper` component:
|
|
|
|
```md
|
|
<!-- Import in markdown -->
|
|
<script setup>
|
|
import Swiper from 'vuepress-theme-plume/features/Swiper.vue'
|
|
</script>
|
|
|
|
<!-- After importing, you can use it in markdown -->
|
|
<Swiper :items="['img_link1', 'img_link2']" />
|
|
```
|
|
|
|
Register as a global component:
|
|
|
|
```ts title=".vuepress/client.ts"
|
|
import Swiper from 'vuepress-theme-plume/features/Swiper.vue'
|
|
import { defineClientConfig } from 'vuepress/client'
|
|
|
|
export default defineClientConfig({
|
|
enhance({ app }) {
|
|
app.component('Swiper', Swiper)
|
|
},
|
|
})
|
|
```
|
|
|
|
Global components can be used in any other markdown file:
|
|
|
|
```md
|
|
<Swiper :items="['img_link1', 'img_link2']" />
|
|
```
|
|
|
|
<script setup lang="ts">
|
|
import { ref, onMounted } from 'vue'
|
|
import Swiper from 'vuepress-theme-plume/features/Swiper.vue'
|
|
|
|
const images = ref([])
|
|
|
|
async function fetchImage() {
|
|
const res = await fetch('https://api.pengzhanbo.cn/wallpaper/bing/zh/').then((res) => res.json())
|
|
images.value = res.map(item => ({
|
|
name: item.title,
|
|
link: item.url,
|
|
}))
|
|
}
|
|
|
|
if (!__VUEPRESS_SSR__) {
|
|
fetchImage()
|
|
}
|
|
</script>
|
|
|
|
**Example:**
|
|
|
|
<Swiper v-if="images.length" :items="images" />
|
|
|
|
## Props
|
|
|
|
| Name | Type | Default | Description |
|
|
| ----------------- | ---------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------- |
|
|
| items | `string \| { link: string; href?: string; alt?: string}[]` | `[]` | Image link array. When passing objects, `link` represents image URL, `href` represents navigation link, `alt` represents image description |
|
|
| width | `number \| string` | `100%` | Carousel area width |
|
|
| height | `number \| string` | `100%` | Carousel area height |
|
|
| mode | `'banner' \| 'carousel' \| 'broadcast'` | `'banner'` | Carousel mode: `banner`: banner; `carousel`: carousel; `broadcast`: information display |
|
|
| navigation | `boolean` | `true` | Whether to show navigation buttons |
|
|
| effect | `'slide' \| 'fade' \| 'cube' \| 'coverflow' \| 'flip' \| 'cards' \| 'creative'` | `'slide'` | Carousel effect |
|
|
| delay | `number` | `3000` | Carousel interval time. Only effective when `mode: 'banner'`. Unit: `ms` |
|
|
| speed | `number` | `300` | Animation duration. Unit: `ms` |
|
|
| loop | `boolean` | `true` | Whether to loop |
|
|
| pauseOnMouseEnter | `boolean` | `false` | Whether to pause carousel on mouse hover |
|
|
| swipe | `boolean` | `true` | Whether to enable gesture swiping |
|
|
|
|
For more props, refer to [Swiper Documentation](https://swiperjs.com/swiper-api#parameters)
|
|
|
|
## Reference Examples
|
|
|
|
### Preset Animation Effects
|
|
|
|
**cube:**
|
|
|
|
<Swiper v-if="images.length" :items="images" effect="cube" />
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper :items="images" effect="cube" />
|
|
```
|
|
|
|
:::
|
|
|
|
**fade:**
|
|
|
|
<Swiper v-if="images.length" :items="images" effect="fade" />
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper :items="images" effect="fade" />
|
|
```
|
|
|
|
:::
|
|
|
|
**coverflow:**
|
|
|
|
<Swiper v-if="images.length" :items="images" effect="coverflow" />
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper :items="images" effect="coverflow" />
|
|
```
|
|
|
|
:::
|
|
|
|
**flip:**
|
|
|
|
<Swiper v-if="images.length" :items="images" effect="flip" />
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper :items="images" effect="flip" />
|
|
```
|
|
|
|
:::
|
|
|
|
**cards:**
|
|
|
|
<Swiper v-if="images.length" :items="images" effect="cards" />
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper :items="images" effect="cards" />
|
|
```
|
|
|
|
:::
|
|
|
|
### Custom Animation Effects
|
|
|
|
**Example 1:**
|
|
|
|
<Swiper v-if="images.length" :items="images" effect="creative" :creativeEffect="{
|
|
prev: { shadow: true, translate: [0, 0, -400] },
|
|
next: { translate: ['100%', 0, 0] },
|
|
}" />
|
|
|
|
::: details View Code
|
|
|
|
```md
|
|
<Swiper :items="images" effect="creative" :creativeEffect="{
|
|
prev: { shadow: true, translate: [0, 0, -400] },
|
|
next: { translate: ['100%', 0, 0] },
|
|
}"
|
|
/>
|
|
```
|
|
|
|
:::
|
|
|
|
**Example 2:**
|
|
|
|
<Swiper v-if="images.length" :items="images" effect="creative" :creativeEffect="{
|
|
prev: { shadow: true, translate: [0, 0, -800], rotate: [180, 0, 0] },
|
|
next: { shadow: true, translate: [0, 0, -800], rotate: [-180, 0, 0] },
|
|
}" />
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper :items="images" effect="creative" :creativeEffect="{
|
|
prev: { shadow: true, translate: [0, 0, -800], rotate: [180, 0, 0] },
|
|
next: { shadow: true, translate: [0, 0, -800], rotate: [-180, 0, 0] },
|
|
}"
|
|
/>
|
|
```
|
|
|
|
:::
|
|
|
|
**Example 3:**
|
|
|
|
<Swiper v-if="images.length" :items="images" effect="creative" :creativeEffect="{
|
|
prev: { shadow: true, translate: ['-125%', 0, -800], rotate: [0, 0, -90] },
|
|
next: { shadow: true, translate: ['125%', 0, -800], rotate: [0, 0, 90] },
|
|
}" />
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper :items="images" effect="creative" :creativeEffect="{
|
|
prev: { shadow: true, translate: ['-125%', 0, -800], rotate: [0, 0, -90] },
|
|
next: { shadow: true, translate: ['125%', 0, -800], rotate: [0, 0, 90] },
|
|
}"
|
|
/>
|
|
```
|
|
|
|
:::
|
|
|
|
**Example 4:**
|
|
|
|
<Swiper v-if="images.length" :items="images" effect="creative" :creativeEffect="{
|
|
prev: { shadow: true, origin: 'left center', translate: ['-5%', 0, -200], rotate: [0, 100, 0] },
|
|
next: { origin: 'right center', translate: ['5%', 0, -200], rotate: [0, -100, 0] },
|
|
}" />
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper :items="images" effect="creative" :creativeEffect="{
|
|
prev: { shadow: true, origin: 'left center', translate: ['-5%', 0, -200], rotate: [0, 100, 0] },
|
|
next: { origin: 'right center', translate: ['5%', 0, -200], rotate: [0, -100, 0] },
|
|
}"
|
|
/>
|
|
```
|
|
|
|
:::
|
|
|
|
### Carousel
|
|
|
|
<Swiper
|
|
v-if="images.length"
|
|
:items="images"
|
|
mode="carousel"
|
|
:height="200"
|
|
:slides-per-view="3"
|
|
:space-between="20"
|
|
:speed="5500"
|
|
/>
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper
|
|
:items="images"
|
|
mode="carousel"
|
|
:height="200"
|
|
:slides-per-view="3"
|
|
:space-between="20"
|
|
:speed="5500"
|
|
/>
|
|
```
|
|
|
|
:::
|
|
|
|
### Information Display
|
|
|
|
<Swiper
|
|
v-if="images.length"
|
|
:items="images"
|
|
mode="broadcast"
|
|
:height="200"
|
|
:slides-per-view="3"
|
|
:space-between="20"
|
|
mousewheel
|
|
/>
|
|
|
|
:::details View Code
|
|
|
|
```md
|
|
<Swiper
|
|
:items="images"
|
|
mode="broadcast"
|
|
:height="200"
|
|
:slides-per-view="3"
|
|
:space-between="20"
|
|
mousewheel
|
|
/>
|
|
```
|
|
|
|
:::
|