淘宝Widget规范

1、Widget规范出自淘宝网店铺开发者WIKI跳转到： 导航, 搜索目录隐藏· 1 概述· 2 使用方法o 2.1 Tabs - 标签页§ 2.1.1 实例展示§ 2.1.2 所需DOM结构§ 2.1.3 组件调用方法§ 2.1.4 配置参数列表o 2.2 Slide卡盘效果§ 2.2.1 实例展示§ 2.2.2 所需DOM结构§ 2.2.3 组件调用方法§ 2.2.4 参数配置列表o 2.3 Carousel - 旋转木马§ 2.3.1 实例展示§ 2.3.2 所需DOM结构

2、§ 2.3.3 组件调用方法§ 2.3.4 参数配置列表o 2.4 Accordion - 手风琴§ 2.4.1 实例展示§ 2.4.2 所需DOM结构§ 2.4.3 组件调用方法§ 2.4.4 配置参数列表o 2.5 Popup - 弹出层§ 2.5.1 实例展示§ 2.5.2 所需DOM结构§ 2.5.3 组件调用方法§ 2.5.4 配置参数列表§ 2.5.5 配置项align中的points的说明· 3 关于Kissy· 4 支持效果· 5 编写心得

3、· 6 样例代码概述 实际的开发中需要用到一些功能比较丰富的主机，如图片轮播，tab标签等，这些组件都需要设计师写Javascript才能完成，考虑前期JavaScript是不对设计师开放的，所以淘宝要提供一些widget库，方便设计调用，形成特定的组件。通过载入淘宝的js框架来渲染。<div class="J_TWidget" data-type="Slide" data-cfg=""><!- code - ></div>我们会获取名字叫 J_TWidget 的元素, 并根据其类型和配置

4、信息, 渲染相应的效果。使用方法 目前淘宝提供的widget 分为5种:· Tabs - 标签页· Slide - 卡盘· Carousel - 旋转木马· Accordion - 手风琴· Popup - 弹出层 针对每种不同的动画效果需要通过配置不同的参数，配合不同的DOM结构。以下依次介绍每种不同的动画效果的配置参数以及其DOM结构Tabs - 标签页实例展示 实例一 实例二 所需DOM结构本组件对DOM结构没有特殊要求，调用只需要按顺序将ul列表中每个元素跟内容元素一一对应即可，当然触点和内容都必须包含在唯一的外层容器里面。<di

5、v 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> -预先

6、加载的内容- </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=”

7、 'effect': 'fade', 'autoplay': true, 'circular': true ”><!- code - ></div>配置参数列表配置参数参数可选值作用说明effectnone/fade/scrolly/scrollx(默认值：none)切换时的动画效果none, 最朴素的显示/隐藏效果fade, 可实现淡隐淡现的效果scrolly, 垂直滚动scrollx, 水平滚动easingeaseOutStrong/easeBoth滚动的动画方方式countdowntrue/fa

8、lse (默认值：false)是否开启倒计时样式countdownFromStyle自定义值设定倒计时最终样式如: width:15px 表示进度条最终宽度,可先在CSS里对样式进行定义navCls自定义值对其进行轮播的目标列表的class值contentCls自定义值轮播列表所对应的内容列表的class值delay自定义数值 (默认值：1)延迟加载时间.1 = 100mstriggerTypemouse/click<>(默认值：mouse)br触发方式mouse：鼠标经过触发click：鼠标点击触发hasTriggerstrue/false (默认值：true)是否设置触发点st

9、eps自定义数值 (默认值：1)切换视图内有多少个panelsviewSize自定义值切换视图区域的大小。一般不需要设定此值，仅当获取值不正确时，用于手工指定大小activeIndex自定义数值 (默认值：0)默认激活的列表项activeTriggerCls自定义值 (默认值：active)默认激活列表项的class值autoplaytrue/false (默认值：true)是否自动播放circulartrue/false (默认值：true)是否有循环滚动效果duration自定义值（默认值：0.5）动画时长.1 = 100msSlide卡盘效果实例展示 超帅图片轮播 淘小二推荐 实例一 实

10、例二 实例三 所需DOM结构本组件需要将滚动的对象作为一个ul列表，包含在外层的容器中，同时容器里还需要定义一个容器来放置列表中对应项的具体内容。<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>组件调用方法<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>参数配置列表配置参数参数可选值作用说明effectnone/fade/scrolly/scrollx(默认值：none)切换时的动画效果none, 最朴素的显示/隐藏效果fade, 可实现淡隐淡现的效果scrolly, 垂直滚动scrollx, 水平滚动easingeaseOutStrong/easeBoth滚动的动画方方式countdowntrue/false (默认值：false)是否开启倒计时样式countdownFromStyle自定义值设定

15、倒计时最终样式如: width:15px 表示进度条最终宽度,可先在CSS里对样式进行定义navCls自定义值对其进行轮播的目标列表的class值contentCls自定义值轮播列表所对应的内容列表的class值delay自定义数值 (默认值：1)延迟加载时间.1 = 100mstriggerTypemouse/click<>(默认值：mouse)br触发方式mouse：鼠标经过触发click：鼠标点击触发hasTriggerstrue/false (默认值：true)是否设置触发点steps自定义数值 (默认值：1)切换视图内有多少个panelsviewSize自定义值切换视图区

16、域的大小。一般不需要设定此值，仅当获取值不正确时，用于手工指定大小activeIndex自定义数值 (默认值：0)默认激活的列表项activeTriggerCls自定义值 (默认值：active)默认激活列表项的class值duration自定义值（默认值：0.5）动画时长.1 = 100msCarousel - 旋转木马实例展示 实例一 实例二 所需DOM结构需要滚动的对象依次罗列，包含在内容区的容器中，同时需要两个不同ID的容器来分别包含上下翻页的按钮，另外可以将每一组内容再独自包含在一个ul列表中。<div class="section J_TWidget"&g

