淘寶Widget規(guī)范

1、Widget規(guī)范出自淘寶網(wǎng)店鋪開發(fā)者WIKI跳轉(zhuǎn)到： 導(dǎo)航, 搜索目錄隱藏· 1 概述· 2 使用方法o 2.1 Tabs - 標(biāo)簽頁(yè)§ 2.1.1 實(shí)例展示§ 2.1.2 所需DOM結(jié)構(gòu)§ 2.1.3 組件調(diào)用方法§ 2.1.4 配置參數(shù)列表o 2.2 Slide卡盤效果§ 2.2.1 實(shí)例展示§ 2.2.2 所需DOM結(jié)構(gòu)§ 2.2.3 組件調(diào)用方法§ 2.2.4 參數(shù)配置列表o 2.3 Carousel - 旋轉(zhuǎn)木馬§ 2.3.1 實(shí)例展示§ 2.3.2 所需DOM結(jié)構(gòu)

2、§ 2.3.3 組件調(diào)用方法§ 2.3.4 參數(shù)配置列表o 2.4 Accordion - 手風(fēng)琴§ 2.4.1 實(shí)例展示§ 2.4.2 所需DOM結(jié)構(gòu)§ 2.4.3 組件調(diào)用方法§ 2.4.4 配置參數(shù)列表o 2.5 Popup - 彈出層§ 2.5.1 實(shí)例展示§ 2.5.2 所需DOM結(jié)構(gòu)§ 2.5.3 組件調(diào)用方法§ 2.5.4 配置參數(shù)列表§ 2.5.5 配置項(xiàng)align中的points的說(shuō)明· 3 關(guān)于Kissy· 4 支持效果· 5 編寫心得

3、· 6 樣例代碼概述 實(shí)際的開發(fā)中需要用到一些功能比較豐富的主機(jī)，如圖片輪播，tab標(biāo)簽等，這些組件都需要設(shè)計(jì)師寫Javascript才能完成，考慮前期JavaScript是不對(duì)設(shè)計(jì)師開放的，所以淘寶要提供一些widget庫(kù)，方便設(shè)計(jì)調(diào)用，形成特定的組件。通過(guò)載入淘寶的js框架來(lái)渲染。<div class="J_TWidget" data-type="Slide" data-cfg=""><!- code - ></div>我們會(huì)獲取名字叫 J_TWidget 的元素, 并根據(jù)其類型和配置

4、信息, 渲染相應(yīng)的效果。使用方法 目前淘寶提供的widget 分為5種:· Tabs - 標(biāo)簽頁(yè)· Slide - 卡盤· Carousel - 旋轉(zhuǎn)木馬· Accordion - 手風(fēng)琴· Popup - 彈出層 針對(duì)每種不同的動(dòng)畫效果需要通過(guò)配置不同的參數(shù)，配合不同的DOM結(jié)構(gòu)。以下依次介紹每種不同的動(dòng)畫效果的配置參數(shù)以及其DOM結(jié)構(gòu)Tabs - 標(biāo)簽頁(yè)實(shí)例展示 實(shí)例一 實(shí)例二 所需DOM結(jié)構(gòu)本組件對(duì)DOM結(jié)構(gòu)沒有特殊要求，調(diào)用只需要按順序?qū)l列表中每個(gè)元素跟內(nèi)容元素一一對(duì)應(yīng)即可，當(dāng)然觸點(diǎn)和內(nèi)容都必須包含在唯一的外層容器里面。<di

5、v class="J_TWidget section"> <ul class="ks-switchable-nav"> <li class="ks-active">標(biāo)題 A</li> <li>標(biāo)題 B</li> <li>標(biāo)題 C</li> <li>標(biāo)題 D</li> </ul> <div class="ks-switchable-content"> <div> -預(yù)先

6、加載的內(nèi)容- </div> <div style="display: none">內(nèi)容 B</div> <div style="display: none">內(nèi)容 C</div> <div style="display: none">內(nèi)容 D</div> </div></div>組件調(diào)用方法<div class=”J_TWidget” data-widget-type=”Tabs” data-widget-config=”

