Widget規范_淘大師

Widget規范目錄導航

概述
使用方法
Tabs - 標簽頁
Slide卡盤效果
Carousel - 旋轉木馬
Accordion - 手風琴
Popup - 彈出層
Countdown - 倒計時
Compatibe - 兼容性組件
二維碼圖片組件
購物車組件
收藏寶貝組件
分享組件
關于Kissy
支持效果
編寫心得
樣例代碼

您現在的位置是：淘大首頁 > 美工裝修 > Widget規范

概述

實際的開發中需要用到一些功能比較豐富的主機，如圖片輪播，tab標簽等，這些組件都需要設計師寫Javascript才能完成，考慮前期JavaScript是不對設計師開放的，所以淘寶要提供一些widget庫，方便設計調用，形成特定的組件。

通過載入淘寶的js框架來渲染。

	<div class="J_TWidget"  data-type="Slide" data-cfg="{…}">

    <!--  code  -- >

</div>

我們會獲取名字叫 J_TWidget 的元素, 并根據其類型和配置信息, 渲染相應的效果。

使用方法

目前淘寶提供的widget 分為6種:

● Tabs - 標簽頁
● Slide - 卡盤
● Carousel - 旋轉木馬
● Accordion - 手風琴
● Popup - 彈出層
● Compatible - 兼容性組件

針對每種不同的動畫效果需要通過配置不同的參數，配合不同的DOM結構。
以下依次介紹每種不同的動畫效果的配置參數以及其DOM結構

Tabs - 標簽頁

實例展示

實例一實例二

所需DOM結構

本組件對DOM結構沒有特殊要求，調用只需要按順序將ul列表中每個元素跟內容元素一一對應即可，當然觸點和內容都必須包含在唯一的外層容器里面。

	<div  class="J_TWidget section">

    <ul class="ks-switchable-nav">

        <li class="ks-active">標題 A</li>

        <li>標題 B</li>

        <li>標題 C</li>

        <li>標題 D</li>

    </ul>

    <div class="ks-switchable-content">

        <div>
               
                  -----預先加載的內容---------
           
        </div>

        <div style="display: none">內容 B</div>

        <div style="display: none">內容 C</div>

        <div style="display: none">內容 D</div>

    </div>

	</div>

組件調用方法

	<div class=”J_TWidget”  data-widget-type=”Tabs”  data-widget-config=”{

            'effect': 'fade',

            'autoplay': true,

            'circular': true
      }”>

	<!--  code  -- >

	</div>

配置參數列表

配置參數	參數可選值	作用說明
effect	none/fade/scrolly/scrollx (默認值：none)	切換時的動畫效果 none, 最樸素的顯示/隱藏效果 fade, 可實現淡隱淡現的效果 scrolly, 垂直滾動 scrollx, 水平滾動
easing	easeOutStrong/easeBoth	滾動的動畫方方式
countdown	true/false (默認值：false)	是否開啟倒計時樣式
countdownFromStyle	自定義值	設定倒計時最終樣式如: width:15px 表示進度條最終寬度,可先在CSS里對樣式進行定義
navCls	自定義值	對其進行輪播的目標列表的class值
contentCls	自定義值	輪播列表所對應的內容列表的class值
delay	自定義數值 (默認值：1)	延遲加載時間 .1 == 100ms
triggerType	mouse/click<> (默認值：mouse)br	觸發方式—— mouse：鼠標經過觸發 click：鼠標點擊觸發
hasTriggers	true/false (默認值：true)	是否設置觸發點
steps	自定義數值 (默認值：1)	切換視圖內有多少個panels
viewSize	自定義值	切換視圖區域的大小。一般不需要設定此值，僅當獲取值不正確時，用于手工指定大小
activeIndex	自定義數值 (默認值：0)	默認激活的列表項
activeTriggerCls	自定義值 (默認值：active)	默認激活列表項的class值
autoplay	true/false (默認值：true)	是否自動播放
circular	true/false (默認值：true)	是否有循環滾動效果
duration	自定義值（默認值：0.5）	動畫時長 .1 = 100ms

Slide卡盤效果

實例展示

超帥圖片輪播淘小二推薦實例一實例二實例三

