Switchable

Switchable 的核心类, Switchable.Tabs/Switchable.Slide/Switchable.Accordion/Switchable.Carousel 都是扩展自它.
KISSY.use('switchable',function(S,Switchable){
    // use Switchable
});

Warning

本组件停止维护,推荐使用 gallery/slide

Class

Class Detail

class switchable.Switchable
Switchable (container[, config])
Parameters:
  • container (String|HTMLElement) – 容器
  • config (object) – 可选, 配置项, 详细见下方 Configs Detail .

Configs Detail

Switchable.config.markupType

{Number} - 默认为0. 指明 DOM 结构标记的类型, 可取 0, 1, 2.

当取 0 时, 表示 DOM 是默认结构: 通过 nav 和 content 来获取 triggers 和 panels, 即通过配置以下两个参数获取.

Switchable.config.navCls

{String} - triggers 所在容器的 class, 默认为 ‘ks-switchable-nav’.

Switchable.config.contentCls

{String} - panels 所在容器的 class, 默认为 ‘ks-switchable-content’.

这种方式的 DOM 结构类似于:

<div id="J_Slide">  <!-- 容器元素 -->
    <ul class="ks-switchable-nav">  <!-- 触发器列表 -->
        <li class="ks-active">标题 A</li>
        <li>标题 B</li>
        <li>标题 C</li>
        <li>标题 D</li>
    </ul>
    <div class="ks-switchable-content">  <!-- 面板列表 -->
        <div>内容 A</div>
        <div style="display: none">内容 B</div>
        <div style="display: none">内容 C</div>
        <div style="display: none">内容 D</div>
    </div>
</div>

当取 1 时, 表示 DOM 结构 可适度灵活:通过 cls 来获取 triggers 和 panels, 即通过配置以下两个参数获取.

Switchable.config.triggerCls

{String} - 默认为 ‘ks-switchable-trigger’, 会在 container 下寻找指定 class 的元素作为触发器.

Switchable.config.panelCls

{String} - 默认为 ‘ks-switchable-panel’, 会在 container 下寻找指定 class 的元素作为面板.

这种方式的 DOM 结构类似于:

<div id="J_Accordion">
    <div class="ks-switchable-trigger ks-active"><i class="ks-icon"></i><h3>标题A</h3></div>
    <div class="ks-switchable-panel">内容A<br/>内容A<br/>内容A</div>
    <div class="ks-switchable-trigger"><i class="ks-icon"></i><h3>标题B</h3></div>
    <div class="ks-switchable-panel" style="display:none;">内容B<br/>内容B<br/>内容B</div>
    <div class="ks-switchable-trigger"><i class="ks-icon"></i><h3>标题C</h3></div>
    <div class="ks-switchable-panel" style="display:none;">内容C<br/>内容C<br/>内容C<br/>内容C<br/>内容C</div>
    <div class="ks-switchable-trigger last-trigger"><i class="ks-icon"></i><h3>标题D</h3></div>
    <div class="ks-switchable-panel last-panel" style="display:none;">内容D<br/>内容D<br/>内容D</div>
</div>

当取 2 时, 表示 DOM 结构 完全自由: 直接传入 triggers 和 panels, 即通过配置以下两个参数获取. 这种方式下, DOM 结构就非常自由了, 传入什么内容有你自己定, 只需要 triggers 和 panels 的数量保持一致就好.

Switchable.config.triggers

{Array<HTMLElement>} - 默认为 [], 触发器数组.

Switchable.config.panels

{Array<HTMLElement>} - 默认为 [], 面板数组.

Switchable.config.hasTriggers

{Boolean} - 默认为 true, 是否有触发器.

Switchable.config.triggerType

{String} - 默认为 ‘mouse’ , 触发类型, 可选为’mouse’ 或 ‘click’.

Switchable.config.delay

{Number} - 默认为 .1 , 触发延迟时间, 单位为s.

Switchable.config.activeIndex

{Number} - 默认为 0, markup 的默认激活项, 应该与此 index 一致.

Note

使用此项时, 需要让激活项对应的 trigger 和 panel 的 HTMLElement, 在 DOM 结构上设置为 激活状态, 不然无法正确切换

Switchable.config.activeTriggerCls

{String} - 激活某个 trigger 时设置的 class , 默认是 ‘ks-active’.

Switchable.config.switchTo

{Number} - 初始化时, 自动切换到指定面板, 默认为 0 , 即第一个.

Note

