Owl Carousel 2是上一版Owl Carousel的升级版本。Owl Carousel 2可以让你创建漂亮的响应式旋转木马的jQuery插件,它支持移动触摸屏,功能十分强大。Owl的新特性有:

  • 可以无限循环
  • 项目可以居中显示
  • 灵活的速度控制
  • 多级别的padding设置
  • 项目间可以设置Margin
  • 使几乎所有的选项都具有响应能力
  • 多种宽度设置
  • 丰富的回调事件
  • RTL(从右向左移动)
  • YouTube/Vimeo视频支持
  • 锚链接导航
  • 合并项
  • 还有更多...

浏览器兼容

Owl Carousel 2.x.x 版本和以前的1.x.x版本不兼容。Owl Carousel 2.x.x版本的大部分文件和1.x.x版本的基本相同,但是核心文件已经被从新编写。

Owl Carousel 2已经在下列浏览器中进行了测试:

  • Chrome
  • Firefox
  • Opera
  • IE7/8/10/11
  • iPad Safari
  • iPod4 Safari
  • Nexus 7 Chrome
  • Galaxy S4
  • Nokia 8s Windows8

文件结构

Owl Carousel 2发行版的目录结构如下:

owlcarousel/
├── assets/
│   ├── owl.carousel.css
│   ├── owl.carousel.min.css
│   ├── owl.theme.default.css
│   ├── owl.theme.default.min.css
│   ├── owl.theme.green.css
│   ├── owl.theme.green.min.css
│   └── owl.video.play.png
│
├── owl.carousel.js
├── owl.carousel.min.js
├── LICENSE-MIT
└── README.md                  
                

插件依赖

Owl Carousel 2依赖于jQueryZepto。jQuery最低版本要求是1.8.3版本。

使用方法

CSS文件

在html头部中引入必要的css文件:

<link rel="stylesheet" href="owlcarousel/owl.carousel.min.css">
<link rel="stylesheet" href="owlcarousel/owl.theme.default.min.css">                  
                

owl.theme.default.css文件时可选的。

JS文件

在页面的尾部添加owl.carousel.min.js文件:

<script src="jquery.min.js"></script>
<script src="owlcarousel/owl.carousel.min.js"></script>                  
                
HTML结构

Owl Carousel不需要设置复杂的html结构,你只需要将你的内容<div>(当然,owl可以工作在其它元素中,如a/img/span)包裹在一个class为owl-carousel<div>中即可。Class owl-carousel是在owl.carousel.css文件中定义的,改变它需要修改整个owl.carousel.css文件。

调用插件

现在,你可以调用Owl Carousel的初始化方法来使旋转木马工作:

$(document).ready(function(){
  $(".owl-carousel").owlCarousel();
});                  
                

参数选项

下表中是所有内置的Owl Carousel参数选项:

参数名称 参数类型 默认值 描述
items Type: Number Default: 3 在屏幕中可见的旋转木马项
margin Type: Number Default: 0 旋转木马项的margin-right值,单位像素
loop Type: Boolean Default: false 是否无限循环,会复制第一项和最后一项来制作无限循环的错觉
center Type: Boolean Default: false 旋转木马项居中。在奇数和偶数项中都可以很好的工作
mouseDrag Type: Boolean Default: true 是否可以使用鼠标拖拽
touchDrag Type: Boolean Default: true 是否可以触摸拖拽
pullDrag Type: Boolean Default: true Stage pull to edge.
freeDrag Type: Boolean Default: false Item pull to edge
stagePadding Type: Number Default: 0 Stage上的Padding left和Padding right(可以看到相邻的项)
merge Type: Boolean Default: false 合并旋转木马项。Looking for data-merge='{number}' inside item..
mergeFit Type: Boolean Default: true 如果屏幕比旋转木马项小,使旋转木马项适合屏幕大小
autoWidth Type: Boolean Default: false 设置非网格内容。尝试在div上使用width样式
startPosition Type: Number/String Default: 0 开始点或URL Hash字符串,如:'#id'
URLhashListener Type: Boolean Default: false 监听url hash 的变化。必须在旋转木马项上设置data-hash属性
nav Type: Boolean Default: false 显示ext/prev按钮
navRewind Type: Boolean Default: true 跳转到前一项或后一项
navText Type: Array Default: ['next','prev'] HTML箭头导航
slideBy Type: Number/String Default: 1 Navigation slide by x. 'page' string can be set to slide by page.
dots Type: Boolean Default: true 显示圆点导航按钮
dotsEach Type: Number/Boolean Default: false 每多少个项显示一个圆点导航按钮
dotData Type: Boolean Default: false 使用data-dot的内容
lazyLoad Type: Boolean Default: false 是否懒加载图片。data-srcdata-src-retina为高分辨率。如果元素不是<img>会设置为元素的内联背景图像。
lazyContent Type: Boolean Default: false lazyContent选项只在测试版中有,发行版中已经被删除。
autoplay Type: Boolean Default: false 旋转木马是否自动播放
autoplayTimeout Type: Number Default: 5000 旋转木马自动播放的时间间隔
autoplayHoverPause Type: Boolean Default: false 是否在鼠标滑过时停止自动播放
smartSpeed Type: Number Default: 250 速度计算
fluidSpeed Type: Boolean Default: Number 速度计算
autoplaySpeed Type: Number/Boolean Default: false 是新密码自动播放的速度
navSpeed Type: Number/Boolean Default: false 旋转木马导航的速度
dotsSpeed Type: Boolean Default: Number/Boolean 分页的速度
dragEndSpeed Type: Number/Boolean Default: false Drag end speed
callbacks Type: Boolean Default: true 是否允许回调函数
responsive Type: Object Default: empty object 包含responsive选项的对象。设置为flase取消responsive能力。
responsiveRefreshRate Type: Number Default: 200 Responsive的刷新频率
responsiveBaseElement Type: DOM element Default: window 可以设置在任何DOM元素上。如果你关心不支持响应式的浏览器(如IE8),可以在包裹容器中使用该属性。
responsiveClass Type: Boolean Default: false 可选的辅助class。添加owl-reponsive-breakpoint class到主元素上。可以在给定breakpoint的元素上设置内容样式。
video Type: Boolean Default: false 是否允许添加YouTube/Vimeo视频。
videoHeight Type: Number/Boolean Default: false 设置视频的高度。
videoWidth Type: Number/Boolean Default: false 设置视频的宽度。
animateOut Type: String/Bolean Default: false CSS3 animation out.
animateIn Type: String/Bolean Default: false CSS3 animation in.
fallbackEasing Type: String Default: swing Easing for CSS2 $.animate.
info Type: Function Default: false 获取基本信息的回调函数(当前的 item/pages/widths) 。Info函数的第二个参数是Owl DOM元素的对象引用。
nestedItemSelector Type: String/Class Default: false 当owl元素嵌套在某些很深的DOM结构中时使用该参数。在class名字前面不要使用.号。
itemElement Type: String Default: div owl-item的DOM元素类型。
stageElement Type: String Default: div owl-stage.的DOM元素类型。
navContainer Type: String/Class/ID/Bolean Default: false 设置自定义的导航容器class
dotsContainer Type: String/Class/ID/Bolean Default: false 设置自定义的导航容器class

Classes

下面的例子说明了Owl Carousel在HTML中是如何被渲染的。通过后面表格中列出的参数,你可以改变的class样式:

<div class="owl-carousel owl-theme owl-loaded">
    <div class="owl-stage-outer">
        <div class="owl-stage">
            <div class="owl-item">...</div>
            <div class="owl-item">...</div>
            <div class="owl-item">...</div>
        </div>
    </div>
    <div class="owl-controls">
        <div class="owl-nav">
            <div class="owl-prev">prev</div>
            <div class="owl-next">next</div>
        </div>
        <div class="owl-dots">
            <div class="owl-dot active"><span></span></div>
            <div class="owl-dot"><span></span></div>
            <div class="owl-dot"><span></span></div>
        </div>
    </div>
</div>                  
                
参数名称 参数类型 默认值 描述
themeClass Type: Class/String Default: owl-theme Theme Class.
baseClass Type: Class/String Default: owl-carousel Base element Class
itemClass Type: Class/String Default: owl-item Item Class
centerClass Type: Class/String Default: center Center Class.
activeClass Type: Class/String Default: active Active Class
navContainerClass Type: Class/String Default: owl-nav Nav container Class.
navClass Type: Array/Class/String Default: ['owl-prev','owl-next'] Nav buttons Classes
controlsClass Type: Class/String Default: owl-controls Controls Class - wrapper for navs and dots
dotClass Type: Class/String Default: owl-dot Dot Class
dotsClass Type: Class/String Default: owl-dots Dots Class - Container for dots..
autoHeightClass Type: Class/String Default: owl-height Auto height Class.