7、 'effect': 'fade', 'autoplay': true, 'circular': true ”><!- code - ></div>配置參數(shù)列表配置參數(shù)參數(shù)可選值作用說(shuō)明effectnone/fade/scrolly/scrollx(默認(rèn)值：none)切換時(shí)的動(dòng)畫效果none, 最樸素的顯示/隱藏效果fade, 可實(shí)現(xiàn)淡隱淡現(xiàn)的效果scrolly, 垂直滾動(dòng)scrollx, 水平滾動(dòng)easingeaseOutStrong/easeBoth滾動(dòng)的動(dòng)畫方方式countdowntrue/fa

8、lse (默認(rèn)值：false)是否開啟倒計(jì)時(shí)樣式countdownFromStyle自定義值設(shè)定倒計(jì)時(shí)最終樣式如: width:15px 表示進(jìn)度條最終寬度,可先在CSS里對(duì)樣式進(jìn)行定義navCls自定義值對(duì)其進(jìn)行輪播的目標(biāo)列表的class值contentCls自定義值輪播列表所對(duì)應(yīng)的內(nèi)容列表的class值delay自定義數(shù)值 (默認(rèn)值：1)延遲加載時(shí)間.1 = 100mstriggerTypemouse/click<>(默認(rèn)值：mouse)br觸發(fā)方式mouse：鼠標(biāo)經(jīng)過(guò)觸發(fā)click：鼠標(biāo)點(diǎn)擊觸發(fā)hasTriggerstrue/false (默認(rèn)值：true)是否設(shè)置觸發(fā)點(diǎn)st

9、eps自定義數(shù)值 (默認(rèn)值：1)切換視圖內(nèi)有多少個(gè)panelsviewSize自定義值切換視圖區(qū)域的大小。一般不需要設(shè)定此值，僅當(dāng)獲取值不正確時(shí)，用于手工指定大小activeIndex自定義數(shù)值 (默認(rèn)值：0)默認(rèn)激活的列表項(xiàng)activeTriggerCls自定義值 (默認(rèn)值：active)默認(rèn)激活列表項(xiàng)的class值autoplaytrue/false (默認(rèn)值：true)是否自動(dòng)播放circulartrue/false (默認(rèn)值：true)是否有循環(huán)滾動(dòng)效果duration自定義值（默認(rèn)值：0.5）動(dòng)畫時(shí)長(zhǎng).1 = 100msSlide卡盤效果實(shí)例展示 超帥圖片輪播 淘小二推薦 實(shí)例一 實(shí)

10、例二 實(shí)例三 所需DOM結(jié)構(gòu)本組件需要將滾動(dòng)的對(duì)象作為一個(gè)ul列表，包含在外層的容器中，同時(shí)容器里還需要定義一個(gè)容器來(lái)放置列表中對(duì)應(yīng)項(xiàng)的具體內(nèi)容。<div class="J_TWidget section"> <div class="yslider-stage"> <p><a href="#" target="_blank"><img src="#"/></a></p><p><a href=&q

11、uot;#" target="_blank"><img src="#"/></a></p><p><a href="#" target="_blank"><img src="#"/></a></p> </div> <ul class="yslider-stick"> <li class="selected">&l

12、t;a href="#" target="_blank">aaa</a></li> <li><a href="#" target="_blank">bbb</a></li> <li><a href="#" target="_blank">ccc</a></li> </ul></div>組件調(diào)用方法<div class=”J

13、_TWidget” data-widget-type=”Slide” data-widget-config=”'navCls': 'yslider-stick', 'contentCls': 'yslider-stage', 'activeTriggerCls': 'selected', 'delay': 0.2, 'effect': 'fade', 'easing': 'easeBoth', 'duration

