Swiper配置选项、方法、函数详解笔录（一）

青春..荒唐

浏览: 974551 次
性别:

最近访客更多访客>>

lliiqiang

nbczw8750

kingkongzmc

lokily

博主相关

博客

微博

相册

留言

关于我

文章分类

社区版块

存档分类

博客分类：

前端插件

前端插件

下面根据Swiper4的API文档，总结下Swiper4.x的配置选项，包括全部配置选项、方法、函数

本章内容会过长，根据内容列表查找相应配置选项即可快速找到

【版本对比】

Swiper4的API变化：

Swiper4将组件的相关选项整合起来了，并且修改了回调函数获取swiper实例的方式为this关键词

【组件列表】

Navigation 分页器 Pagination 按钮

Scrollbar 滚动条 Autoplay 自动切换

Lazy Loading 延迟加载图片 Zoom 缩放

Keyboard Control 键盘 Mousewheel Control 鼠标

Virtual Slides 虚拟块 Hash Navigation 锚导航

History Navigation 历史导航 Controller 相互控制

Accessibility 障碍使用辅助

过渡类：

Fade Effect 渐变过渡 Coverflow Effect 行进翻转过渡

Flip Effect 翻转过渡 Cube Effect 方块过渡

【内容列表】

（1）Swiper初始化；

（2）Swiper一般基础选项；

（3）网格分布；

（4）free模式/抵抗反弹

（5）环路 / 循环Loop

（6）progress进度

（7）Clicks点击

（8）Touches（触发条件）

【详解】

（1）Swiper初始化

语法：new Swiper(swiperContainer容器, parameters参数)，用于初始化一个Swiper，返回初始化后的Swiper实例

swiperContainer容器 : Swiper容器的css选择器，HTMLElement or string，必选；例如“.swiper-container”

parameters参数 : Swiper的个性化配置，object类型，可选

一个页面中引用多个Swiper，可以给每个容器加上ID或Class区分，要保留默认的类名swiper-container

例如：

<div class="swiper-container" id="swiper1">....<div>
<div class="swiper-container" id="swiper2">....<div>
<div class="swiper-container" id="swiper3">....<div>
<script>
   var swiper1 = new Swiper('#swiper1');
   var swiper2 = new Swiper('#swiper2');
   var swiper3 = new Swiper('#swiper3');
</script>

案例：效果中用css给slide设置了高度和背景色

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>swiper测试</title>
    <link rel="stylesheet" href="./swiper.min.css">
    <link rel="stylesheet" href="./animate.min.css">
    <style type="text/css">
        .one{
            width: 100%;
            height: 300px;
            background-color: #00bcd4;
        }
    </style>
</head>
<body>
<div class="swiper-container" id="oneContainer">
    <div class="swiper-wrapper">
        <div class="swiper-slide one">slider1</div>
        <div class="swiper-slide one">slider2</div>
        <div class="swiper-slide one">slider3</div>
    </div>
</div>
<hr>
<div class="swiper-container" id="twoContainer">
    <div class="swiper-wrapper">
        <div class="swiper-slide one">slider1</div>
        <div class="swiper-slide one">slider2</div>
        <div class="swiper-slide one">slider3</div>
    </div>
</div>
<script src="./swiper.min.js"></script>
<script src="./swiper.animate.min.js"></script>
<script>
    var mySwiperOne = new Swiper('#oneContainer', {
        autoplay: true,//可选选项，自动滑动
    });
    var mySwiperTwo = new Swiper('#twoContainer', {
        autoplay: true,//可选选项，自动滑动
    })
</script>
</body>
</html>

（2）Swiper一般基础选项

注意：基础设置的数据类型，string类型的值要用双引号""

①initialSlide（初始化幻灯片）类型：number 默认：0

例如：设置initialSlide = 2后，Swiper初始化时activeSlide成了第三个

②direction（滑动方向）类型：string 默认：horizontal水平