所需DOM結構

本組件需要將滾動的對象作為一個ul列表，包含在外層的容器中，同時容器里還需要定義一個容器來放置列表中對應項的具體內容。

	<div class="J_TWidget section">

    <div class="yslider-stage">

        <p><a href="#" target="_blank"><img src="###"/></a></p>

        <p><a href="#" target="_blank"><img src="###"/></a></p>

        <p><a href="#" target="_blank"><img src="###"/></a></p>

    </div>

    <ul class="yslider-stick">

        <li class="selected"><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>

組件調用方法

	<div class=”J_TWidget”  data-widget-type=”Slide”  data-widget-config=”{

			'navCls': 'yslider-stick',

            'contentCls': 'yslider-stage',

            'activeTriggerCls': 'selected',

            'delay': 0.2,

            'effect': 'fade',

            'easing': 'easeBoth',

            'duration': 0.8,

            'autoplay': false,

			}”>

     <!--  code  -- >

	</div>

參數配置列表

配置參數	參數可選值	作用說明
effect	none/fade/scrolly/scrollx (默認值：none)	切換時的動畫效果 none, 最樸素的顯示/隱藏效果 fade, 可實現淡隱淡現的效果 scrolly, 垂直滾動 scrollx, 水平滾動
easing	easeOutStrong/easeBoth	滾動的動畫方方式
countdown	true/false (默認值：false)	是否開啟倒計時樣式
countdownFromStyle	自定義值	設定倒計時最終樣式如: width:15px 表示進度條最終寬度,可先在CSS里對樣式進行定義
navCls	自定義值	對其進行輪播的目標列表的class值
contentCls	自定義值	輪播列表所對應的內容列表的class值
delay	自定義數值 (默認值：1)	延遲加載時間 .1 == 100ms
triggerType	mouse/click<> (默認值：mouse)br	觸發方式—— mouse：鼠標經過觸發 click：鼠標點擊觸發
hasTriggers	true/false (默認值：true)	是否設置觸發點
steps	自定義數值 (默認值：1)	切換視圖內有多少個panels
viewSize	自定義值	切換視圖區域的大小。一般不需要設定此值，僅當獲取值不正確時，用于手工指定大小
activeIndex	自定義數值 (默認值：0)	默認激活的列表項
activeTriggerCls	自定義值 (默認值：active)	默認激活列表項的class值
duration	自定義值（默認值：0.5）	動畫時長 .1 = 100ms

Carousel - 旋轉木馬

實例展示

實例一實例二

所需DOM結構

需要滾動的對象依次羅列，包含在內容區的容器中，同時需要兩個不同ID的容器來分別包含上下翻頁的按鈕，另外可以將每一組內容再獨自包含在一個ul列表中。

	<div  class="section  J_TWidget">

    <span id="scroller-prev" class="prev disable">? 上一頁</span>

    <span id="scroller-next" class="next">下一頁 ?</span>

    <div class="scroller">

        <div class="ks-switchable-content">

          <img alt="" src="###"/>

          <img alt="" src="###"/>

         <img alt="" src="###"/>

         <img alt="" src="###"/>

         <img alt="" src="###"/>

         <img alt="" src="###"/>

         <img alt="" src="###"/>

        <img alt="" src="###"/>

        <img alt="" src="###"/>

        </div>

        <ul class="ks-switchable-nav">

            <li class="ks-active">?</li>

            <li>?</li>

            <li>?</li>

        </ul>
    </div>
</div>

組件調用方法

	<div class=”J_TWidget”  data-widget-type=”Carousel”  data-widget-config=”{

            'effect': 'scrollx',

            'easing': 'easeOutStrong',

            'steps': 5,

            'viewSize': [680],

            'circular': false,

            'prevBtnCls': 'prev',

            'nextBtnCls': 'next',

            'disableBtnCls': 'disable',

           }”>

            <!--  code  -- >

</div>

參數配置列表