14、': 0.8, 'autoplay': false,”><!- code - ></div>參數(shù)配置列表配置參數(shù)參數(shù)可選值作用說(shuō)明effectnone/fade/scrolly/scrollx(默認(rèn)值：none)切換時(shí)的動(dòng)畫效果none, 最樸素的顯示/隱藏效果fade, 可實(shí)現(xiàn)淡隱淡現(xiàn)的效果scrolly, 垂直滾動(dòng)scrollx, 水平滾動(dòng)easingeaseOutStrong/easeBoth滾動(dòng)的動(dòng)畫方方式countdowntrue/false (默認(rèn)值：false)是否開啟倒計(jì)時(shí)樣式countdownFromStyle自定義值設(shè)定

15、倒計(jì)時(shí)最終樣式如: width:15px 表示進(jìn)度條最終寬度,可先在CSS里對(duì)樣式進(jìn)行定義navCls自定義值對(duì)其進(jìn)行輪播的目標(biāo)列表的class值contentCls自定義值輪播列表所對(duì)應(yīng)的內(nèi)容列表的class值delay自定義數(shù)值 (默認(rèn)值：1)延遲加載時(shí)間.1 = 100mstriggerTypemouse/click<>(默認(rèn)值：mouse)br觸發(fā)方式mouse：鼠標(biāo)經(jīng)過(guò)觸發(fā)click：鼠標(biāo)點(diǎn)擊觸發(fā)hasTriggerstrue/false (默認(rèn)值：true)是否設(shè)置觸發(fā)點(diǎn)steps自定義數(shù)值 (默認(rèn)值：1)切換視圖內(nèi)有多少個(gè)panelsviewSize自定義值切換視圖區(qū)

16、域的大小。一般不需要設(shè)定此值，僅當(dāng)獲取值不正確時(shí)，用于手工指定大小activeIndex自定義數(shù)值 (默認(rèn)值：0)默認(rèn)激活的列表項(xiàng)activeTriggerCls自定義值 (默認(rèn)值：active)默認(rèn)激活列表項(xiàng)的class值duration自定義值（默認(rèn)值：0.5）動(dòng)畫時(shí)長(zhǎng).1 = 100msCarousel - 旋轉(zhuǎn)木馬實(shí)例展示 實(shí)例一 實(shí)例二 所需DOM結(jié)構(gòu)需要滾動(dòng)的對(duì)象依次羅列，包含在內(nèi)容區(qū)的容器中，同時(shí)需要兩個(gè)不同ID的容器來(lái)分別包含上下翻頁(yè)的按鈕，另外可以將每一組內(nèi)容再獨(dú)自包含在一個(gè)ul列表中。<div class="section J_TWidget"&g

17、t; <span id="scroller-prev" class="prev disable"> 上一頁(yè)</span> <span id="scroller-next" class="next">下一頁(yè) </span> <div class="scroller"> <div class="ks-switchable-content"> <img alt="" src="

18、;#"/> <img alt="" src="#"/> <img alt="" src="#"/> <img alt="" src="#"/> <img alt="" src="#"/> <img alt="" src="#"/> <img alt="" src="#"/>

19、; <img alt="" src="#"/> <img alt="" src="#"/> </div> <ul class="ks-switchable-nav"> <li class="ks-active"></li> <li></li> <li></li> </ul> </div></div>組件調(diào)用方法<di

20、v class=”J_TWidget” data-widget-type=”Carousel” data-widget-config=”'effect': 'scrollx', 'easing': 'easeOutStrong', 'steps': 5, 'viewSize': 680, 'circular': false, 'prevBtnCls': 'prev', 'nextBtnCls': 'next', '