例如：可设置水平(horizontal)或垂直(vertical)

③speed（切换速度）类型：number 默认：300ms

slider自动滑动开始到结束的时间（单位ms），也是触摸滑动时释放至贴合的时间

④grabCursor（抓住光标）类型：boolean 默认：false

设置为true时，鼠标覆盖Swiper时指针会变成手掌形状，拖动时指针会变成抓手形状。（根据浏览器形状有所不同）

⑤parallax（视差）类型：boolean 默认：false

设置为true开启视差效果，效果可以应用于container或slide的子元素

效果列表：

1.视差位移变化

在所需要的元素上增加data-swiper-parallax属性（与Swiper切换方向相同）或data-swiper-parallax-x （x方向） data-swiper-parallax-y（y方向）

data-swiper-parallax接受两种类型的参数

number（单位：px），如-300，从右边300px进入左边出去；

percentage（百分比），移动距离=该元素宽度 * percentage

2.透明度变化

在所需要的元素上增加data-swiper-parallax-opacity属性。可选值0-1，如0.5，从半透明进入半透明出去

3.缩放变化

在所需要的元素上增加data-swiper-parallax-scale属性。可选值如0.5，从一半大小进入一半大小出去

4.持续时间

还可通过data-swiper-parallax-duration设定视差动画持续时间（ms）。默认值是Swiper的speed，与切换时间同步。

注意：设定透明度或缩放必须同时设定位移，否则无效

<div data-swiper-parallax="0" data-swiper-parallax-opacity="0.5" >透明度变化</div>

案例：

<div class="swiper-container">
<div style="background-image:url(/img/Parallax.jpg)" data-swiper-parallax="-23%" 
            data-swiper-parallax-duration="3000"></div>
    <div class="swiper-wrapper">
       <div class="swiper-slide">
            <div class="title" data-swiper-parallax="-100">从右边100px开始进入</div>
            <div class="subtitle" data-swiper-parallax="-200">从右边200px开始进入</div>
            <div class="text" data-swiper-parallax="-300" 
                              data-swiper-parallax-duration="600">
              <p>从右边300px开始进入，时间600ms</p>
            </div>
            <div data-swiper-parallax="0" data-swiper-parallax-opacity="0.5">
                  透明度变化</div>
            <div data-swiper-parallax-scale="0.15" >缩放变化</div>
        </div>
    </div>
</div>
</div>
<script language="javascript"> 
    var mySwiper = new Swiper('.swiper-container',{
            parallax : true,
    })
</script>

⑥setWrapperSize（设置包装大小）类型：boolean 默认：false

Swiper使用flexbox布局(display: flex)，开启这个设定会在Wrapper上添加等于slides相加的宽或高，在对flexbox布局的支持不是很好的浏览器中可能需要用到

<script> 
var mySwiper = new Swiper('.swiper-container',{
  setWrapperSize :true,
})
//获取全部slide相加(wrapper)的宽度
console.log(mySwiper.$wrapperEl.css('width'));
</script>

⑦virtualTranslate（虚拟位移）

虚拟的位移。当你启用这个参数，Slide不会移动，但是Swiper还是在运行，例如progress，active-slide，各种回调等。当你想自定义一些slide切换效果时可以用。例如配合上progress。

启用这个选项时slideChange和transition等事件有效（与Swiper3.x不同）；还可以用来使Swiper的滑动停止（锁定）

效果演示：滑动Swiper，slide没移动，但是swiper切换了

<script> 
var mySwiper = new Swiper('.swiper-container',{
  virtualTranslate : true,
})
//mySwiper.params.virtualTranslate=true;
</script>

⑧width宽度强制Swiper的宽度(px)，当你的Swiper在隐藏状态下初始化时才用得上，这个参数会使自适应失效

类型：number

<script> 
var mySwiper = new Swiper('.swiper-container',{
  direction: "horizontal",
  width: 800, //你的slide宽度
  //全屏  width: window.innerWidth,
})
</script>