事件

所有的事件都有Owl Carousel的核心代码提供。这使得你可以监听任何元素的变化和给出回调函数。

var owl = $('.owl-carousel');
owl.owlCarousel();
// Listen to owl events:
owl.on('changed.owl.carousel', function(event) {
    ...
})                  
                

你也可以自行触发Owl Carousel事件:

var owl = $('.owl-carousel');
owl.owlCarousel();
// Go to the next item
$('.customNextBtn').click(function() {
    owl.trigger('next.owl.carousel');
})
// Go to the previous item
$('.customPrevBtn').click(function() {
    // With optional speed parameter
    // Parameters has to be in square bracket '[]'
    owl.trigger('prev.owl.carousel', [300]);
})                  
                
Callbacks
$('.owl-carousel').owlCarousel({
    onDragged: callback
});
function callback(event) {
    ...
}                  
                
Data

每一个事件都通过event object提供非常有用的信息。

function callback(event) {
    // Provided by the core
    var element   = event.target;         // DOM element, in this example .owl-carousel
    var name      = event.type;           // Name of the event, in this example dragged
    var namespace = event.namespace;      // Namespace of the event, in this example owl.carousel
    var items     = event.item.count;     // Number of items
    var item      = event.item.index;     // Position of the current item
    // Provided by the navigation plugin
    var pages     = event.page.count;     // Number of pages
    var page      = event.page.index;     // Position of the current page
    var size      = event.page.size;      // Number of items per page
}                  
                
Carousel
名称 类型 回调函数 触发时机
initialize.owl.carousel Type: attachable Callback: onInitialize 插件初始化时触发
initialized.owl.carousel Type: attachable Callback: onInitialized 插件初始化后触发
resize.owl.carousel Type: attachable Callback: onResize 旋转木马尺寸改变时触发
resized.owl.carousel Type: attachable Callback: onResized 旋转木马尺寸改变后触发
refresh.owl.carousel Type: attachable, cancelable, triggerable Callback: onRefresh,Parameter: [event, speed] When the internal state of the plugin needs update.
refreshed.owl.carousel Type: attachable Callback: onRefreshed When the internal state of the plugin has updated.
drag.owl.carousel Type: attachable Callback: onDrag 当拖动旋转木马项时触发
dragged.owl.carousel Type: attachable Callback: onDragged 当拖动旋转木马项结束后触发
translate.owl.carousel Type: attachable Callback: onTranslate When the translation of the stage starts.
translated.owl.carousel Type: attachable Callback: onTranslated When the translation of the stage has finished.
change.owl.carousel Type: attachable Callback: onChange,Parameter: property When a property is going to change its value
changed.owl.carousel Type: attachable Callback: onChanged,Parameter: property When a property has changed its value.
next.owl.carousel Type: triggerable Parameter: [speed] Goes to next item.
prev.owl.carousel Type: triggerable Parameter: [speed] Goes to previous item.
to.owl.carousel Type: triggerable Parameter: [position, speed] Goes to postion
destroy.owl.carousel Type: triggerable Destroys carousel
replace.owl.carousel Type: triggerable Parameter: data Removes current content and add a new one passed in the parameter.
add.owl.carousel Type: triggerable Parameter: [data, position] Adds a new item on a given position.
remove.owl.carousel Type: triggerable Parameter: position Removes an item from a given position
Lazy
名称 类型 回调函数 触发时机
load.owl.lazy Type: attachable Callback: onLoadLazy When lazy image loads.
loaded.owl.lazy Type: attachable Callback: onLoadedLazy
Video
名称 类型 回调函数 触发时机
stop.owl.video Type: attachable Callback: onStopVideo When video has unloaded.
play.owl.video Type: attachable Callback: onPlayVideo When video has loaded.
Autoplay
名称 类型 参数 描述
play.owl.autoplay Type: triggerable Parameter: [timeout, speed] Runs autoplay
stop.owl.autoplay Type: triggerable Stops autoplay