21、;disableBtnCls': 'disable', ”><!- code - ></div>參數(shù)配置列表配置參數(shù)參數(shù)可選值作用說(shuō)明effectnone/fade/scrolly/scrollx(默認(rèn)值：none)切換時(shí)的動(dòng)畫效果none, 最樸素的顯示/隱藏效果fade, 可實(shí)現(xiàn)淡隱淡現(xiàn)的效果scrolly, 垂直滾動(dòng)scrollx, 水平滾動(dòng)easingeaseOutStrong/easeBoth滾動(dòng)的動(dòng)畫方方式countdowntrue/false (默認(rèn)值：false)是否開啟倒計(jì)時(shí)樣式countdownFromStyle自定義值

22、設(shè)定倒計(jì)時(shí)最終樣式如: width:15px 表示進(jìn)度條最終寬度,可先在CSS里對(duì)樣式進(jìn)行定義navCls自定義值對(duì)其進(jìn)行輪播的目標(biāo)列表的class值contentCls自定義值輪播列表所對(duì)應(yīng)的內(nèi)容列表的class值delay自定義數(shù)值 (默認(rèn)值：1)延遲加載時(shí)間，當(dāng)前顯示圖片到切換其他圖片動(dòng)作開始，這中間的停留時(shí)間.1 = 100mstriggerTypemouse/click<>(默認(rèn)值：mouse)br觸發(fā)方式mouse：鼠標(biāo)經(jīng)過(guò)觸發(fā)click：鼠標(biāo)點(diǎn)擊觸發(fā)hasTriggerstrue/false (默認(rèn)值：true)是否設(shè)置觸發(fā)點(diǎn)steps自定義數(shù)值 (默認(rèn)值：1)切換視

23、圖內(nèi)有多少個(gè)panelsviewSize自定義值切換視圖區(qū)域的大小。一般不需要設(shè)定此值，僅當(dāng)獲取值不正確時(shí)，用于手工指定大小activeIndex自定義數(shù)值 (默認(rèn)值：0)默認(rèn)激活的列表項(xiàng)activeTriggerCls自定義值 (默認(rèn)值：active)默認(rèn)激活列表項(xiàng)的class值circulartrue/false(默認(rèn)：true)滾動(dòng)效果prevBtnCls自定義值上一頁(yè)的class值nextBtnCls自定義值下一頁(yè)的class值disableBtnCls自定義值按鈕不可用的class值duration自定義值(默認(rèn)：0.5)動(dòng)畫時(shí)長(zhǎng),一張圖片開始切換到另一張圖片顯示的時(shí)間.1 = 10

24、0msAccordion - 手風(fēng)琴實(shí)例展示 實(shí)例一 實(shí)例二 所需DOM結(jié)構(gòu)需要將菜單中每個(gè)標(biāo)題及其內(nèi)容分別包含在對(duì)應(yīng)的容器中，最外層容器有唯一的ID來(lái)標(biāo)示組件。<div class="J_TWidget section"> <div class="ks-switchable-trigger ks-active"><h3>標(biāo)題A</h3></div> <div class="ks-switchable-panel"> 內(nèi)容AAAAA </div> &l

25、t;div class="ks-switchable-trigger"><h3>標(biāo)題B</h3></div><div class="ks-switchable-panel" style="display:none;">內(nèi)容BBBBB</div> <div class="ks-switchable-trigger"><h3>標(biāo)題C</h3></div><div class="ks-swit

26、chable-panel" style="display:none;">內(nèi)容CCCCC</div> <div class="ks-switchable-trigger last-trigger"><h3>標(biāo)題D</h3></div><div class="ks-switchable-panel last-panel" style="display:none;">內(nèi)容DDDDD</div></div>組件調(diào)

27、用方法<div class=”J_TWidget” data-widget-type=”Accordion” data-widget-config=” 'triggerType': 'click', 'multiple':true ”> <!- code - ></div>配置參數(shù)列表配置參數(shù)參數(shù)可選值作用說(shuō)明triggerCls自定義值主列表的class值panelCls自定義值列表所對(duì)應(yīng)的內(nèi)容列表的class值triggerTypemouse/click (默認(rèn)值：click)觸發(fā)方式mouse：鼠標(biāo)經(jīng)過(guò)觸