switchTo 和 activeIndex 的区别是:

  • activeIndex 需要 DOM 上设置激活状态, 初始化后不会去切换状态;
  • switchTo 则不需要修改 DOM, 但 switchTo 设置后, 会去切换到指定状态, 这在用了一些动画效果时, 切换动作更为明显;
Switchable.config.steps

{Number} - 步长, 表示每次切换要间隔多少个 panels, 默认为 1.

Switchable.config.viewSize

{Array} - 可见视图区域的大小. 如果 css 中不设置 panel 的高宽或初始没有 panel , 则需要这里手工指定大小, 默认为 [].

Note

当 panel 的高宽 css 中不指定时,需要设置 viewSize 为单个 panel 的高宽.

Switchable.config.autoplay

{Boolean} - 是否自动切换, 默认为 false, 开启后, 不需要触发触发器, 即可自动播放.

Switchable.config.interval

{Number} - 自动播放间隔时间, 以 s 为单位, 默认为 5.

Switchable.config.pauseOnHover

{Boolean} - triggerType 为 mouse 时, 鼠标悬停在 slide 上是否暂停自动播放, 默认为 true.

Switchable.config.pauseOnScroll

{Boolean} - 轮播不在视窗时是否停止自动轮播。默认 false

Switchable.config.circular

{Boolean} - 是否循环切换, 默认为 true, 是否循环播放, 当切换到最初/最后一个时, 是否切换到最后/最初一个.

Switchable.config.effect

{String} - 动画效果函数, 默认没有特效, 可取 scrollx, scrolly, fade 或者直接传入自定义效果函数.

Switchable.config.duration

{Number} - 默认为 .5, 动画的时长.

Switchable.config.easing

{String|Function} - 动画效果, 详见 Anim, 默认为 easeNone .

Switchable.config.lazyDataType

{String} - 默认为 ‘area-data’, 设置延迟加载时使用的数据类型, 可取:

  1. textareaarea-data , 即表示延迟加载使用的是 textarea 方式, 可以给非当前 panel 内嵌一个 <textarea class="ks-datalazyload-custom" style="visibility: hidden;">panel的内容</textarea>;
  2. imgimg-src, 即表示延迟加载使用的是 img 方式, 可以给非当前 panel 中的 img 元素设置属性 data-ks-lazyload-custom 为 src 的地址, 这种方式常用于 旋转木马, 见 Demo

Note

  • 支持懒加载, 需要载入 S.Datalazyload, 详见 DataLazyload
Switchable.config.lazyImgAttribute

{String} - 懒加载图片的属性名。默认 “data-ks-lazyload-custom”.

Switchable.config.lazyTextareaClass

{String} - 懒加载 textarea 的类名。默认 “ks-datalazyload-custom”.

Attributes Detail

Switchable.prototype.container

{HTMLElement} - 只读, 容器元素

Switchable.prototype.config

{Object} - - 只读, 配置信息

Switchable.prototype.triggers

{Array} - 只读, 触发器集合, 可以为空值 []

Switchable.prototype.panels

{Array} - 只读, 切换面板集合, 可以为空值 []

Switchable.prototype.content

{HTMLElement} - 只读, 存放面板的容器元素

Note

content 元素不可以为 overflow:hidden,否则从最后一屏切换到第一屏时会出白屏现象.请在整个容器根元素上设置 overflow:hidden

Switchable.prototype.length

{Number} - 只读, 触发器或面板的个数

Switchable.prototype.activeIndex

{Number} - 只读, 当前被激活的触发器序号, 从0 开始

Switchable.prototype.switchTimer

{Object} - 只读, 切换定时器, 一般作为内部使用

Methods Detail

Switchable.prototype.switchTo()
switchTo (index, direction, ev, callback)
切换到某个视图
Parameters:
  • index (Number) – 要切换的项
  • direction (String) – (可选) 方向, 用于 effect, 可取 ‘forward’, ‘backward’, 或者不设置
  • ev (EventObject) – (可选) 引起该操作的事件
  • callback (Function) – (可选) 运行完回调, 和绑定 switch 事件作用一样
Switchable.prototype.prev()
prev ([ev])
切换到上一视图
Parameters:ev (EventObject) – 引起该操作的事件
Switchable.prototype.next()
next (ev)
切换到下一视图
Parameters:ev (EventObject) – (可选) 引起该操作的事件
Switchable.prototype.stop()
stop ()
停止自动切换

Note