⑨height高度强制Swiper的高度(px)，当你的Swiper在隐藏状态下初始化时且切换方向为垂直才用得上，这个参数会使自适应失效

类型：number

<script>
var mySwiper = new Swiper('.swiper-container', {
  direction: 'vertical',
  height: 300,//你的slide高度
  //全屏  height : window.innerHeight,
}) 
</script>

⑩roundLengths（范围长度）类型：boolean 默认：false

设定为true将slide的宽和高取整(四舍五入)以防止某些分辨率的屏幕上文字或边界(border)模糊

例如在1440宽度设备上，当你设定slide宽为76%时，则计算出来结果为1094.4，开启后宽度取整数1094

<script> 
var mySwiper = new Swiper('.swiper-container',{
  roundLengths : true, 
})
</script>

⑪breakpoints（断点）类型：object

断点设定：根据屏幕宽度设置某参数为不同的值，类似于响应式布局的media screen

只有部分不需要变换布局方式和逻辑结构的参数支持断点设定，如slidesPerView视图、slidesPerGroup组、 spaceBetween间隔，而像slidesPerColumn列、loop循环、direction方向、effect效果等则无效

<script>
var swiper = new Swiper('.swiper-container', {
  slidesPerView: 4,
  spaceBetween: 40,
  breakpoints: { 
    320: {//当宽度小于等于320
      slidesPerView: 1,
      spaceBetween: 10
    },
    480: { //当宽度小于等于480
      slidesPerView: 2,
      spaceBetween: 20
    },
    640: {//当宽度小于等于640
      slidesPerView: 3,
      spaceBetween: 30
    }
  }
})
</script>

⑫autoHeight（自动高度）类型：boolean 默认：false

设置为true时，wrapper和container会随着当前slide的高度而发生变化

<script>
var swiper = new Swiper('.swiper-container', {
  autoHeight: true, //高度随内容变化
});
</script>

⑬uniqueNavElements（独特导航元素）类型：boolaen 默认：true

当控制组件放在container外面的时候，需要用到。

默认为true时，仅本swiper的container内的分页器有效，设置为false后，container以外的分页器也生效了

案例：

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
  pagination: {
    el: '.swiper-pagination',
  },
  uniqueNavElements: false,
})
</script>

⑭nested（嵌套）类型：boolean 默认：false

用于嵌套相同方向的swiper时，当切换到子swiper时停止父swiper的切换。

请将子swiper的nested设置为true，由于需要在slideChangeEnd时判断作用块，因此快速滑动时这个选项无效。

同方向的swiper嵌套例子，不要连续快速切换

<script> 
var mySwiper = new Swiper('#swiper-container1')//父swiper
var mySwiper2 = new Swiper('#swiper-container2',{//子swiper
  nested:true,
  resistanceRatio: 0,//阻力比
})
</script>

⑮watchOverflow（监视溢出）类型：boolean 默认：false

当没有足够的slide切换时，例如只有1个slide（非loop），swiper会失效且隐藏导航等。默认不开启这个功能

<div class="swiper-container">
	<div class="swiper-wrapper">
		<div class="swiper-slide blue-slide">
			slider1</div>
	</div>
	<div class="swiper-pagination"></div>
	<div class="swiper-button-prev"></div>
	<div class="swiper-button-next"></div>
	<div class="swiper-scrollbar"></div>
</div>
<script> 
var mySwiper = new Swiper('.swiper-container',{
  watchOverflow: true,//因为仅有1个slide，swiper无效
  navigation: {
    nextEl: '.swiper-button-next',//自动隐藏
    prevEl: '.swiper-button-prev',//自动隐藏
  },
  pagination: {
    el: '.swiper-pagination',//自动隐藏
  },
  scrollbar: {
    el: '.swiper-scrollbar',//自动隐藏
  },
})
</script>

⑯runCallbacksOnInit（在Init上运行回调）类型：boolean 默认：true