28、發(fā)click：鼠標(biāo)點(diǎn)擊觸發(fā)multipletrue/false (默認(rèn)值：false)是否同時(shí)支持多面板展開hasTriggerstrue/false (默認(rèn)值：true)是否設(shè)置觸發(fā)點(diǎn)Popup - 彈出層實(shí)例展示 實(shí)例一 實(shí)例二 所需DOM結(jié)構(gòu)本組件作為一個(gè)彈出層的效果，通過(guò)預(yù)先設(shè)置一個(gè)隱藏的彈出層，并且設(shè)置該彈出層的觸點(diǎn)，通過(guò)鼠標(biāo)滑入和移出觸點(diǎn)來(lái)展示和隱藏彈出層效果<div class="first-trigger">我只是個(gè)觸點(diǎn)而已，把鼠標(biāo)滑到我身上</div><div class="J_TWidget hidden"

29、; data-widget-type="Popup" data-widget-config=" 'trigger':'.first-trigger', 'align': 'node':'.first-trigger', 'offset':0,0, 'points':'cr','cc' "> <div style="background-color: blue; height: 100px;

30、width: 100px;"> 我是一個(gè)彈出層 </div></div>組件調(diào)用方法<div class="J_TWidget hidden" data-widget-type="Popup" data-widget-config=" 'trigger':'.first-trigger', 'align': 'node':'.first-trigger', 'offset':0,0, 'point

31、s':'cr','cc' "> <!- code - ></div>配置參數(shù)列表配置參數(shù)參數(shù)可選值作用說(shuō)明trigger自定義觸點(diǎn)元素，就是鼠標(biāo)滑過(guò)哪個(gè)元素的時(shí)候彈出當(dāng)前的popup，支持class和id選擇器的寫法alignnode,points,offset 三個(gè)配置node: 自定義, / 參考元素。 popup與參考元素進(jìn)行定位。和觸點(diǎn)寫法一樣，支持class和id選擇器 的寫法points: tr,tl, / 'tl', 'tr' 表示popup的tl 與參考節(jié)點(diǎn)的 tr

