fex-swiper

Swiper

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

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

文档

• 基本用法
• 数据类型
  • Transition
  • Page
• 配置选项
• 事件
• API
  • swipeTo
  • swipePrev
  • swipeNext
  • getCurrentIndex
  • on
  • off
• 贡献代码
  • 技术栈
  • 目录结构
  • 开发步骤

基本用法

只需三步即可完成：

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

   1. 在 release 页面下载构建好的 js 和 css；
   2. 通过 npm 或 yarn 安装，命令 npm install fex-swiper 或 yarn 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 定义了两个数据类型: Transition 和 Page，Transition 用于描述翻页过渡动画，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);

参数

• transition: [可选]Transition, 翻页动画，若未指定，则使用当前翻页效果。

示例

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

swipeNext

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

语法

swiper.swipeNext(transition);

参数

• transition: [可选]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。