jCarousel

jQuery跑马灯插件

作者: Jan Sorgalla
版本: 0.2.4 (Changelog)
下载: jcarousel.tar.gz or jcarousel.zip
授权: Dual licensed under the MIT and GPL licenses.

目录

  1. 引言
  2. 示例
  3. 开始
  4. 动态载
  5. 配置
  6. 兼容性
  7. 捐献

引言

jCarousel 是一个可以控制水平或垂直列表的 jQuery 插件。这个列表可以说静态的HTML，也可以说一个动态载入的被人（像AJAX），它们能被向前或向后旋转（需要的话还可以加入一些动画特效）。

示例

下面的示例足可以证明 jCarousel 的能力:

从这儿开始

在HTML 的 <head> 部分里引用 jQuery 类库，jCarousel 源码文件和 jCarousel 的皮肤文件（CSS样式）:

<script type="text/javascript" src="/path/to/jquery-1.4.2.min.js"></script>
<script type="text/javascript" src="/path/to/lib/jquery.jcarousel.min.js"></script>
<link rel="stylesheet" type="text/css" href="/path/to/skin/skin.css" />

这个下载包里有一些示例样式文件，你可以在这个基础上建立自己的皮肤样式。

jCarousel只需要一个简单的 HTML 在你的 网页文档里:

<ul id="mycarousel" class="jcarousel-skin-name">
   <!-- 内容放在这儿 -->
</ul>

jCarousel automatically wraps the required HTML markup around the list. The class attribute applies the jCarousel skin "name" to the carousel.

设置 jCarousel, 把下面的代码加到网页文档的 <head> 里:

<script type="text/javascript">
jQuery(document).ready(function() {
    jQuery('#mycarousel').jcarousel({
        // 这儿配置选项
    });
});
</script>

jCarousel 有许多配置选项, 查看更多信息在"配置" 。

jCarousel初始化完成后, 会在DOM里建立一个完整的标记语言:

<div class="jcarousel-skin-name">
  <div class="jcarousel-container">
    <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 disabled="disabled" class="jcarousel-prev jcarousel-prev-disabled"></div>
    <div class="jcarousel-next"></div>
  </div>
</div>

你会看到，有一些元素被附上了 Class 名（除了那些你自己手动添加的）。你可以根据上面看到的class 名随意去定制你自己的跑马灯样式。

注意:

动态载入

By passing the callback function itemLoadCallback as configuration option, you are able to dynamically create <li> items for the content.

配置选项使用 callback 函数 itemLoadCallback，你可以动态常见<li>列表。

<script type="text/javascript">
jQuery(document).ready(function() {
    jQuery('#mycarousel').jcarousel({
        itemLoadCallback: itemLoadCallbackFunction
    });
});
</script>