32、對(duì)齊 ， 具體tl，tr表示的意義和值看下面截圖, t(top)，c(center), b(bottom),l(left),r(right)offset: 0,0 / 有效值為 n, m ， points對(duì)齊后，offset值，一般可用于微調(diào), n和m分別表示對(duì)齊兩個(gè)點(diǎn)在x,y坐標(biāo)之間的偏移量配置項(xiàng)align中的points的說(shuō)明 觸點(diǎn)與彈出層的對(duì)齊方式（align中的points配置） 元素及參考元素上各自的九個(gè)不同位置點(diǎn)('tl', 'tc', 'tr', 'cl', 'cc', 'cr', &

33、#39;bl', 'bc', 'br') 如下圖所示:demo 代碼，直接復(fù)制到自定義內(nèi)容區(qū)里面，保存-預(yù)覽就可以到效果了哈。大家發(fā)揮自己的想象力吧。<div class="first-trigger">我只是個(gè)觸點(diǎn)而已，把鼠標(biāo)滑到我身上</div><div class="J_TWidget hidden" data-widget-type="Popup" data-widget-config=" 'trigger':'.first

34、-trigger', 'align': 'node':'.first-trigger', 'offset':0,0, 'points':'cr','cl' "> <div style="background-color: blue; height: 100px; width: 100px;"> 我是一個(gè)彈出層 </div></div>demo 代碼，直接復(fù)制到自定義內(nèi)容區(qū)里面，保存-預(yù)覽就可以到效果了哈。

35、大家發(fā)揮自己的想象力吧。<div class="first-trigger">我只是個(gè)觸點(diǎn)而已，把鼠標(biāo)滑到我身上</div><div class="J_TWidget hidden" data-widget-type="Popup" data-widget-config=" 'trigger':'.first-trigger', 'align': 'node':'.first-trigger', 'offse

36、t':0,0, 'points':'cr','cl' "> <div style="background-color: blue; height: 100px; width: 100px;"> 我是一個(gè)彈出層 </div></div>注意： 觸點(diǎn)目前只允許包含在#content內(nèi)。不允許影響頁(yè)頭頁(yè)尾：關(guān)于Kissy 淘寶發(fā)布開源編輯器：KISSY Editor，和我們?cè)?WordPress 后臺(tái)使用的富文本編輯器 TinyMCE 一樣，它可以讓我們?cè)诰€編輯和格式化文本

37、，但是相比 TinyMCE KISSY Editor 更加輕巧，更加適合國(guó)內(nèi)的網(wǎng)絡(luò)環(huán)境。 KISSY Editor 是開源項(xiàng)目 KISSY UI Library 的一個(gè)組件。KISSY 目前基于 YUI 2.x 開發(fā)，目標(biāo)是打造一系列小巧靈活、簡(jiǎn)潔實(shí)用、使用起來(lái)讓人感覺愉悅的 UI 組件，目前已有 CSS 基礎(chǔ)框架、搜索提示 Suggest 和 KISSY Editor 這個(gè)富文本編輯器等組件。支持效果 目前kissy中開放，能直接調(diào)用的效果組件為switchable，其中包括四種widget，tabs（標(biāo)簽頁(yè)），Slide（卡盤），Carousel（旋轉(zhuǎn)木馬），Accordion（手風(fēng)琴）

38、雖然只有四種效果，但實(shí)際上，通過(guò)kissy中開放的配置（對(duì)應(yīng)sdk中的data-widget-config），以及不同的dom結(jié)構(gòu)，與css控制，可以展示出各種各樣的效果。 下面是互聯(lián)網(wǎng)中，部分電子商務(wù)網(wǎng)站首頁(yè)的一些效果截圖 附件中會(huì)給出，sdk中如何通過(guò)淘寶提供的J_TWidget實(shí)現(xiàn)其中的效果。Tabs：Slide：· 其中“土豆今日焦點(diǎn)”這個(gè)組件中，當(dāng)縮略圖的切換時(shí)，上面的內(nèi)容和左側(cè)的大圖同時(shí)切換，這個(gè)略微特殊一點(diǎn)，用到了兩個(gè)slide，用一個(gè)ks-switchable-nav來(lái)控制兩個(gè)ks-switchable-content的切換。編寫心得 拿其中一個(gè)dom結(jié)構(gòu)為例，kis

39、sy中開放效果，只要把握其中這樣幾點(diǎn)。最外層dom結(jié)構(gòu)：id為demo這個(gè)div標(biāo)簽，組件的最外層dom結(jié)構(gòu)。組件中的dom結(jié)構(gòu)：包含在id為demo里面的div結(jié)構(gòu)里面的結(jié)構(gòu)。class=”J_TWidget”：用來(lái)表示這個(gè)div是一個(gè)組件，我們要用kissy來(lái)渲染這個(gè)組件。data-widget-type="Tabs":這個(gè)是用來(lái)告訴sdk，我們的widget組件要用什么方式來(lái)渲染。data-widget-config=”.”: 這個(gè)是組件的相關(guān)配置，也是很靈活的一部分class=”ks-switchable-nav” : 這個(gè)用來(lái)定義當(dāng)前組件進(jìn)行輪播的目標(biāo)列表的class值。PS:我們更推薦用戶去自定義一個(gè)class來(lái)覆蓋這個(gè)淘寶默認(rèn)的鉤子，方法為在data-widget-config中。data-widget-config=" 'navCls': '自定義的class'"，這樣也方便設(shè)計(jì)師定義樣式。class="ks-switchable-content"：用來(lái)定義輪播列表所對(duì)應(yīng)的內(nèi)容列表的class值。PS:我們更推薦用戶去自定義一個(gè)class來(lái)覆蓋這個(gè)淘寶默認(rèn)的鉤子，方法為在data-wi