Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Swiper

Build Status Coverage Status

轻量的移动端 H5 翻页库,提供了必要的配置选项和 API,同时具有高性能的特点。目前百度 H5 运行时页面在使用。 支持的功能:

  • 横向或竖向滑动
  • 循环翻页
  • 总体和页面级别过渡效果
  • 页面级别禁止滑动
  • 外部 API 调用
  • 完善的事件机制
  • 可扩展的过渡动画

文档

基本用法

只需三步即可完成:

  1. 引入 js 和 css,可以按照下面两种方式之一进行:

    1. release 页面下载构建好的 js 和 css;
    2. 通过 npm 或 yarn 安装,命令 npm install fex-swiperyarn add fex-swiper,目的文件在 dist 目录下;
  2. 创建一个容器 div,注意:这个容器必须是有宽度和高度(如 100% 或者 650px);

<div class="outer-container"></div>
  1. 准备数据,创建 swiper。
var list = [{
    content: '<h1>第 0 页</h1>'
}, {
    content: '<h1>第 1 页</h1>'
}, {
    content: '<h1>第 2 页</h1>'
}];

var swiper = new Swiper({
    container: document.querySelector('.outer-container'),
    data: list
});

具体可以参考 simple.html

数据类型

Swiper 定义了两个数据类型: TransitionPageTransition 用于描述翻页过渡动画,Page 用于描述页面。

Transition

{
    // 过渡动画名称,目前提供了 5 种过渡动画
    name: 'slide' | 'rotate' | 'flip' | 'card' | 'fade'
    // 过渡动画时长,单位为 ms
    duration: Number
    // 只允许滑动方向 1: 后向,-1: 前向,0:双向禁止滑动,默认为 undefined,即不限制任何方向的滑动
    direction: 1 | -1 | 0
}

Page

{
    // 本页面内容,可以是 DOM 或者 string
    content: DOM or string,
    // 本页面翻页过渡动画
    transition: Transition
}

配置选项

所有的配置项都是可选的

配置项 类型 默认值 说明
container DOM or string document.body swiper 的外层容器
data Page[] [] 所有页面的数据
debug boolean false 是否开启调试模式
isVertical boolean true 是否是垂直方向滑动
isLoop boolean false 是否开启循环翻页
keepDefaultClasses string[] [] 保持默认行为的 class 名,详见说明
transition Transition {name: 'slide', duration: 800} 翻页过渡动画,按照优先级取值,详见优先级

关于 keepDefaultClasses 说明

为防止滑动事件中断,Swiper 默认阻止所有除了 a, input, textarea, select 以外的所有元素的滑动事件(mouseXXX, touchXXX)默认行为。但是在实际项目中,可能还有一些元素需要被排除在外(如微信中,长按图片会有识别二维码的响应,因此就需要将该图片的 className 放入该数组中),加入到 keepDefaultClasses 的元素及其 后代元素 均会被排除在外。因此 keepDefaultClasses 就是一个 要保持默认响应的元素 class 的白名单

过渡效果优先级

swipeTo 函数设定的翻页效果 > 当前页面的翻页效果 > 全局的翻页效果。

若高优先级已经设定,以高优先级的为准,若未设定,采用低一优先级的翻页效果。

事件

Swiper 提供了 7 个事件,按照滑动开始到结束的顺序介绍如下:

事件名 触发时机
swipeStart 在页面开始滑动时触发
swipeMoving 在页面滑动时触发
swipeChanged 在翻页完成时触发
swipeRestore 在回弹开始时触发
swipeRestored 在回弹完成时触发
activePageChanged 下一页有变动时触发
destroy 销毁实例时触发

其中,页面滑动有两个结果:回弹翻页

回弹即页码没有变化,恢复原状。

翻页即页码产生变化,翻到了下一页。

API

Swiper 提供了 5 个接口供外部调用:

函数名 作用
swipeTo 翻到指定页面
swipePrev 翻到上一页
swipeNext 翻到下一页
on 监听事件
off 取消监听事件

swipeTo

swipeTo 函数用于将页面翻到指定页码(从 0 开始计),可以指定翻页过渡动画。不受页面禁止滑动配置选项的限制。

语法

swiper.swipeTo(toIndex, transition);

参数

  • toIndex: Number, 翻到的页码,从 0 开始计。
  • transition: [可选]Transition, 翻页动画,若未指定,则使用当前翻页效果

示例

swiper = new Swiper();
// 翻到第 0 页
swiper.swipeTo(0);
// 翻到第 3 页,以 rotate 过渡效果
swiper.swipeTo(3, {name: 'rotate'});

swipePrev

swipePrev 函数用于将页面翻到上一页,可以指定翻页过渡动画。不受页面禁止滑动配置选项的限制。

语法

swiper.swipePrev(transition);

参数

示例

swiper = new Swiper();
// 翻到上一页,以默认效果
swiper.swipePrev();

swipeNext

swipeNext 函数用于将页面翻到下一页,可以指定翻页过渡动画。不受页面禁止滑动配置选项的限制。

语法

swiper.swipeNext(transition);

参数

示例

swiper = new Swiper();
// 翻到下一页,以 flip 过渡效果
swiper.swipeNext({name: 'flip'});

getCurrentIndex

getCurrentIndex 函数用于获取当前页面的序号(从 0 开始计)。

语法

swiper.getCurrentIndex();

参数

示例

swiper = new Swiper();
// 获取当前页面序号
swiper.getCurrentIndex();

on

on 函数用于监听事件。

语法

swiper.on(eventName, listener);

参数

  • eventName: string, swiper 事件
  • listener: Function, 当所监听事件触发时,就会接收到通知并执行该函数,拥有 1 个参数 event
    • event: Object, 默认包含 name 属性,表示当前的事件名。

示例

swiper = new Swiper();
// 监听 swipeChanged 事件,会在页面完成翻页时触发
swiper.on('swipeChanged', function (e) {
    console.log(e.name + 'fired');
});

off

off 函数用于取消监听事件,与 on 函数相反。取消监听后,不会接收到事件响应。

语法

swiper.off(eventName, listener);

参数

  • eventName: string, swiper 事件
  • listener: Function, 在 on 函数中传入的监听函数。

示例

swiper = new Swiper();
// 取消监听 swipeChanged 事件
swiper.off('swipeChanged', function (e) {
    console.log(e.name + 'fired');
});

贡献代码

欢迎大家为 Swiper 共享代码,开始之前,可以了解一下 Swiper 的基本原理,见这篇文章

技术栈

TypeScript + Webpack + Jest

目录结构

├── docs 文档
├── examples 例子
├── index.html 开发用到的 demo
├── src 源码
│   ├── constant.ts 常量定义
│   ├── device.ts 统一设备
│   ├── easing.ts 缓动函数
│   ├── interface.ts 接口定义
│   ├── render.ts render 抽象类
│   ├── renders 支持的六种翻页效果
│   ├── swiper.css 样式文件
│   └── swiper.ts 主文件
└── tests 测试文件

开发步骤

  1. Fork 代码至自己的代码库,并 clone 到本地;
  2. yarn,安装依赖包,主要是开发时用的;
  3. yarn dev,用到的文件是 index.html,开发时修改保存后,会实时将 TypeScript 编译为 Javascript;
  4. yarn test,运行测试用例,并输出代码覆盖率;
  5. 开发完成后,在 Github 上提交 Pull Request。
You can’t perform that action at this time.