如果你的初始化slide不是第一个(例initialSlide:2)或者设置了loop: true，那么初始化时会触发一次 [Transition/SlideChange] [Start/End] 回调函数，如果不想触发，设置为false。

案例：每换一张，执行一次回调（配置无效？！！！）

⑰on 注册事件，Swiper4.0开始使用关键词this指代Swiper实例类型：object

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container', {
  on: {
    slideChange: function () {
      console.log(this.activeIndex);
    },
  },
};
//或者
var mySwiper = new Swiper('.swiper-container');
mySwiper.on('slideChange', function () {
  //...
});
</script>

⑱init（初始化）类型：boolean 默认：false

当你创建一个Swiper实例时是否立即初始化；如果禁止了，可以稍后使用mySwiper.init()来初始化。

案例：6秒后初始化

var mySwiper = new Swiper('#oneContainer', {
        init:false,
        autoplay: true,//可选选项，自动滑动
        initialSlide:2,//初始化幻灯片首个
    });
    setTimeout(function(){
        mySwiper.init();//现在才初始化
    },6000)

⑲preloadImages（预加载图像）类型：boolean 默认：true

默认为true，Swiper会强制加载所有图片

⑳updateOnImagesReady（更新图像就绪）类型：boolean 默认：true

当所有的内嵌图像（img标签）加载完成后Swiper会重新初始化。使用此选项需要先开启preloadImages: true

（3）Swiper网格分布

①centeredSlides（居中幻灯片）类型：boolean 默认：false

设定为true时，active slide会居中，而不是默认状态下的居左

②slidesPerView（每个视图幻灯片）类型：number 默认：1

设置slider容器能够同时显示的slides数量(carousel模式)

可以设置为数字（可为小数，小数不可loop），或者 'auto'则自动根据slides的宽度来设定数量

loop模式下如果设置为'auto'还需要设置另外一个参数loopedSlides（成环幻灯片）

③slidesPerGroup（每组幻灯片数量）类型：number 默认：1

在carousel mode（轮播）下定义slides的数量多少为一组。例如为3时，切换时直接3个3个切换

④spaceBetween（空间间距）类型：number 默认：0

在slide之间设置距离（单位px / %）

注意：若为%，则是按container的百分比，且百分比需加""引号

⑤slidesPerColumn（幻灯片每列）类型：number 默认：1

多行布局里面每列的slide数量，例slidesPerColumn为2时，每行有两列slider

⑥slidesPerColumnFill（幻灯片每列填充）类型：string 默认：column（列）

多行布局中以什么顺序填充：

'column'（列） 'row'（行）

1 3 5 或者 1 2 3

2 4 6 4 5 6

⑦slidesOffsetBefore（幻灯片前移偏移）类型：number 默认：0

设定slide与左边框的预设偏移量（单位px）

⑧slidesOffsetAfter（幻灯片前移偏移）类型：number 默认：0

设定slide与右边框的预设偏移量（单位px）

（4）free模式/抵抗反弹

①freeMode（自由模式）类型：boolean 默认：false普通模式

普通模式：slide滑动时只滑动一格，并自动贴合wrapper；

free模式：设置为true则变为free模式，slide会根据惯性滑动可能不止一格且不会贴合

②freeModeMomentum（惯性 / 惯量）类型：boolean 默认：true惯性模式

true模式：自由模式动量，释放slide之后继续惯性滑动

free模式：若设置为false则关闭动量，释放slide之后立即停止不会滑动

③freeModeMomentumRatio（惯性比）类型：number 默认：1s

设置的值越大，惯性越大，当释放slide时的滑动时间越长

④freeModeMomentumVelocityRatio（惯性速度比）类型：number 默认：1

free模式惯性速度，设置越大，释放后滑得越快

⑤freeModeMomentumBounce（动量反弹）类型：boolean 默认：true

