翻譯: 張?chǎng)涡?/a>
作者: Jan Sorgalla
版本: 0.2.3 (更新日志)
下載: jcarousel.tar.gz或jcarousel.zip(英文原版)，或是jcarousel_zh.zip(中文版)
許可: MIT
和 GPL 雙授權許可。
介紹
示例
入門(mén)指南
動(dòng)態(tài)內容加載
配置
兼容性
致謝
jCarousel是一款 jQuery 插件， 用來(lái)控制水平或垂直排列的列表項. 這些項目（可以是靜態(tài)HTML內容或是Ajax加載內容）內容是可以來(lái)回滾動(dòng)的（可以有動(dòng)畫(huà)效果）。
下面的示例展示了jCarousel插件可能的潛力:
<p style="color:red">您需要JavaScript的支持以看到效果</p>靜態(tài)實(shí)例
動(dòng)態(tài)實(shí)例
特別的實(shí)例
想要使用這款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文檔中能有一個(gè)非?；镜腍TML標記結構：
<ul id="mycarousel" class="jcarousel-skin-name"> <!-- The content goes in here --> </ul>
jCarousel可以自動(dòng)包括在列表外部的需要的HTML標記。這個(gè)class參數是將jCarousel皮膚“名稱(chēng)”應用于滾動(dòng)切換上。
為了設置jCarousel, 在您的HTML文檔的<head>標簽內部添加如下的代碼：
<script type="text/javascript">
jQuery(document).ready(function() {
jQuery('#mycarousel').jcarousel({
// Configuration goes here
});
});
</script>
jCarousel接受很多的配置選項，您可以去“配置”段落查看更多的信息。
在jCarousel被初始化之后，DOM中完整的創(chuàng )建的標記是：
<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（您手動(dòng)指定的class除外）。您可以根據上面您看到的些樣式設計您自己的滾動(dòng)切換的表現。
皮膚class "jcarousel-skin-name" 已經(jīng)從<ul>移到的頂部的<div>元素上了。
實(shí)例中，<div class="jcarousel-container">下第一個(gè)嵌套的<div>是個(gè)不可用的按鈕，第二個(gè)可用。這個(gè)不可使用的按鈕有個(gè)disabled屬性（對于<div>而言有些不合理，但是您可以使用<button>元素或者其他您想要的元素）和附加的class類(lèi)jcarousel-prev-disabled或（jcarousel-next-disabled）。
列表中每個(gè)<li>元素都有jcarousel-item-n這個(gè)特定的class。其中這個(gè)n代表了當前元素在列表中的位置
這里沒(méi)有顯示的是，所有class類(lèi)后面附加的后綴是由滾動(dòng)切換的方向決定的。例如： <ul class="jcarousel-list
jcarousel-list-horizontal">表水平方向上的傳送切換。
通過(guò)itemLoadCallback的回調函數作為配置選項，你可以動(dòng)態(tài)地創(chuàng )建<li>項添加到內容中。
<script type="text/javascript">
jQuery(document).ready(function() {
jQuery('#mycarousel').jcarousel({
itemLoadCallback: itemLoadCallbackFunction
});
});
</script>
itemLoadCallbackFunction 是一個(gè)JavaScript函數，這個(gè)函數在滾動(dòng)切換需要的些選項即將被加載完畢的時(shí)候調用。傳遞了兩個(gè)參數：請求的滾動(dòng)切換實(shí)例參數和顯示當前滾動(dòng)切換狀態(tài)的標志('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包含一個(gè)很方便的方法add()，這個(gè)玩意可以創(chuàng )建列表項以及每個(gè)項中的innerHTML字符串。如果當前項已經(jīng)存在，則此方法僅僅更新innerHTML。您可以通過(guò)公共變量carousel.first和carousel.last使用第一個(gè)和最后一個(gè)可見(jiàn)項。
jCarousel接受一系列的參數來(lái)控制滾動(dòng)切換傳送帶的外觀(guān)和行為。下面就是一些您可以設置的參數。
| 屬性 | 類(lèi)型 | 默認 | 描述 |
|---|---|---|---|
| vertical | bool | false | 指定滾動(dòng)切換傳送帶是以水平方向顯示還是垂直方向顯示。改變左右方向的滾動(dòng)切換為上下方向。 |
| start | integer | 1 | 指定起始項 |
| offset | integer | 1 | 在初始化時(shí)索引的第一個(gè)可用的項。 |
| size | integer | Number of existing <li> elements if size is not passed explicitly | 總共的列表項數目。 |
| scroll | integer | 3 | 每次滾動(dòng)切換的數目 |
| visible | integer | null | 如果通過(guò)，整個(gè)列表項的寬/高將會(huì )根據剪裁的寬/高計算和設定。因此整個(gè)列表項的數目將會(huì )被準確的顯示出來(lái)。 |
| animation | mixed | "fast" | 用以確定滾動(dòng)顯示動(dòng)畫(huà)的速度，可以是某些jQuery式字符串（"slow"或"fast"）或是毫秒（參見(jiàn)jQuery文檔材料）。如果設為0，則動(dòng)畫(huà)效果關(guān)閉。 |
| easing | string | null | 您想使用的緩動(dòng)類(lèi)型的名稱(chēng)（參見(jiàn)jQuery文檔材料）。 |
| auto | integer | 0 | 指定多少秒內容定期自動(dòng)滾動(dòng)。如果設置為0，則自動(dòng)滾動(dòng)關(guān)閉。 |
| wrap | string | null | 指定是否包裹第一/最后一項（或同時(shí)）并跳回到開(kāi)始/結束。選項參數有"first", "last"
或"both"字符串。如果設置為null，包裹會(huì )關(guān)閉（默認）。您也可以設置"circular"作為參數使支持循環(huán)滾動(dòng)顯示。您可以查看實(shí)例循環(huán)滾動(dòng)切換看看如何使用此參數。 |
| initCallback | function | null | JavaScript函數，在滾動(dòng)切換初始化后執行。需傳遞兩個(gè)參數：一個(gè)請求的滾動(dòng)切換實(shí)例參數，另外一個(gè)是滾動(dòng)切換的初始化狀態(tài)參數（init,reset或reload）。 |
| itemLoadCallback | function | null | JavaScript函數，在滾動(dòng)切換請求的些列表項加載完畢的時(shí)候執行。需要傳遞兩個(gè)參數：一個(gè)當前請求的滾動(dòng)切換的實(shí)例化對象，另外一個(gè)是滾動(dòng)切換的活動(dòng)狀態(tài)參數（prev,next或init）?；蛘?，您可以傳遞在動(dòng)畫(huà)之前或之后觸發(fā)的一個(gè)或兩個(gè)函數： itemLoadCallback: {
onBeforeAnimation: callback1,
onAfterAnimation: callback2
} |
| itemFirstInCallback | function | null | JavaScript函數，滾動(dòng)動(dòng)畫(huà)執行之后，當某一列表項成為可見(jiàn)區域的第一項時(shí)調用。傳遞四個(gè)參數：一是當前滾動(dòng)切換的實(shí)例對象，二是<li>對象本身，三是用來(lái)表明當前項在列表項中位置的參數，四是滾動(dòng)切換的活動(dòng)狀態(tài)參數（prev,next或init）?；蛘?，您可以傳遞在動(dòng)畫(huà)之前或之后觸發(fā)的一個(gè)或兩個(gè)函數： itemFirstInCallback: {
onBeforeAnimation: callback1,
onAfterAnimation: callback2
} |
| itemFirstOutCallback | function | null | JavaScript函數，滾動(dòng)動(dòng)畫(huà)執行之后，當某一列表項不再是可見(jiàn)區域的第一項時(shí)調用。傳遞四個(gè)參數：一是當前滾動(dòng)切換的實(shí)例對象，二是<li>對象本身，三是用來(lái)表明當前項在列表項中位置的參數，四是滾動(dòng)切換的活動(dòng)狀態(tài)參數（prev,next或init）?；蛘?，您可以傳遞在動(dòng)畫(huà)之前或之后觸發(fā)的一個(gè)或兩個(gè)函數： itemFirstOutCallback: {
onBeforeAnimation: callback1,
onAfterAnimation: callback2
} |
| itemLastInCallback | function | null | JavaScript函數，滾動(dòng)動(dòng)畫(huà)執行之后，當某一列表項成為可見(jiàn)區域的最后一項時(shí)調用。傳遞四個(gè)參數：一是當前滾動(dòng)切換的實(shí)例對象，二是<li>對象本身，三是用來(lái)表明當前項在列表項中位置的參數，四是滾動(dòng)切換的活動(dòng)狀態(tài)參數（prev,next或init）?；蛘?，您可以傳遞在動(dòng)畫(huà)之前或之后觸發(fā)的一個(gè)或兩個(gè)函數： itemLastInCallback: {
onBeforeAnimation: callback1,
onAfterAnimation: callback2
} |
| itemLastOutCallback | function | null | JavaScript函數，滾動(dòng)動(dòng)畫(huà)執行之后，當某一列表項不再是可見(jiàn)區域的最后一項時(shí)調用。傳遞四個(gè)參數：一是當前滾動(dòng)切換的實(shí)例對象，二是<li>對象本身，三是用來(lái)表明當前項在列表項中位置的參數，四是滾動(dòng)切換的活動(dòng)狀態(tài)參數（prev,next或init）?；蛘?，您可以傳遞在動(dòng)畫(huà)之前或之后觸發(fā)的一個(gè)或兩個(gè)函數： itemLastOutCallback: {
onBeforeAnimation: callback1,
onAfterAnimation: callback2
} |
| itemVisibleInCallback | function | null | JavaScript函數，滾動(dòng)動(dòng)畫(huà)執行之后，當某一列表項進(jìn)入到可見(jiàn)區域內時(shí)調用。傳遞四個(gè)參數：一是當前滾動(dòng)切換的實(shí)例對象，二是<li>對象本身，三是用來(lái)表明當前項在列表項中位置的參數，四是滾動(dòng)切換的活動(dòng)狀態(tài)參數（prev,next或init）?；蛘?，您可以傳遞在動(dòng)畫(huà)之前或之后觸發(fā)的一個(gè)或兩個(gè)函數： itemVisibleInCallback: {
onBeforeAnimation: callback1,
onAfterAnimation: callback2
} |
| itemVisibleOutCallback | function | null | JavaScript函數，滾動(dòng)動(dòng)畫(huà)執行之后，當某一列表項已經(jīng)不在可見(jiàn)區域內時(shí)調用。傳遞四個(gè)參數：一是當前滾動(dòng)切換的實(shí)例對象，二是<li>對象本身，三是用來(lái)表明當前項在列表項中位置的參數，四是滾動(dòng)切換的活動(dòng)狀態(tài)參數（prev,next或init）?；蛘?，您可以傳遞在動(dòng)畫(huà)之前或之后觸發(fā)的一個(gè)或兩個(gè)函數： itemVisibleOutCallback: {
onBeforeAnimation: callback1,
onAfterAnimation: callback2
} |
| buttonNextCallback | function | null | JavaScript函數，在'next'控制狀態(tài)改變的時(shí)候調用。此方法的職責就是啟用或禁用'next'控制。需傳遞三個(gè)參數：一是滾動(dòng)切換實(shí)例對象，二是控制的元素，三是按鈕是否要被禁用的標志參數。 |
| buttonPrevCallback | function | null | JavaScript函數，在'previous'控制狀態(tài)改變的時(shí)候調用。此方法的職責就是啟用或禁用'previous'控制。需傳遞三個(gè)參數：一是滾動(dòng)切換實(shí)例對象，二是控制的元素，三是按鈕是否要被禁用的flag標志。 |
| buttonNextHTML | string | <div></div> | 自動(dòng)生成下一個(gè)按鈕的HTML標記。如果設為null，則沒(méi)有“下一個(gè)(next-button)”按鈕創(chuàng )建。 |
| buttonPrevHTML | string | <div></div> | 自動(dòng)生成前一個(gè)按鈕的HTML標記。如果設為null，則沒(méi)有“前一個(gè)(prev-button)”按鈕創(chuàng )建。 |
| buttonNextEvent | string | "click" | 指定向后滾動(dòng)觸發(fā)的事件。 |
| buttonPrevEvent | string | "click" | 指定向前滾動(dòng)觸發(fā)的事件。 |
jCarousel已經(jīng)在下列瀏覽器下測試通過(guò)：
Internet Explorer 6 (PC)
Internet Explorer 7 (PC)
FireFox 1.5.0.6 (PC/Mac/Linux)
Opera 9.01 (PC/Mac)
Safari 2.0.4 (Mac)
Safari 3.1.0 (PC)
Konqueror 3.4.0 (Linux)
感謝John Resig 和他的不可思議的jQuery庫。
jCarousel的靈感來(lái)自Carousel Component，由Bill Scott書(shū)寫(xiě)。
內容可以公開(kāi)展示，需保留翻譯者姓名及鏈接。相關(guān)博文：http://www.zhangxinxu.com/wordpress/?p=477
聯(lián)系客服