配置參數	參數可選值	作用說明
effect	none/fade/scrolly/scrollx (默認值：none)	切換時的動畫效果 none, 最樸素的顯示/隱藏效果 fade, 可實現淡隱淡現的效果 scrolly, 垂直滾動 scrollx, 水平滾動
easing	easeOutStrong/easeBoth	滾動的動畫方方式
countdown	true/false (默認值：false)	是否開啟倒計時樣式
countdownFromStyle	自定義值	設定倒計時最終樣式如: width:15px 表示進度條最終寬度,可先在CSS里對樣式進行定義
navCls	自定義值	對其進行輪播的目標列表的class值
contentCls	自定義值	輪播列表所對應的內容列表的class值
delay	自定義數值 (默認值：1)	延遲加載時間，當前顯示圖片到切換其他圖片動作開始，這中間的停留時間 .1 == 100ms
triggerType	mouse/click<> (默認值：mouse)br	觸發方式—— mouse：鼠標經過觸發 click：鼠標點擊觸發
hasTriggers	true/false (默認值：true)	是否設置觸發點
steps	自定義數值 (默認值：1)	切換視圖內有多少個panels
viewSize	自定義值	切換視圖區域的大小。一般不需要設定此值，僅當獲取值不正確時，用于手工指定大小
activeIndex	自定義數值 (默認值：0)	默認激活的列表項
activeTriggerCls	自定義值 (默認值：active)	默認激活列表項的class值
circular	true/false(默認：true)	滾動效果
prevBtnCls	自定義值	上一頁的class值
nextBtnCls	自定義值	下一頁的class值
disableBtnCls	自定義值	按鈕不可用的class值
duration	自定義值(默認：0.5)	動畫時長,一張圖片開始切換到另一張圖片顯示的時間 .1 == 100ms

Accordion - 手風琴

實例展示

實例一實例二

所需DOM結構

需要將菜單中每個標題及其內容分別包含在對應的容器中，最外層容器有唯一的ID來標示組件。

  <div class="J_TWidget section">

    <div class="ks-switchable-trigger ks-active"><h3>標題A</h3></div>

    <div class="ks-switchable-panel">

            內容AAAAA

    </div>

    <div class="ks-switchable-trigger"><h3>標題B</h3></div>
        <div class="ks-switchable-panel" style="display:none;">

            內容BBBBB

        </div>

    <div class="ks-switchable-trigger"><h3>標題C</h3></div>

        <div class="ks-switchable-panel" style="display:none;">

            內容CCCCC

        </div>

    <div class="ks-switchable-trigger last-trigger"><h3>標題D</h3></div>

        <div class="ks-switchable-panel last-panel" style="display:none;">

            內容DDDDD

     </div>

    </div>

組件調用方法

	<div class=”J_TWidget”  data-widget-type=”Accordion”  data-widget-config=”{

             'triggerType': 'click',

             'multiple':true

     }”>

             <!--  code  -- >
  </div>

配置參數列表

配置參數	參數可選值	作用說明
triggerCls	自定義值	主列表的class值
panelCls	自定義值	列表所對應的內容列表的class值
triggerType	mouse/click (默認值：click)	觸發方式—— mouse：鼠標經過觸發 click：鼠標點擊觸發
multiple	true/false (默認值：false)	是否同時支持多面板展開
hasTriggers	true/false (默認值：true)	是否設置觸發點

Popup - 彈出層

實例展示

實例一實例二

所需DOM結構

本組件作為一個彈出層的效果，通過預先設置一個隱藏的彈出層，并且設置該彈出層的觸點，通過鼠標滑入和移出觸點來展示和隱藏彈出層效果

<div class="first-trigger">我只是個觸點而已，把鼠標滑到我身上</div>

<div class="J_TWidget hidden" data-widget-type="Popup" data-widget-config="{
          'trigger':'.first-trigger',
          'align':{
                  'node':'.first-trigger',
                  'offset':[0,0],
                  'points':['cr','cc']
                  }
            }">
    <div style="background-color: yellow; height: 100px; width: 100px;">
       我是一個彈出層
    </div>
</div>

組件調用方法

	 <div class="J_TWidget hidden" data-widget-type="Popup" data-widget-config="{
          'trigger':'.first-trigger',
          'align':{
                  'node':'.first-trigger',
                  'offset':[0,0],
                  'points':['cr','cc']
                  }
            }">
    <!--  code  -- >
   </div>