false时禁用free模式下的动量反弹，slides通过惯性滑动到边缘时，无法反弹。注意与resistance（手动抵抗）区分

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
freeMode : true,
freeModeMomentumBounce : false,
})
</script>

⑥resistance（抵抗性）类型：boolean 默认：true

边缘抵抗，即当swiper已经处于第一个或最后一个slide时，继续拖动Swiper会离开边界，释放后弹回。边缘抵抗就是拖离边界时的抵抗力。值为false时禁用，将slide拖离边缘时完全没有抗力。

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
resistance : false,//完全没有边缘抵抗力
})
</script>

【拓展】：抵抗率

resistanceRatio（抵抗率）类型：number 默认：0.85

边缘抵抗力的大小比例，值越小抵抗越大越难将slide拖离边缘，0时完全无法拖离

⑦freeModeMomentumBounceRatio（惯性反弹比）类型：number 默认：1

值越大产生的边界反弹效果越明显，反弹距离越大

⑧freeModeSticky（自由模式粘滞）类型：boolean 默认：false

使得自由模式也能自动贴合

⑨freeModeMinimumVelocity（自由模式最小速度）类型：number 默认：0.02

触发自由模式惯性的最小触摸速度（px/ms），低于这个值不会惯性滑动

案例：设置为1后需要触摸很快才能产生惯性

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
freeMode : true,//开启自由模式
freeModeMinimumVelocity : 1,//最小触摸速度
})
</script>

（5）环路 / 循环Loop

①loop（循环）类型：boolean 默认：false

设置为true 则开启loop循环模式

loop模式：会在原本slide前后复制若干个slide(默认一个)并在合适的时候切换，让Swiper看起来是循环的，并且loop模式在与free模式同用时会产生抖动，因为free模式下没有复制slide的时间点

②loopAdditionalSlides（循环其他幻灯片）类型：number 默认：0

loop模式下会在slides前后复制若干个slide,，前后复制的个数不会大于原总个数。

默认为0，前后各复制1个。0,1,2 --> 2,0,1,2,0

例：取值为1，0,1,2 --> 1,2,0,1,2,0,1

例：取值为2或以上，0,1,2 --> 0,1,2,0,1,2,0,1,2

③loopedSlides（成环幻灯片）类型：number 默认：1

在loop模式下使用slidesPerview:'auto'，还需使用该参数设置所要用到的loop个数(一般设置为本来slide的个数)

④loopFillGroupWithBlank（带空白的循环填充组）类型：boolean 默认：false

在loop模式下，为group填充空白slide；在最后一个slide后面填充了一个空白的slide

（6）progress进度

①watchSlidesProgress（查看幻灯片进度）类型：boolean 默认：false

开启这个参数来计算每个slide的progress(进度、进程)，Swiper的progress无需设置即开启。

对于slide的progress属性，活动的那个为0，其他的依次减1。例：如果一共有6个slide，活动的是第三个，从第一个到第六个的progress属性分别是：2、1、0、-1、-2、-3。

对于swiper的progress属性，活动的slide在最左（上）边时为0，活动的slide在最右（下）边时为1，其他情况平分。例：有6个slide，当活动的是第三个时swiper的progress属性是0.4，当活动的是第五个时swiper的progress属性是0.8。

swiper的progress其实就是wrapper的translate值的百分值，与activeIndex等属性不同，progress是随着swiper的切换而不停的变化，而不是在某个时间点突变。

②watchSlidesVisibility（幻灯片可见性）类型：boolean 默认：false

开启watchSlidesVisibility选项前需要先开启watchSlidesProgress，如果开启了watchSlidesVisibility，则会在每个可见slide增加一个classname，默认为'swiper-slide-visible'

（7）Clicks点击

①preventClicks（阻止点击）类型：boolean 默认：true

当触摸拖拽时阻止默认事件（preventDefault），用于防止触摸拖拽时触发链接跳转

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
preventClicks : false,//默认true
})
</script>

②preventClicksPropagation（阻止点击传播/冒泡）类型：boolean 默认：true

