DOCSEARCHbyAlgolia
Submit Docs

zebra-swiper Documentation

website·Indexed 32 days ago

https://swiper.zebraui.com

A high-performance carousel component library designed for multi-terminal use, supporting complex 3D carousel effects. Built for Vue 3, it includes features such as virtual nodes for performance optimization, automatic playback, and various 3D modules like Cube, Coverflow, and Creative effects. The library provides core components like z-swiper and z-swiper-item, along with a modular system for pagination, scrollbars, and navigation.

Tokens
22.8K
Snippets
128
Records
146
Agent score
57%

What's inside zebra-swiper

  1. Overview of zebra-swiper capabilities

    zebra-swiper is a high-performance carousel component library designed for multi-platform use (Mini-programs, H5, and App). It supports complex 3D carousel effects and provides a modular design for minimal code size. Key features include:

    • Indicators & Pagination: Visual status tracking and direct page switching.
    • Bidirectional Control: Linking multiple carousel components together.
    • Infinite Loop & Autoplay: Seamless continuous playback and automatic transitions.
    • Navigation: Support for thumbnails and scrollbars.
    • Creative Customization: A creative feature allowing developers to build unique carousel expressions.
    • Extensibility: Ability to integrate custom plugin modules by listening to specific events.

  2. Swiper read-only state properties

    These properties provide real-time information about the Swiper instance and cannot be modified directly.
    PropertyDescription
    activeIndexThe index of the currently active slide.
    realIndexThe actual index of the active item (used specifically with loop and virtual modes).
    animatingBoolean indicating if a transition animation is currently running.
    clickedIndexThe index of the last slide that was clicked.
    isBeginningBoolean indicating if the swiper is at the first position.
    isEndBoolean indicating if the swiper is at the last position.
    progressThe current progress of the swiper (value between 0 and 1).
    translateThe current CSS translate value.
    widthThe current width of the swiper container.
    heightThe current height of the swiper container.

  3. Implement thumbnail navigation with Zebra UI Swiper

    The Thumbnails module allows you to create a thumbnail navigation bar for a main carousel. This requires two separate swiper instances: a main swiper and a thumbnail swiper. The main swiper must be linked to the thumbnail swiper instance via the thumbs configuration property. Note that thumbnail styling (such as active slide opacity) must be managed by the developer.
    <script setup>
import { ref } from 'vue'
import { Thumb, FreeMode } from '@zebra-ui/swiper/modules'

const list = ref(Array.from({ length: 5 }).map((_, index) => ({ text: `Slide ${index + 1}`, id: index + 1 })))
const modules = ref([Thumb, FreeMode])
const swiperInstance = ref({})

const onSwiper = (swiper, name) => {
  swiperInstance.value[name] = swiper
}
</script>

<template>
  <!-- Main Swiper -->
  <z-swiper
    :modules="modules"
    :thumbs="{ swiper: swiperInstance['thumbs'] }"
  >
    <z-swiper-item v-for="item in list" :key="item.id">
      <div>{{ item.text }}</div>
    </z-swiper-item>
  </z-swiper>

  <!-- Thumbnail Swiper -->
  <div class="thumb-swiper">
    <z-swiper
      :modules="modules"
      watch-slides-progress
      :spaceBetween="10"
      :slidesPerView="4"
      freeMode
      :custom-style="{height:'100px'}"
      @swiper="onSwiper($event, 'thumbs')"
    >
      <z-swiper-item v-for="item in list" :key="item.id">
        <div style="height: 100px">{{ item.text }}</div>
      </z-swiper-item>
    </z-swiper>
  </div>
</template>

<style lang="scss">
.thumb-swiper {
    .swiper-slide { opacity: 0.4; }
    .swiper-slide-thumb-active { opacity: 1; }
}
</style>

  4. Implement Scrollbar in z-swiper

    To enable the built-in scrollbar, add the scrollbar prop to z-swiper, include the Scrollbar module in the :modules array, and import the corresponding SCSS styles.
    <template>
  <z-swiper grabCursor scrollbar :modules="modules">
    <z-swiper-item v-for="item in list" :key="item.id">
      <DemoItem :text="item.text"></DemoItem>
    </z-swiper-item>
  </z-swiper>
</template>

<script setup>
import { ref } from 'vue'
import { Scrollbar } from '@zebra-ui/swiper/modules'

const list = ref([
  { text: 'Slide 1', id: 1 },
  { text: 'Slide 2', id: 2 },
])
const modules = ref([Scrollbar])
</script>