17、t; <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="

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

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>参数配置列表配置参数参数可选值作用说明effectnone/fade/scrolly/scrollx(默认值：none)切换时的动画效果none, 最朴素的显示/隐藏效果fade, 可实现淡隐淡现的效果scrolly, 垂直滚动scrollx, 水平滚动easingeaseOutStrong/easeBoth滚动的动画方方式countdowntrue/false (默认值：false)是否开启倒计时样式countdownFromStyle自定义值

22、设定倒计时最终样式如: width:15px 表示进度条最终宽度,可先在CSS里对样式进行定义navCls自定义值对其进行轮播的目标列表的class值contentCls自定义值轮播列表所对应的内容列表的class值delay自定义数值 (默认值：1)延迟加载时间，当前显示图片到切换其他图片动作开始，这中间的停留时间.1 = 100mstriggerTypemouse/click<>(默认值：mouse)br触发方式mouse：鼠标经过触发click：鼠标点击触发hasTriggerstrue/false (默认值：true)是否设置触发点steps自定义数值 (默认值：1)切换视

23、图内有多少个panelsviewSize自定义值切换视图区域的大小。一般不需要设定此值，仅当获取值不正确时，用于手工指定大小activeIndex自定义数值 (默认值：0)默认激活的列表项activeTriggerCls自定义值 (默认值：active)默认激活列表项的class值circulartrue/false(默认：true)滚动效果prevBtnCls自定义值上一页的class值nextBtnCls自定义值下一页的class值disableBtnCls自定义值按钮不可用的class值duration自定义值(默认：0.5)动画时长,一张图片开始切换到另一张图片显示的时间.1 = 10

24、0msAccordion - 手风琴实例展示 实例一 实例二 所需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> &l

25、t;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-swit

26、chable-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>组件调

27、用方法<div class=”J_TWidget” data-widget-type=”Accordion” data-widget-config=” 'triggerType': 'click', 'multiple':true ”> <!- code - ></div>配置参数列表配置参数参数可选值作用说明triggerCls自定义值主列表的class值panelCls自定义值列表所对应的内容列表的class值triggerTypemouse/click (默认值：click)触发方式mouse：鼠标经过触

28、发click：鼠标点击触发multipletrue/false (默认值：false)是否同时支持多面板展开hasTriggerstrue/false (默认值：true)是否设置触发点Popup - 弹出层实例展示 实例一 实例二 所需DOM结构本组件作为一个弹出层的效果，通过预先设置一个隐藏的弹出层，并且设置该弹出层的触点，通过鼠标滑入和移出触点来展示和隐藏弹出层效果<div class="first-trigger">我只是个触点而已，把鼠标滑到我身上</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;"> 我是一个弹出层 </div></div>组件调用方法<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>配置参数列表配置参数参数可选值作用说明trigger自定义触点元素，就是鼠标滑过哪个元素的时候弹出当前的popup，支持class和id选择器的写法alignnode,points,offset 三个配置node: 自定义, / 参考元素。 popup与参考元素进行定位。和触点写法一样，支持class和id选择器 的写法points: tr,tl, / 'tl', 'tr' 表示popup的tl 与参考节点的 tr

32、对齐 ， 具体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', &

33、#39;bl', 'bc', 'br') 如下图所示:demo 代码，直接复制到自定义内容区里面，保存-预览就可以到效果了哈。大家发挥自己的想象力吧。<div class="first-trigger">我只是个触点而已，把鼠标滑到我身上</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;"> 我是一个弹出层 </div></div>demo 代码，直接复制到自定义内容区里面，保存-预览就可以到效果了哈。

35、大家发挥自己的想象力吧。<div class="first-trigger">我只是个触点而已，把鼠标滑到我身上</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;"> 我是一个弹出层 </div></div>注意： 触点目前只允许包含在#content内。不允许影响页头页尾：关于Kissy 淘宝发布开源编辑器：KISSY Editor，和我们在 WordPress 后台使用的富文本编辑器 TinyMCE 一样，它可以让我们在线编辑和格式化文本

37、，但是相比 TinyMCE KISSY Editor 更加轻巧，更加适合国内的网络环境。 KISSY Editor 是开源项目 KISSY UI Library 的一个组件。KISSY 目前基于 YUI 2.x 开发，目标是打造一系列小巧灵活、简洁实用、使用起来让人感觉愉悦的 UI 组件，目前已有 CSS 基础框架、搜索提示 Suggest 和 KISSY Editor 这个富文本编辑器等组件。支持效果 目前kissy中开放，能直接调用的效果组件为switchable，其中包括四种widget，tabs（标签页），Slide（卡盘），Carousel（旋转木马），Accordion（手风琴）

38、虽然只有四种效果，但实际上，通过kissy中开放的配置（对应sdk中的data-widget-config），以及不同的dom结构，与css控制，可以展示出各种各样的效果。 下面是互联网中，部分电子商务网站首页的一些效果截图 附件中会给出，sdk中如何通过淘宝提供的J_TWidget实现其中的效果。Tabs：Slide：· 其中“土豆今日焦点”这个组件中，当缩略图的切换时，上面的内容和左侧的大图同时切换，这个略微特殊一点，用到了两个slide，用一个ks-switchable-nav来控制两个ks-switchable-content的切换。编写心得 拿其中一个dom结构为例，kis

39、sy中开放效果，只要把握其中这样几点。最外层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-wi