阻止click冒泡，拖动Swiper时阻止click事件

案例：拖动释放时不会输出信息

<div class="swiper-slide" onclick="alert('你点了Swiper')">
<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
preventLinksPropagation : false,
})
</script>

③slideToClickedSlide（点击过渡）类型：boolean 默认：false

若设置为true，则点击slide会过渡到这个slide幻灯片

注意：一般适用于设置了slidesPerView（每个视图幻灯片）属性的幻灯片

var mySwiper = new Swiper('#oneContainer', {
        loop:true,
        slideToClickedSlide:true,
        centeredSlides : true,
        slidesPerView : 3,
});

（8）Touches（触发条件）

①touchRatio（触摸比率）类型：number 默认：1

触摸距离与slide滑动距离的比率

案例：设置为0.5后slide滑动距离只有触摸距离的一半，变得难以滑动，缓慢拖动查看效果

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
touchRatio : 0.5,
})
</script>

②simulateTouch（模拟触摸）类型：boolean 默认：true

默认为true，Swiper接受鼠标点击、拖动；设置为false的话鼠点击、标拖动失效

③allowTouchMove（允许触摸移动）类型：boolean 默认：true

值为false时，slide无法拖动，只能使用扩展API函数。例如slideNext() 或slidePrev()或slideTo()等改变slides滑动。等同于Swiper3.x 的 onlyExternal

<script language="javascript"> 
  var mySwiper = new Swiper('.swiper-container',{
    allowTouchMove: false,
    navigation: {
      prevEl: '.swiper-button-prev',
      nextEl: '.swiper-button-next',
    },
  })
  //开启拖动 mySwiper.allowTouchMove= true;
  //关闭拖动 mySwiper.allowTouchMove= false;
</script>

④followFinger（根据手势）类型：boolean 默认：true

如设置为false，拖动slide时它不会动，当你释放时slide才会切换

案例：鼠标幻灯片不动，拖动完成后后释放鼠标或手指时，slide幻灯片滑动

⑤shortSwipes（短距离拖动）类型：boolean 默认：true

设置为false时，进行快速短距离的拖动无法触发Swiper

⑥longSwipes（长距离拖动）类型：boolean 默认：true

设置为false时，进行长时间长距离的拖动无法触发Swiper

⑦threshold（阈值/临界点）类型：number 默认：false

拖动的临界值（单位为px），如果触摸距离小于该值滑块不会被拖动

案例：必须拖动大于100px后slide才会开始移动

<script language="javascript"> 
var mySwiper = new Swiper('.swiper-container',{
threshold : 100,
})
</script>

⑧touchAngle（触摸角度）类型：number 默认：45

允许触发拖动的角度值。默认45度，即使触摸方向不是完全水平也能拖动slide

案例：设置了很小的允许拖动角度（10°）

⑨touchReleaseOnEdges（触摸边缘释放）类型：boolean 默认：false

当滑动到Swiper的边缘时释放滑动，可以用于同向Swiper的嵌套（移动端触摸有效）

<script> 
var mySwiper = new Swiper('.swiper-container',{
touchReleaseOnEdges:true,
})
</script>

【总结】

（1）鼠标悬停停止轮播、移开重新开始轮播

$('.swiper-slide').mouseenter(function () {
   mySwiper.autoplay.stop();
})
$('.swiper-slide').mouseleave(function () {
   mySwiper.autoplay.start();
})

（2）

今天先总结到这里，下次继续

【疑问点】

下面记下未搞定的几个配置

⑯runCallbacksOnInit（在Init上运行回调）类型：boolean 默认：true

分享到：

组合包Appserv搭建PHP环境教程 | swiper教程详解

2018-03-05 10:50
浏览 16774
评论(0)
分类:Web前端
查看更多

发表评论

您还没有登录,请您登录后再发表评论

最近访客更多访客>>

博主相关

文章分类

社区版块

存档分类

最新评论