<style lang="scss">
@use "@zebra-ui/swiper/modules/scrollbar/scrollbar.scss";
</style>

  6. Pass list data to z-swiper using v-model

    Starting from version 2.1.0, the z-swiper component requires the list of data to be passed via the v-model directive. This is a mandatory requirement to ensure the component can manage data operations correctly and support features like infinite looping. The data passed to v-model must match the list being iterated over in the z-swiper-item children.
    <z-swiper v-model="list">
  <z-swiper-item v-for="(item, index) in list" :key="index">
    <image class="image" :src="item" mode="aspectFill">
    </image>
  </z-swiper-item>
</z-swiper>

  7. Implement fade transition effect in Zebra UI Swiper

    To enable a soft fade transition between slides instead of the traditional sliding effect, set the effect prop to 'fade' and provide the EffectFade module to the :modules prop.
    <z-swiper grabCursor effect="fade" :modules="modules">
  <z-swiper-item v-for="item in list" :key="item.id">
    <DemoItem :text="item.text"></DemoItem>
  </z-swiper-item>
</z-swiper>

  8. Handle infinite loop data in version 2.1.2

    In version 2.1.2, the loop (infinite loop) mode was updated to no longer require manual data concatenation. If you upgrade to this version, you should remove any manual data splicing previously used to achieve the loop effect.

  9. Import ZebraSwiper components in uni-app

    There are three ways to import ZebraSwiper components. For cross-platform development, easycom is recommended. Note that for Mini Programs, you must import the .vue files directly rather than the JS entry point.
    // pages.json (easycom configuration)
{
  "easycom": {
    "custom": {
      "^z-(.*)": "@zebra-ui/swiper/components/z-$1/z-$1.vue"
    }
  },
  "pages": [...]
}
    <!-- Local import in index.vue -->
<script setup>
// Web only
import { ZSwiper, ZSwiperItem } from '@zebra-ui/swiper'

// Mini Programs
import ZSwiper from '@zebra-ui/swiper/components/z-swiper/z-swiper.vue'
import ZSwiperItem from '@zebra-ui/swiper/components/z-swiper-item/z-swiper-item.vue'
</script>
    // Global registration in main.js
import { createSSRApp } from 'vue'

// Web only
import { ZSwiper, ZSwiperItem } from '@zebra-ui/swiper'

// Mini Programs
import ZSwiper from '@zebra-ui/swiper/components/z-swiper/z-swiper.vue'
import ZSwiperItem from '@zebra-ui/swiper/components/z-swiper-item/z-swiper-item.vue'

import App from './App.vue'
export function createApp() {
  const app = createSSRApp(App)
  app.component('ZSwiper', ZSwiper) 
  app.component('ZSwiperItem', ZSwiperItem) 
  return { app }
}

  10. Trigger animations in zebra-swiper using state classes

    You can create visual effects and animations in zebra-swiper by targeting the specific class names that Swiper applies to slides based on their current state. Because these animations are triggered by class changes, they are high-performance but cannot be dynamically adjusted in real-time based on the user's finger movement (progress) during a swipe.

    Key state classes available:

    • .swiper-slide-active: The currently active slide.
    • .swiper-slide-prev: The slide immediately preceding the active slide.
    • .swiper-slide-next: The slide immediately following the active slide.

  11. Implement 3D Coverflow effect in Zebra UI Swiper

    The Coverflow effect creates a 3D rotating card stack appearance. To use it, set the effect prop to coverflow and provide the EffectCoverflow module. For the best experience, it is recommended to use this effect in combination with carousel blocks, centeredSlides, and a slidesPerView value greater than 1.
    <z-swiper
  grabCursor
  effect="coverflow"
  centeredSlides
  :slidesPerView="3"
  :coverflowEffect="{
      rotate: 50,
      stretch: 0,
      depth: 100,
      modifier: 1,
      slideShadows: true,
    }"
  :modules="modules"
>
  <z-swiper-item v-for="item in list" :key="item.id">
    <DemoItem :text="item.text"></DemoItem>
  </z-swiper-item>
</z-swiper>

  12. Critical requirements for using loop with v-for

    When using the loop feature, you must provide a unique key for each item in the v-for loop.

    Constraints:

    • Do NOT use the array index as the key; this will cause intermittent flickering because the swiper cannot correctly match nodes during movement.
    • It is strongly recommended to use an array of objects where each object has a unique identifier (e.g., item.id).
    • If using strings, ensure every string in the array is unique.