配置參數列表

配置參數

參數可選值

作用說明

trigger

自定義

觸點元素，就是鼠標滑過哪個元素的時候彈出當前的popup，支持class和id選擇器的寫法

align

node,points,offset 三個配置

node: ‘自定義’, // 參考元素。 popup與參考元素進行定位。和觸點寫法一樣，

支持class和id選擇器的寫法

points: [tr,tl],  // ['tl', 'tr']表示popup的tl 與參考節點的 tr 對齊 ，

                     具體tl，tr表示的意義和值看下面截圖, 

                     t(top)，c(center), b(bottom),l(left),r(right)

offset: [0,0]     // 有效值為 [n, m] ， points對齊后，offset值，

                      一般可用于微調, n和m分別表示對齊兩個點

                      在x,y坐標之間的偏移量

配置項align中的points的說明

觸點與彈出層的對齊方式（align中的points配置）元素及參考元素上各自的九個不同位置點('tl', 'tc', 'tr', 'cl', 'cc', 'cr', 'bl', 'bc', 'br') 如下圖所示:

demo 代碼，直接復制到自定義內容區里面，保存-預覽就可以到效果了哈。大家發揮自己的想象力吧。

	 <div class="first-trigger">我只是個觸點而已，把鼠標滑到我身上</div>

     <div class="J_TWidget hidden" data-widget-type="Popup" data-widget-config="{
          'trigger':'.first-trigger',
          'align':{
                  'node':'.first-trigger',
                  'offset':[0,0],
                  'points':['cr','cl']
                  }
            }">
    <div style="background-color: blue; height: 100px; width: 100px;">
       我是一個彈出層
    </div>
    </div>

demo 代碼，直接復制到自定義內容區里面，保存-預覽就可以到效果了哈。大家發揮自己的想象力吧。

	 <div class="first-trigger">我只是個觸點而已，把鼠標滑到我身上</div>

     <div class="J_TWidget hidden" data-widget-type="Popup" data-widget-config="{
          'trigger':'.first-trigger',
          'align':{
                  'node':'.first-trigger',
                  'offset':[0,0],
                  'points':['cr','cl']
                  }
            }">
    <div style="background-color: blue; height: 100px; width: 100px;">
       我是一個彈出層
    </div>
    </div>

注意：觸點目前只允許包含在#content內。不允許影響頁頭頁尾：

Countdown - 倒計時

實例展示

實例一實例二

組件調用方法及所需DOM結構

	<!-- 配置項中的class名前別忘了加點號哦 -->
    <div class="J_TWidget" data-widget-type="Countdown"  data-widget-config="{
     'endTime': '20000',
     'interval': 1000,
     'timeRunCls': '.ks-countdown-run',
     'timeUnitCls':{
    'd': '.ks-d',      
    'h': '.ks-h',      
    'm': '.ks-m',      
    's': '.ks-s',      
    'i': '.ks-i'       
     },
     'minDigit': 1,
     'timeEndCls': '.ks-countdown-end'
     }">
    <!-- 倒計時結束時隱藏-->
    <!--可以寫多個 -->
    <div class="ks-countdown-run">
    <span class="ks-d"></span>天
    <span class="ks-h"></span>小時
    <span class="ks-m"></span>分
        <!-- 如果有0.1秒級別的變化建議以gif背景圖片的形式變化 -->
    <span class="ks-s"></span>秒
        
    <span class="ks-i"></span>毫秒
    </div>
    <div class="ks-countdown-run"></div>
   
     <!-- 倒計時結束時顯示-->
     <!--可以寫多個 -->
    <div class="ks-countdown-end">
    倒計時結束了,干點什么吧
        把什么隱藏起來，或者把什么顯示出來
    </div>
    <div class="ks-countdown-end">
    </div>
   </div>

配置參數列表

