Touchslide 触屏轮播工具

GB.Touchslide 是支持鼠标、触摸屏和触控笔的轻量轮播工具。它提供水平与垂直平移、淡入淡出和缩放三类特效，并支持循环播放、自动播放、导航、分页、前后按钮及切换回调。

安装与引入

浏览器直接引入

<script src="https://cloud.m775.net/js/touchslide.js"></script>

npm 项目

npm i @gentbo/touchslide

import '@gentbo/touchslide';

快速开始

主容器需要包含一个内容层，内容层的直接子元素就是轮播项。建议显式设置内容选择器，避免页面结构与默认值不一致。

<div id="banner">
  <div class="slides">
    <article>第一页</article>
    <article>第二页</article>
    <article>第三页</article>
  </div>
</div>

<script>
GB.Touchslide('#banner')
  .content('.slides')
  .translate()
  .start();
</script>

主容器必须具有可用的宽度和高度。推荐由主容器定义可视尺寸，内容层及轮播项使用 width: 100% 和 height: 100%。初始化会生成可视层，并调整内容层及轮播项的行内样式。

完整轮播示例

<div id="gallery">
  <div class="slides">
    <figure><img src="1.jpg" alt=""></figure>
    <figure><img src="2.jpg" alt=""></figure>
    <figure><img src="3.jpg" alt=""></figure>
  </div>
  <button class="prev" type="button">上一页</button>
  <button class="next" type="button">下一页</button>
  <ol class="nav"></ol>
  <span class="paging">
    <b class="index"></b> / <b class="total"></b>
  </span>
</div>

<script>
GB.Touchslide('#gallery')
  .content('.slides')
  .nav('.nav', 'on', true)
  .prev('.prev')
  .next('.next')
  .paging('.paging .index', '.paging .total')
  .loop()
  .auto(3000)
  .delay(240)
  .before((index, total) => console.log('开始', index, total))
  .after((index, total) => console.log('完成', index, total))
  .start();
</script>

内容、导航与分页

.content(selector)设置内容层；它的直接子元素会作为轮播项。初始默认选择器为 .slider。

.nav(selector, onClass?, autoPage?)设置导航容器、当前项类名及自动分页。autoPage 为 true 时自动创建与轮播项等量的导航项。

.paging(index, total)设置当前页和总页数元素；页码从 1 开始显示。

自动分页时，如果导航容器是 ul 或 ol，将生成 li；其他容器会生成 span。导航项支持点击切换。

特效、循环与自动播放

.translate(horizontal = true)平移特效。true 为水平切换，false 为垂直切换；不传参数时默认水平切换。

.left()translate(true) 的兼容入口，水平跟手滑动；自动播放时向左移动。

.top()translate(false) 的兼容入口，垂直跟手滑动；主容器需要明确高度。

.fade()淡入淡出特效，轮播项原位叠放，支持横向滑动触发切换。

.zoom()缩放淡入特效，轮播项原位叠放，支持横向滑动触发切换。

.loop()启用无缝循环。只有一个轮播项时，循环和自动播放会自动关闭。

.auto(ms = 2500)启用自动播放并设置间隔，单位为毫秒；非正数会恢复为 2500ms。

.delay(ms = 200)设置单次切换动画时长，单位为毫秒；非正数会恢复为 200ms。

translate 会让内容跟随手指移动；fade 和 zoom 只使用横向滑动判断上一页或下一页，动画不会跟随手指变化。页面进入后台时自动播放会暂停，页面重新可见后恢复。非循环自动播放到最后一项后停止；用户手动滑动后也不会继续自动播放。

// 水平平移（默认）
GB.Touchslide('#gallery').content('.slides').translate().start();

// 垂直平移
GB.Touchslide('#gallery').content('.slides').translate(false).start();

// 淡入淡出
GB.Touchslide('#gallery').content('.slides').fade().loop().auto(3000).start();

// 缩放淡入
GB.Touchslide('#gallery').content('.slides').zoom().loop().auto(3000).start();

按钮与边界状态

.prev(selector, stopClass?)绑定上一页按钮；非循环模式到达第一页时添加 stopClass，默认 prevStop。

.next(selector, stopClass?)绑定下一页按钮；非循环模式到达最后一页时添加 stopClass，默认 nextStop。

GB.Touchslide('#gallery')
  .content('.slides')
  .prev('.prev', 'disabled')
  .next('.next', 'disabled')
  .start();

切换回调

.before(callback)动画开始时执行 callback(index, total)。

.after(callback)CSS 过渡结束时执行 callback(index, total)。

index 是从 1 开始的当前页码，total 是轮播项总数。首次无动画初始化不会调用这两个回调。

启动与使用边界

.start()完成 DOM 调整、事件绑定及首次渲染。

.run()start() 的兼容入口。

同一个 DOM 元素只能创建一个 Touchslide 实例，且同一实例只能启动一次；重复初始化或重复启动会抛出错误。调用 start() 前必须保证目标元素与内容层已经存在。

工具优先使用 Pointer Events，不支持时回退为鼠标事件。初始化还会监听窗口尺寸变化并自动重新计算轮播尺寸。