只有设置了 autoplay true 时有效

Switchable.prototype.start()
start ()
开始自动切换

Note

只有设置了 autoplay true 时有效

Switchable.prototype.add()
add (cfg)
添加一项
Parameters:
  • cfg (Object) – 添加的具体配置
  • cfg.trigger (HTMLElement) – 导航的 trigger 节点
  • cfg.panel (HTMLElement) – 内容节点
  • cfg.index (Number) – 插入位置
  • cfg.active (Boolean) – 是否将新插入的内容节点激活显示
  • cfg.callback (Function) – 添加成功后的回调

Note

添加操作详解:

  1. 假设当前 activeIndex 为 x

  2. 如果 steps == 1

    1. 插入新的 trigger 和 panel 到指定位置
    2. 如果 x 大于等于参数的 index,那么当前的 activeIndex++
    3. 强制 switch 到新的 activeIndex 的位置,保持当前panel内容不变(防止新元素排挤)
    4. 如果指定了 active,那么 switch 到新的插入位置 index
  3. 如果 steps > 1

    1. 插入新的panel
    2. 如果 panel 插入后导致 length 增大,那么插入新的 trigger 到尾部
    3. 强制 switch 到 activeIndex 的位置,保持当前页位置不变(防止新元素排挤)
    4. 如果指定了 active,那么 switch 到新的插入位置 index 所应该在的页数(一页有多个panel)
Switchable.prototype.remove()
remove (cfg)
删除一个内容节点
Parameters:
  • cfg (Function) – 删除配置
  • cfg.callback (Function) – 删除成功后的回调
  • cfg.index (Number) – 将要删除的内容节点所在的位置

Note

删除操作详解:

  1. 假设当前 activeIndex 为 x

  2. 如果 steps == 1

    1. 如果 x 位置的元素就是要删除的元素: x==index

      1. 如果 x ==0,switch 到 1位置后,删除0元素,在设置 activeIndex 为 0
      2. switch 到 x-1 位置,然后删除 x 位置元素
    2. 如果 x 的值大于 index,那么设置 activeIndex=x-1;

    3. 删除 trigger 和 x 元素

  3. 如果 steps > 1

    1. 如果删除 x 元素导致页数-1,那么设置 trigger 为最后一个trigger,否则trigger为null
    2. 如果删除 x 元素导致 activeIndex 页为空,那么先 switch 到 activeIndex-1 的页,然后删除 x 元素
    3. 否则直接删除 trigger 和 x 位置 panel 元素,并重新强制 switch 到 activeIndex 元素(懒加载替换上来的元素)
Switchable.prototype.destroy()
destroy (keepNode)
销毁该组件
Parameters:keepNode (Boolean) – 是否保留节点,默认 false.

Events Detail

Switchable.beforeSwitch()
beforeSwitch (ev)
切换前触发. 当该事件的函数处理器返回 false, 则会阻止切换动作.
Parameters:
  • ev (Object) – 事件对象
  • ev.toIndex (Number) – 即将切换到的tab的索引号
Switchable.switch()
switch (ev)
切换后触发.
Parameters:
  • ev (Object) – 事件对象
  • ev.currentIndex (Number) – 当前切换到的tab的索引号
Switchable.add()
add (ev)
添加节点后触发
Parameters:
  • ev (Object) – 事件对象
  • ev.index (Number) – 新节点所在的位置
  • trigger (HTMLElement) – 新 trigger 节点
  • panel (HTMLElement) – 新内容节点
Switchable.beforeRemove()
beforeRemove (ev)
删除节前触发. 当该事件的函数处理器返回 false, 则会阻止删除节动作.
Parameters:
  • ev (Object) – 事件对象
  • ev.index (Number) – 将要删除的节点所在的位置
  • trigger (HTMLElement) – 将要被删除的 trigger 节点
  • panel (HTMLElement) – 将要被删除的内容节点
Switchable.remove()
remove (ev)
删除节点后触发
Parameters:
  • ev (Object) – 事件对象
  • ev.index (Number) – 删除的节点所在的位置
  • trigger (HTMLElement) – 被删除的 trigger 节点
  • panel (HTMLElement) – 被删除的内容节点

Important

如果 panel css 指定了高宽,或内部图片指定了高宽,或设置了 viewSize 都没问题, 否则在网速慢时都会因为初始化取不到面板高度而出问题。

switchable-content 样式不能设置 overflow:hidden ,请在整个容器上设置 overflow:hidden .