参考
http://club.sm160.com/showtopic-216185.aspx
翻译: 张鑫旭 作者: Jan Sorgalla
入门指南想要使用这款jCarousel组件,需要include jQuery 库, jCarousel资源文件, jCarousel core 核心样式表文件以及jCarousel皮肤样式表文件,该文件在您的HTML文档<head>标签之内。 <script type="text/javascript" src="/path/to/jquery-1.2.1.pack.js"></script><script type="text/javascript" src="/path/to/lib/jquery.jcarousel.pack.js"></script><link rel="stylesheet" type="text/css" href="/path/to/lib/jquery.jcarousel.css" /><link rel="stylesheet" type="text/css" href="/path/to/skin/skin.css" />下载文件包中包含几款打包的示例皮肤。您可以自由的在这些皮肤上建立属于您自己的皮肤。 jCarousel期望在您的HTML文档中能有一个非常基本的HTML标记结构: <ul id="mycarousel" class="jcarousel-skin-name"> <!-- The content goes in here --></ul>jCarousel可以自动包括在列表外部的需要的HTML标记。这个class参数是将jCarousel皮肤“名称”应用于滚动切换上。为了设置jCarousel, 在您的HTML文档的<head>标签内部添加如下的代码: <script type="text/javascript">jQuery(document).ready(function() { jQuery('#mycarousel').jcarousel({ // Configuration goes here });});</script>jCarousel接受很多的配置选项,您可以去“配置”段落查看更多的信息。在jCarousel被初始化之后,DOM中完整的创建的标记是: <div class="jcarousel-skin-name"> <div class="jcarousel-container"> <div disabled="disabled" class="jcarousel-prev jcarousel-prev-disabled"></div> <div class="jcarousel-next"></div> <div class="jcarousel-clip"> <ul class="jcarousel-list"> <li class="jcarousel-item-1">First item</li> <li class="jcarousel-item-2">Second item</li> </ul> </div> </div></div>正如您看到的,有些元素添加了一些指定的class(您手动指定的class除外)。您可以根据上面您看到的些样式设计您自己的滚动切换的表现。注意:
- 皮肤class "jcarousel-skin-name" 已经从<ul>移到的顶部的<div>元素上了。
- 实例中,<div class="jcarousel-container">下第一个嵌套的<div>是个不可用的按钮,第二个可用。这个不可使用的按钮有个disabled属性(对于<div>而言有些不合理,但是您可以使用<button>元素或者其他您想要的元素)和附加的class类jcarousel-prev-disabled或(jcarousel-next-disabled)。
- 列表中每个<li>元素都有jcarousel-item-n这个特定的class。其中这个n代表了当前元素在列表中的位置
- 这里没有显示的是,所有class类后面附加的后缀是由滚动切换的方向决定的。例如: <ul class="jcarousel-list jcarousel-list-horizontal">表水平方向上的传送切换。
动态内容加载通过itemLoadCallback的回调函数作为配置选项,你可以动态地创建<li>项添加到内容中。 <script type="text/javascript">jQuery(document).ready(function() { jQuery('#mycarousel').jcarousel({ itemLoadCallback: itemLoadCallbackFunction });});</script>itemLoadCallbackFunction 是一个JavaScript函数,这个函数在滚动切换需要的些选项即将被加载完毕的时候调用。传递了两个参数:请求的滚动切换实例参数和显示当前滚动切换状态的标志('init', 'prev' 或 'next')参数。 <script type="text/javascript">function itemLoadCallbackFunction(carousel, state){ for (var i = carousel.first; i <= carousel.last; i++) { // Check if the item already exists if (!carousel.has(i)) { // Add the item carousel.add(i, "I'm item #" + i); } }};</script>jCarousel包含一个很方便的方法add(),这个玩意可以创建列表项以及每个项中的innerHTML字符串。如果当前项已经存在,则此方法仅仅更新innerHTML。您可以通过公共变量carousel.first和carousel.last使用第一个和最后一个可见项。 配置jCarousel接受一系列的参数来控制滚动切换传送带的外观和行为。下面就是一些您可以设置的参数。
属性 | 类型 | 默认 | 描述 |
vertical | bool | false | 指定滚动切换传送带是以水平方向显示还是垂直方向显示。改变左右方向的滚动切换为上下方向。 |
start | integer | 1 | 指定起始项 |
offset | integer | 1 | 在初始化时索引的第一个可用的项。 |
size | integer | Number of existing <li> elements if size is not passed explicitly | 总共的列表项数目。 |
scroll | integer | 3 | 每次滚动切换的数目 |
visible | integer | null | 如果通过,整个列表项的宽/高将会根据剪裁的宽/高计算和设定。因此整个列表项的数目将会被准确的显示出来。 |
animation | mixed | "fast" | 用以确定滚动显示动画的速度,可以是某些jQuery式字符串("slow"或"fast")或是毫秒(参见jQuery文档材料)。如果设为0,则动画效果关闭。 |
easing | string | null | 您想使用的缓动类型的名称(参见jQuery文档材料)。 |
auto | integer | 0 | 指定多少秒内容定期自动滚动。如果设置为0,则自动滚动关闭。 |
wrap | string | null | 指定是否包裹第一/最后一项(或同时)并跳回到开始/结束。选项参数有"first", "last" 或"both"字符串。如果设置为null,包裹会关闭(默认)。您也可以设置"circular"作为参数使支持循环滚动显示。您可以查看实例循环滚动切换看看如何使用此参数。 |
initCallback | function | null | JavaScript函数,在滚动切换初始化后执行。需传递两个参数:一个请求的滚动切换实例参数,另外一个是滚动切换的初始化状态参数(init,reset或reload)。 |
itemLoadCallback | function | null | JavaScript函数,在滚动切换请求的些列表项加载完毕的时候执行。需要传递两个参数:一个当前请求的滚动切换的实例化对象,另外一个是滚动切换的活动状态参数(prev,next或init)。或者,您可以传递在动画之前或之后触发的一个或两个函数: itemLoadCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2} |
itemFirstInCallback | function | null | JavaScript函数,滚动动画执行之后,当某一列表项成为可见区域的第一项时调用。传递四个参数:一是当前滚动切换的实例对象,二是<li>对象本身,三是用来表明当前项在列表项中位置的参数,四是滚动切换的活动状态参数(prev,next或init)。或者,您可以传递在动画之前或之后触发的一个或两个函数: itemFirstInCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2} |
itemFirstOutCallback | function | null | JavaScript函数,滚动动画执行之后,当某一列表项不再是可见区域的第一项时调用。传递四个参数:一是当前滚动切换的实例对象,二是<li>对象本身,三是用来表明当前项在列表项中位置的参数,四是滚动切换的活动状态参数(prev,next或init)。或者,您可以传递在动画之前或之后触发的一个或两个函数: itemFirstOutCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2} |
itemLastInCallback | function | null | JavaScript函数,滚动动画执行之后,当某一列表项成为可见区域的最后一项时调用。传递四个参数:一是当前滚动切换的实例对象,二是<li>对象本身,三是用来表明当前项在列表项中位置的参数,四是滚动切换的活动状态参数(prev,next或init)。或者,您可以传递在动画之前或之后触发的一个或两个函数: itemLastInCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2} |
itemLastOutCallback | function | null | JavaScript函数,滚动动画执行之后,当某一列表项不再是可见区域的最后一项时调用。传递四个参数:一是当前滚动切换的实例对象,二是<li>对象本身,三是用来表明当前项在列表项中位置的参数,四是滚动切换的活动状态参数(prev,next或init)。或者,您可以传递在动画之前或之后触发的一个或两个函数: itemLastOutCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2} |
itemVisibleInCallback | function | null | JavaScript函数,滚动动画执行之后,当某一列表项进入到可见区域内时调用。传递四个参数:一是当前滚动切换的实例对象,二是<li>对象本身,三是用来表明当前项在列表项中位置的参数,四是滚动切换的活动状态参数(prev,next或init)。或者,您可以传递在动画之前或之后触发的一个或两个函数: itemVisibleInCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2} |
itemVisibleOutCallback | function | null | JavaScript函数,滚动动画执行之后,当某一列表项已经不在可见区域内时调用。传递四个参数:一是当前滚动切换的实例对象,二是<li>对象本身,三是用来表明当前项在列表项中位置的参数,四是滚动切换的活动状态参数(prev,next或init)。或者,您可以传递在动画之前或之后触发的一个或两个函数: itemVisibleOutCallback: { onBeforeAnimation: callback1, onAfterAnimation: callback2} |
buttonNextCallback | function | null | JavaScript函数,在'next'控制状态改变的时候调用。此方法的职责就是启用或禁用'next'控制。需传递三个参数:一是滚动切换实例对象,二是控制的元素,三是按钮是否要被禁用的标志参数。 |
buttonPrevCallback | function | null | JavaScript函数,在'previous'控制状态改变的时候调用。此方法的职责就是启用或禁用'previous'控制。需传递三个参数:一是滚动切换实例对象,二是控制的元素,三是按钮是否要被禁用的flag标志。 |
buttonNextHTML | string | <div></div> | 自动生成下一个按钮的HTML标记。如果设为null,则没有“下一个(next-button)”按钮创建。 |
buttonPrevHTML | string | <div></div> | 自动生成前一个按钮的HTML标记。如果设为null,则没有“前一个(prev-button)”按钮创建。 |
buttonNextEvent | string | "click" | 指定向后滚动触发的事件。 |
buttonPrevEvent | string | "click" | 指定向前滚动触发的事件。 |
兼容性jCarousel已经在下列浏览器下测试通过:
- Internet Explorer 6 (PC)