{"id":30279846,"url":"https://github.com/fex-team/swiper","last_synced_at":"2025-08-16T14:35:33.249Z","repository":{"id":57234827,"uuid":"95543098","full_name":"fex-team/swiper","owner":"fex-team","description":"轻量的移动端 H5 翻页库","archived":false,"fork":false,"pushed_at":"2019-01-10T08:11:02.000Z","size":167,"stargazers_count":555,"open_issues_count":9,"forks_count":98,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-08-09T06:19:27.657Z","etag":null,"topics":["baidu","frontend","h5","mobile","swiper"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fex-team.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-27T09:45:26.000Z","updated_at":"2025-08-08T03:06:36.000Z","dependencies_parsed_at":"2022-09-07T09:51:29.164Z","dependency_job_id":null,"html_url":"https://github.com/fex-team/swiper","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/fex-team/swiper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fex-team%2Fswiper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fex-team%2Fswiper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fex-team%2Fswiper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fex-team%2Fswiper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fex-team","download_url":"https://codeload.github.com/fex-team/swiper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fex-team%2Fswiper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269706642,"owners_count":24462205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["baidu","frontend","h5","mobile","swiper"],"created_at":"2025-08-16T14:35:27.836Z","updated_at":"2025-08-16T14:35:33.188Z","avatar_url":"https://github.com/fex-team.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swiper\n[![Build Status](https://travis-ci.org/fex-team/swiper.svg?branch=master)](https://travis-ci.org/fex-team/swiper)\n[![Coverage Status](https://coveralls.io/repos/github/fex-team/swiper/badge.svg?branch=master)](https://coveralls.io/github/fex-team/swiper?branch=master)\n\n轻量的移动端 H5 翻页库，提供了必要的配置选项和 API，同时具有高性能的特点。目前百度 H5 运行时页面在使用。\n支持的功能：\n- 横向或竖向滑动\n- 循环翻页\n- 总体和页面级别过渡效果\n- 页面级别禁止滑动\n- 外部 API 调用\n- 完善的事件机制\n- 可扩展的过渡动画\n\n## 文档\n- [基本用法](#基本用法)\n- [数据类型](#数据类型)\n    - [Transition](#transition)\n    - [Page](#page)\n- [配置选项](#配置选项)\n- [事件](#事件)\n- [API](#api)\n    - [swipeTo](#swipeto)\n    - [swipePrev](#swipeprev)\n    - [swipeNext](#swipenext)\n    - [getCurrentIndex](#getcurrentindex)\n    - [on](#on)\n    - [off](#off)\n- [贡献代码](#贡献代码)\n    - [技术栈](#技术栈)\n    - [目录结构](目录结构)\n    - [开发步骤](#开发步骤)\n\n## 基本用法\n只需三步即可完成：\n1. 引入 js 和 css，可以按照下面两种方式之一进行：\n    1. 在 [release](https://github.com/fex-team/swiper/releases) 页面下载构建好的 js 和 css；\n    2. 通过 npm 或 yarn 安装，命令 `npm install fex-swiper` 或 `yarn add fex-swiper`，目的文件在 `dist` 目录下；\n\n2. 创建一个容器 `div`，注意：这个容器必须是有宽度和高度（如 100% 或者 650px）；\n```html\n\u003cdiv class=\"outer-container\"\u003e\u003c/div\u003e\n```\n\n3. 准备数据，创建 swiper。\n```javascript\nvar list = [{\n    content: '\u003ch1\u003e第 0 页\u003c/h1\u003e'\n}, {\n    content: '\u003ch1\u003e第 1 页\u003c/h1\u003e'\n}, {\n    content: '\u003ch1\u003e第 2 页\u003c/h1\u003e'\n}];\n\nvar swiper = new Swiper({\n    container: document.querySelector('.outer-container'),\n    data: list\n});\n```\n具体可以参考 [simple.html](https://github.com/fex-team/swiper/blob/master/examples/simple.html)\n\n## 数据类型\nSwiper 定义了两个数据类型: `Transition` 和 `Page`，`Transition` 用于描述翻页过渡动画，`Page` 用于描述页面。\n\n### Transition\n```javascript\n{\n    // 过渡动画名称，目前提供了 5 种过渡动画\n    name: 'slide' | 'rotate' | 'flip' | 'card' | 'fade'\n    // 过渡动画时长，单位为 ms\n    duration: Number\n    // 只允许滑动方向 1: 后向，-1: 前向，0:双向禁止滑动，默认为 undefined，即不限制任何方向的滑动\n    direction: 1 | -1 | 0\n}\n```\n\n### Page\n```javascript\n{\n    // 本页面内容，可以是 DOM 或者 string\n    content: DOM or string,\n    // 本页面翻页过渡动画\n    transition: Transition\n}\n```\n\n## 配置选项\n所有的配置项都是可选的\n\n配置项|类型|默认值|说明\n----|----|----|---\ncontainer           | `DOM` or `string` | document.body                     | swiper 的外层容器 \ndata                | [Page](#page)[]            | []                                |所有页面的数据    \ndebug               | boolean           | `false`                           | 是否开启调试模式    \nisVertical          | boolean           | `true`                            | 是否是垂直方向滑动\nisLoop              | boolean           | `false`                           |是否开启循环翻页 \nkeepDefaultClasses    | string[]          | []              | 保持默认行为的 class 名，详见[说明](#about-keepdefault)\ntransition          | [Transition](#transition)           | `{name: 'slide', duration: 800}`  | 翻页过渡动画，按照优先级取值，详见[优先级](#about-transition-priority)\n\n**关于 keepDefaultClasses 说明**\u003ca name=\"about-keepdefault\"\u003e\u003c/a\u003e\n\n为防止滑动事件中断，Swiper 默认阻止所有除了 `a`, `input`, `textarea`, `select` 以外的所有元素的滑动事件(mouseXXX, touchXXX)默认行为。但是在实际项目中，可能还有一些元素需要被排除在外（如微信中，长按图片会有识别二维码的响应，因此就需要将该图片的 className 放入该数组中），加入到 keepDefaultClasses 的元素及其 **后代元素** 均会被排除在外。因此 `keepDefaultClasses` 就是一个 **要保持默认响应的元素 class 的白名单**。\n\n**过渡效果优先级**\u003ca name=\"about-transition-priority\"\u003e\u003c/a\u003e\n\n`swipeTo` 函数设定的翻页效果 \u003e 当前页面的翻页效果 \u003e 全局的翻页效果。\n\n若高优先级已经设定，以高优先级的为准，若未设定，采用低一优先级的翻页效果。\n\n## 事件\u003ca name=\"swiper-events\"\u003e\u003c/a\u003e\nSwiper 提供了 7 个事件，按照滑动开始到结束的顺序介绍如下：\n\n事件名|触发时机\n----|----\nswipeStart          | 在页面开始滑动时触发\nswipeMoving         | 在页面滑动时触发\nswipeChanged        | 在翻页完成时触发\nswipeRestore        | 在回弹开始时触发\nswipeRestored       | 在回弹完成时触发\nactivePageChanged   | 下一页有变动时触发\ndestroy             | 销毁实例时触发\n\n其中，页面滑动有两个结果：**回弹**和**翻页**。\n\n回弹即页码没有变化，恢复原状。\n\n翻页即页码产生变化，翻到了下一页。\n\n## API\nSwiper 提供了 5 个接口供外部调用：\n\n函数名|作用\n----|----\nswipeTo | 翻到指定页面\nswipePrev | 翻到上一页\nswipeNext | 翻到下一页\non      | 监听事件\noff     | 取消监听事件\n\n### swipeTo\n`swipeTo` 函数用于将页面翻到指定页码（从 0 开始计），可以指定翻页过渡动画。不受页面禁止滑动配置选项的限制。\n\n#### 语法\n```javascript\nswiper.swipeTo(toIndex, transition);\n```\n#### 参数\n- `toIndex`: Number, 翻到的页码，从 0 开始计。\n- `transition`: \\[可选\\][Transition](#transition), 翻页动画，若未指定，则使用[当前翻页效果](#about-transition-priority)。\n\n#### 示例\n```javascript\nswiper = new Swiper();\n// 翻到第 0 页\nswiper.swipeTo(0);\n// 翻到第 3 页，以 rotate 过渡效果\nswiper.swipeTo(3, {name: 'rotate'});\n```\n\n### swipePrev\n`swipePrev` 函数用于将页面翻到上一页，可以指定翻页过渡动画。不受页面禁止滑动配置选项的限制。\n\n#### 语法\n```javascript\nswiper.swipePrev(transition);\n```\n#### 参数\n- `transition`: \\[可选\\][Transition](#transition), 翻页动画，若未指定，则使用[当前翻页效果](#about-transition-priority)。\n\n#### 示例\n```javascript\nswiper = new Swiper();\n// 翻到上一页，以默认效果\nswiper.swipePrev();\n```\n### swipeNext\n`swipeNext` 函数用于将页面翻到下一页，可以指定翻页过渡动画。不受页面禁止滑动配置选项的限制。\n\n#### 语法\n```javascript\nswiper.swipeNext(transition);\n```\n#### 参数\n- `transition`: \\[可选\\][Transition](#transition), 翻页动画，若未指定，则使用[当前翻页效果](#about-transition-priority)。\n\n#### 示例\n```javascript\nswiper = new Swiper();\n// 翻到下一页，以 flip 过渡效果\nswiper.swipeNext({name: 'flip'});\n```\n\n### getCurrentIndex\n`getCurrentIndex` 函数用于获取当前页面的序号（从 0 开始计）。\n\n#### 语法\n```javascript\nswiper.getCurrentIndex();\n```\n#### 参数\n- 无\n\n#### 示例\n```javascript\nswiper = new Swiper();\n// 获取当前页面序号\nswiper.getCurrentIndex();\n```\n\n### on \n`on` 函数用于监听事件。\n\n#### 语法\n```javascript\nswiper.on(eventName, listener);\n```\n#### 参数\n- `eventName`: string, swiper [事件](#swiper-events)。\n- `listener`: Function, 当所监听事件触发时，就会接收到通知并执行该函数，拥有 1 个参数 `event`。\n    - `event`: Object, 默认包含 `name` 属性，表示当前的事件名。\n\n#### 示例\n```javascript\nswiper = new Swiper();\n// 监听 swipeChanged 事件，会在页面完成翻页时触发\nswiper.on('swipeChanged', function (e) {\n    console.log(e.name + 'fired');\n});\n```\n\n### off\n`off` 函数用于取消监听事件，与 `on` 函数相反。取消监听后，不会接收到事件响应。\n\n#### 语法\n```javascript\nswiper.off(eventName, listener);\n```\n#### 参数\n- `eventName`: string, swiper [事件](#swiper-events)\n- `listener`: Function, 在 `on` 函数中传入的监听函数。\n    \n\n#### 示例\n```javascript\nswiper = new Swiper();\n// 取消监听 swipeChanged 事件\nswiper.off('swipeChanged', function (e) {\n    console.log(e.name + 'fired');\n});\n```\n\n## 贡献代码\n欢迎大家为 Swiper 共享代码，开始之前，可以了解一下 Swiper 的基本原理，见[这篇文章](http://fex.baidu.com/blog/2017/10/build-a-silky-smooth-slide-library)。\n\n### 技术栈\nTypeScript + Webpack + Jest\n\n### 目录结构\n├── docs 文档  \n├── examples 例子  \n├── index.html 开发用到的 demo  \n├── src 源码  \n│   ├── constant.ts 常量定义  \n│   ├── device.ts 统一设备  \n│   ├── easing.ts 缓动函数  \n│   ├── interface.ts 接口定义  \n│   ├── render.ts render 抽象类  \n│   ├── renders 支持的六种翻页效果  \n│   ├── swiper.css 样式文件  \n│   └── swiper.ts 主文件  \n└── tests 测试文件\n\n### 开发步骤\n1. Fork 代码至自己的代码库，并 clone 到本地；\n2. `yarn`，安装依赖包，主要是开发时用的；\n3. `yarn dev`，用到的文件是 `index.html`，开发时修改保存后，会实时将 TypeScript 编译为 Javascript；\n4. `yarn test`，运行测试用例，并输出代码覆盖率；\n5. 开发完成后，在 Github 上提交 Pull Request。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffex-team%2Fswiper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffex-team%2Fswiper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffex-team%2Fswiper/lists"}