配置參數	參數可選值	作用說明
endTime	毫秒數（多少毫秒后倒計時結束），或者日期格式時間（格式：2011-7-21 11:01:01）	倒計時結束時間例如：毫秒數： 'endTime': '2011-7-21 11:01:01' 或日期格式： 'endTime': '10000'
interval	單位：毫秒，取值范圍（>=100毫秒），默認值為1000毫秒	倒計時刷新間隔（單位為毫秒/次）即每隔多少毫秒刷新一次例如：interval = 2000, 那么屏幕上的時間每次變化時會少兩秒
timeRunCls	自定義值	有此class名的標簽，其內容在倒計時運行時顯示,倒計時結束時隱藏
timeUnitCls	時間單位的組合值,每個時間單位的class名自定義	設定時間單位b標簽的class 例如:{ 'd': '.ks-d', //天 'h': '.ks-h', //小時 'm': '.ks-m', //分 's': '.ks-s', //秒 'i': '.ks-i' //毫秒 }
minDigit	數據類型：整數，取值范圍（>=1），默認為1，	每個時間單位值顯示的最小位數，意思是超過不截斷，少則前面補0顯示例如：digit = 2 少于情形：2天4小時10分20秒，則應該顯示02天04小時10分20秒超過情形：400分20秒，則應該顯示 400分20秒
timeEndCls	自定義值	有此class名的標簽，其內容在倒計時運行時隱藏,倒計時結束時顯示

Compatibe - 兼容性組件

實例展示

組件調用方法及所需DOM結構

	兼容組件的第一個作用：ie 6的position:fixed;
<div class="J_TWidget" data-widget-type="Compatible" data-widget-config="{'fixed':true}"
     style="position:fixed;top:50px;left:40px;">
    這是解決ie6的懸浮組件
</div>
  
第二種兼容的第二個作用：png在ie6下的透明
<div class="J_TWidget"
     style="height:40px;width:40px;background-image: url(//img.alicdn.com/tps/i1/T1g604XjdrXXXXXXXX-24-24.png);"
     data-widget-type="Compatible" data-widget-config="{'png':true,'png_bg':true}">
    背景透明
</div>
<!-- img標簽透明 -->
<img class="J_TWidget" src="//img.alicdn.com/tps/i1/T1g604XjdrXXXXXXXX-24-24.png"
     data-widget-type="Compatible" data-widget-config="{'png':true,'png_tag':true}"/>

配置參數列表

配置參數	參數可選值	作用說明
fixed	可選值true / false，默認false	需要用兼容組件解決的問題，是否是ie 6下面的position:fixed
png	可選值true / false，默認false	需要用兼容組件解決的問題，是否是在ie 6下面的png透明
png_bg	可選值true / false，默認false	需要透明的png圖片，是否是背景圖
png_tag	可選值true / false，默認false	需要透明的png圖片，是否是img標簽元素

二維碼圖片組件

模塊PHP代碼中添加HTML代碼，例如：

<img src="http://chart.apis.google.com/chart?chs=<?=$width.x.$height ?>&cht=qr&chl=<?=$url?>"/></div>

其中，$width為圖片寬度，$height為圖片高度，$url為網頁的地址，如果設計師想做寶貝的二維碼，可以使用寶貝的詳情頁地址。

比如：

$width = 188; $height = 188; $url = www.taobao.com

運行結果地址：

http://chart.apis.google.com/chart?chs=188x188&cht=qr&chl=www.taobao.com

購物車組件

模塊PHP代碼中添加HTML代碼，DOM上綁定一個class。

例如：

<a href="#" class=" J_CartPluginTrigger" target="_blank">購物車</a>

收藏寶貝組件

模塊PHP代碼中添加HTML代碼，例如：

<a href="http://favorite.taobao.com/popup/add_collection.htm?id=<?=$item->id ?>&itemtype=1&scjjc=1" target="_blank">收藏</a>

其中，$item->id為寶貝的ID。

分享組件

http://t.taobao.com/platform/favorSeller.htm?spm=0.0.0.53.LPEvXL

關于Kissy

淘寶發布開源編輯器：KISSY Editor，和我們在 WordPress 后臺使用的富文本編輯器 TinyMCE 一樣，它可以讓我們在線編輯和格式化文本，但是相比 TinyMCE KISSY Editor 更加輕巧，更加適合國內的網絡環境。 KISSY Editor 是開源項目 KISSY UI Library 的一個組件。KISSY 目前基于 YUI 2.x 開發，目標是打造一系列小巧靈活、簡潔實用、使用起來讓人感覺愉悅的 UI 組件，目前已有 CSS 基礎框架、搜索提示 Suggest 和 KISSY Editor 這個富文本編輯器等組件。

支持效果

目前kissy中開放，能直接調用的效果組件為switchable，其中包括四種widget，tabs（標簽頁），Slide（卡盤），Carousel（旋轉木馬），Accordion（手風琴）雖然只有四種效果，但實際上，通過kissy中開放的配置（對應sdk中的data-widget-config），以及不同的dom結構，與css控制，可以展示出各種各樣的效果。下面是互聯網中，部分電子商務網站首頁的一些效果截圖附件中會給出，sdk中如何通過淘寶提供的J_TWidget實現其中的效果。

Tabs：

Slide：

其中“土豆今日焦點”這個組件中，當縮略圖的切換時，上面的內容和左側的大圖同時切換，這個略微特殊一點，用到了兩個slide，用一個ks-switchable-nav來控制兩個ks-switchable-content的切換。

編寫心得

拿其中一個dom結構為例，kissy中開放效果，只要把握其中這樣幾點。

最外層dom結構：id為demo這個div標簽，組件的最外層dom結構。
組件中的dom結構：包含在id為demo里面的div結構里面的結構。
class=”J_TWidget”：用來表示這個div是一個組件，我們要用kissy來渲染這個組件。
data-widget-type="Tabs":這個是用來告訴sdk，我們的widget組件要用什么方式來渲染。
data-widget-config=”{….}”: 這個是組件的相關配置，也是很靈活的一部分
class=”ks-switchable-nav” : 這個用來定義當前組件進行輪播的目標列表的class值。
PS:我們更推薦用戶去自定義一個class來覆蓋這個淘寶默認的鉤子，方法為在data-widget-config中。
data-widget-config="{ 'navCls': '自定義的class'}"，這樣也方便設計師定義樣式。
class="ks-switchable-content"：用來定義輪播列表所對應的內容列表的class值。
PS:我們更推薦用戶去自定義一個class來覆蓋這個淘寶默認的鉤子，方法為在data-widget-config中, data-widget-config="{ 'contentCls': '自定義的class'}"，這樣也方便設計師定義樣式class=”ks-active” : 當前正在輪播的對象（可以用這個來動態應用樣式）

樣例代碼

	 <div  class="J_TWidget"  data-widget-type="Tabs"  data-widget-config="{
            'effect': 'none',
            'autoplay': 'auto',
            'circular': true
      }">
      <ul class="ks-switchable-nav">
        <li class="ks-active">標題 A</li>
        <li>標題 B</li>
        <li>標題 C</li>
        <li>標題 D</li>
        <li>標題 E</li>
    </ul>
    <div class="ks-switchable-content">
     <div>

	    tabs 標簽的展示效果是可以通過配置改變的，比如，改變effect ，autoplay 等
       tabs 標簽的展示效果是可以通過配置改變的，比如，改變effect ，autoplay 等
       tabs 標簽的展示效果是可以通過配置改變的，比如，改變effect ，autoplay 等
       tabs 標簽的展示效果是可以通過配置改變的，比如，改變effect ，autoplay 等

	       </div>
        <div style="display: none;">這里還可以放置一些圖片，比如像百度首頁下面的那個</div>
        <div style="display: none;">至于如何使用tab，大家可以盡情發揮</div>
        <div style="display: none;">這是最內容D ，這是最內容D</div>
        <div style="display: none;">
            這個div里面放置任何你想要放的dom結構，你所要做的就是用過css，控制dom的展示
        </div>
        </div>
        </div>

附錄：SDK 的J_TWidget源代碼在附件中，直接在sdk中新建一個模板，然后覆蓋其中的index.php，就可以看到效果了。代碼很簡單，就是按照規范寫dom結構，然后用css控制下樣式就ok了。相信你看完樣例，就可以很好的使用我們提供的widget了。

下載范例代碼

查看更多效果組件

本文地址：http://www.obd2space.com/Clip/doc.html

分享到：QQ空間新浪微博騰訊微博人人網網易微博微信