itemLoadCallbackFunction 是一个JavaScript 函数，但它被这个跑马灯调用时就会加载进来一组列表。有2个参数：被请求的跑马灯实例和一个用来指明跑马灯当前的状态('init', 'prev' or '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 一条记录。如果这个记录已经存在，则更新。你可以通过 公共变量（ carousel.first and carousel.last）提取第一和最后一个可见的元素。

Accessing the jCarousel instance

The instance of the carousel will be stored with the data() method of jQuery under the key jcarousel for a simple access.

这个跑马灯实例可以 data() 方法存储。

如果你已经建立了一个像这样的程序:

jQuery(document).ready(function() {
    jQuery('#mycarousel').jcarousel();
});

You can access the instance with你可以存储这个例子:

var carousel = jQuery('#mycarousel').data('jcarousel');

You can also access methods of the instance directly, for example the add() method:你也可以直接使用实例的存取方法，像 add（） 方法： 

var index = 1;
var html = 'My content of item no. 1';
jQuery('#mycarousel').jcarousel('add', index, html);

配置

jCarousel 可以通过一些属性配置来控制它的外观和表现，下面是配置列表：

Property Type Default Description
vertical bool false Specifies wether the carousel appears in horizontal or vertical orientation. Changes the carousel from a left/right style to a up/down style carousel.决定 carousel 的水平还是垂直方向。可以将carousel左右方向旋转改为上下方向。
start integer 1 The index of the item to start with.
offset integer 1 The index of the first available item at initialisation.初始化是引索第一个可见的标签。
size integer Number of existing <li> elements if size is not passed explicitly The number of total items.所有标签的数目。
scroll integer 3 The number of items to scroll by.每次旋转几个元素。
visible integer null If passed, the width/height of the items will be calculated and set depending on the width/height of the clipping, so that exactly that number of items will be visible.
animation mixed "fast"

The speed of the scroll animation as string in jQuery terms ("slow" or "fast") or milliseconds as integer (See jQuery Documentation). If set to 0, animation is turned off.

旋转动画的速度("slow" 或 "fast") 或者是整数的毫秒。如果设置为0，则会关闭动画效果。
easing string null The name of the easing effect that you want to use (See jQuery Documentation).
auto integer 0 Specifies how many seconds to periodically autoscroll the content. If set to 0 (default) then autoscrolling is turned off.
wrap string null Specifies whether to wrap at the first/last item (or both) and jump back to the start/end. Options are "first", "last" or "both" as string. If set to null, wrapping is turned off (default). You can also pass "circular" as option to enable support for circular carousels. See the example Circular carousel on how to implement it.
initCallback function null JavaScript function that is called right after initialisation of the carousel. Two parameters are passed: The instance of the requesting carousel and the state of the carousel initialisation (init, reset or reload)
itemLoadCallback function null JavaScript function that is called when the carousel requests a set of items to be loaded. Two parameters are passed: The instance of the requesting carousel and the state of the carousel action (prev, next or init). Alternatively, you can pass a hash of one or two functions which are triggered before and/or after animation: 
itemLoadCallback: {
  onBeforeAnimation: callback1,
  onAfterAnimation: callback2
}
itemFirstInCallback function null JavaScript function that is called (after the scroll animation) when an item becomes the first one in the visible range of the carousel. Four parameters are passed: The instance of the requesting carousel and the <li> object itself, the index which indicates the position of the item in the list and the state of the carousel action (prev, next or init). Alternatively, you can pass a hash of one or two functions which are triggered before and/or after animation: 
itemFirstInCallback: {
  onBeforeAnimation: callback1,
  onAfterAnimation: callback2
}
itemFirstOutCallback function null JavaScript function that is called (after the scroll animation) when an item isn't longer the first one in the visible range of the carousel. Four parameters are passed: The instance of the requesting carousel and the <li> object itself, the index which indicates the position of the item in the list and the state of the carousel action (prev, next or init). Alternatively, you can pass a hash of one or two functions which are triggered before and/or after animation: 
itemFirstOutCallback: {
  onBeforeAnimation: callback1,
  onAfterAnimation: callback2
}
itemLastInCallback function null JavaScript function that is called (after the scroll animation) when an item becomes the last one in the visible range of the carousel. Four parameters are passed: The instance of the requesting carousel and the <li> object itself, the index which indicates the position of the item in the list and the state of the carousel action (prev, next or init). Alternatively, you can pass a hash of one or two functions which are triggered before and/or after animation: 
itemLastInCallback: {
  onBeforeAnimation: callback1,
  onAfterAnimation: callback2
}
itemLastOutCallback function null JavaScript function that is called when an item isn't longer the last one in the visible range of the carousel. Four parameters are passed: The instance of the requesting carousel and the <li> object itself, the index which indicates the position of the item in the list and the state of the carousel action (prev, next or init). Alternatively, you can pass a hash of one or two functions which are triggered before and/or after animation: 
itemLastOutCallback: {
  onBeforeAnimation: callback1,
  onAfterAnimation: callback2
}
itemVisibleInCallback function null JavaScript function that is called (after the scroll animation) when an item is in the visible range of the carousel. Four parameters are passed: The instance of the requesting carousel and the <li> object itself, the index which indicates the position of the item in the list and the state of the carousel action (prev, next or init). Alternatively, you can pass a hash of one or two functions which are triggered before and/or after animation: 
itemVisibleInCallback: {
  onBeforeAnimation: callback1,
  onAfterAnimation: callback2
}
itemVisibleOutCallback function null JavaScript function that is called (after the scroll animation) when an item isn't longer in the visible range of the carousel. Four parameters are passed: The instance of the requesting carousel and the <li> object itself, the index which indicates the position of the item in the list and the state of the carousel action (prev, next or init). Alternatively, you can pass a hash of one or two functions which are triggered before and/or after animation: 
itemVisibleOutCallback: {
  onBeforeAnimation: callback1,
  onAfterAnimation: callback2
}
buttonNextCallback function null JavaScript function that is called when the state of the 'next' control is changing. The responsibility of this method is to enable or disable the 'next' control. Three parameters are passed: The instance of the requesting carousel, the control element and a flag indicating whether the button should be enabled or disabled.
buttonPrevCallback function null JavaScript function that is called when the state of the 'previous' control is changing. The responsibility of this method is to enable or disable the 'previous' control. Three parameters are passed: The instance of the requesting carousel, the control element and a flag indicating whether the button should be enabled or disabled.
buttonNextHTML string <div></div> The HTML markup for the auto-generated next button. If set to null, no next-button is created.
buttonPrevHTML string <div></div> The HTML markup for the auto-generated prev button. If set to null, no prev-button is created.
buttonNextEvent string "click" Specifies the event which triggers the next scroll.
buttonPrevEvent string "click" Specifies the event which triggers the prev scroll.

Compatibility

jCarousel has been tested and works on the following browsers:

Credits

Thanks to John Resig for his fantastic jQuery library.
jCarousel is inspired by the Carousel Component written by Bill Scott.