首页 教程 API文档

基础组件模块

2015-10-10 09:19:45

属性


依赖模型 events, plugin
使用频率
所属模块 Std.ui

描述


UI模块widget是一个基础的UI组件,该组件提供了大量的基础成员方法,通常情况下在创建一个UI组件的时候,使用widget作为基础组件来进行继承.

widget实例或者继承于widget的模块实例如果使用isWidget方法来进行判断的时候,会返回true

我们建议你在创建所有UI组件模块的时候都使用widget作为继承条件,这可以让你在开发UI组件的时候省下极大量的代码.

相关原理


widget实例在被创建的同时也会创建一个DOM对象,在widget内部方法中使用 this[0] 来获取这个DOM对象

当一个widget实例被创建之后,要使其呈现在网页上生效,需要在参数选项中有renderTo选项,或者执行方法renderTo, 如果参数选项中有appendTo或者prependTo,那么需要执行render()方法,总之最后都会调用到render方法,而renderTo方法 相当于appendTo加上render

widget的主函数在执行时候会首先判断选项中是否存在css这个键,如果存在,则调用this[0].css方法给DOM元素增加css样式, 然后判断是否存在appendTo以及prependTo键,根据键值执行对应成员函数.

当主函数执行完毕之后,会判断参数选项中是否存在renderTo这个键,如果存在,则执行renderTo方法渲染widget.

渲染函数render,在被执行的时候,会首先调用beforeRender函数,将this.opts作为参数传递过去,而beforeRender函数在执行完毕之后会触发 beforeRender事件,然后成员变量renderState会被表示为true

随之,render方法会调用成员函数init_boxSize进行widget的DOM元素的盒型大小数据进行初始化. 然后会判断参数选项中的initSize是否为true,如果为true,则设置widget的宽度与高度,之后判断this.opts中的left与 top值是否为null,如果不为null值的时候,widget会调用DOM元素上的css方法设置这些值.

然后,widget会判断参数选项(this.opts)中的visible,与enable是否为false,如果为false,执行对应名称的成员函数, 当这部被完成了,还会判断参数选项中是否有plugins键,如果存在,则给widget装入指定的插件.

最后判断参数选项中的contentType是否为null,如果不为null,则执行init_content方法填充widget的内容,当这部完成之后, 发射最终事件 this.__emit__("render")

需要注意的是__emit__方法,例如render方法在widget被继承了之后,扩展了render方法,__emit__方法也是在被扩展的函数执行 完毕之后才触发事件的.

成员列表


方法名称 成员类型 描述
init_boxSize public 初始化盒型尺寸
init_content public 初始化内容
renderState protected 渲染状态
boxSize protected 盒型尺寸
show public 显示widget
hide public 隐藏widget
hasClass public 判断class是否存在
addClass public 添加class名称
removeClass public 移除class
toggleClass public 切换class
className public 读写class名称
minWidth public 最小宽度
minHeight public 最小高度
maxWidth public 最大宽度
maxHeight public 最大高度
enable public 读写启用状态
disable public 读写禁用状态
visible public widget的可见状态
focus public 让widget获得焦点
blur public 让widget失去焦点
valid public 判断value是否有效值
toForeground public 置顶
beforeRender public widget渲染之前的行为
appendTo public 追加到指定位置
html public html内容
iframe public widget的iframe
url public ajax载入数据的url
animation public widget动画
updateLayout public 更新layout
layout public widget的layout
on public 添加事件
off public 移除事件
move public 移动widget
left public 读写widget的left值
top public 读写widget的top值
opacity public widget的不透明度
renderTo public 渲染widget到指定位置
size public widget的大小
width public widget的宽度
height public widget的高度
render public 渲染widget
destroy public 销毁widget
remove public 删除操作
removeLayout public 移除layout
parent public widget的父对象
level public widget等级
value public 读写value值
validator public value值验证规则
invalidText public 无效value对应的文本
fixedLayoutWidth public 固定的布局宽度
fixedLayoutHeight public 固定的布局高度

参数选项


名称 类型 默认值 描述
level Number 2 widget的等级,当使用layout模块来管理widget布局的时候,该值会直接影响自身的布局方式
parent Object null 父对象
renderTo Object,String null 需要渲染到的目标位置,可以为一个widget,或者一个DOM元素,Std.dom元素,或者一个css选择器字符串
objectName String Empty String widget实例的对象名称
defaultClass String Empty String widget默认DOM对象的默认class值
className String Empty String widget实例中默认DOM对象需要添加的class名称
tabIndex Number 1 widget的默认tabIndex值,该值影响网页中按下tab键的焦点切换,如果为null,则该元素永远不会有焦点
top Number null widget的DOM元素的css top值
left Number null widget的DOM元素的css left值
width Number auto widget的默认宽度,包含padding-left,padding-right,border-left,border-right值的宽度值
height Number auto widget的默认高度,包含padding-top,padding-bottom,border-top,border-bottom值的高度值
minWidth Number 3 widget最小宽度
minHeight Number 3 widget最小高度
maxWidth Number null widget最大宽度值
maxHeight Number null widget最大高度值
enable Boolean true

默认是否为启用状态,如果为false,表示为禁用状态,该值只是做个标识,在widget中不会有直接的作用.

当值为false的时候,widget的DOM元素会自动添加disabled这个class,为true的时候该class会被移除.

visible Boolean true 默认是否为可见状态,如果为false,表示widget需要被隐藏起来
animation Object null 默认的动画设置
initSize Boolean true 在widget在被渲染的时候,是否需要初始化widget的宽度与高度
plugins Object null 当widget被渲染之后,需要载入的插件
validator String null 数据验证器,成员方法valid将会以此值与自身的value做判断
invalidText String invalid 当value与validator验证不通过的时候的文字,在widget仅做标识记录用
cache Boolean true 当widget的内容使用url方式进行异步请求填充的时候是否需要缓存
value Any null widget实例的默认value值
contentType String Empty String(auto) 填充widget内容的方式,有url,html,iframe,layout 这4种,该值直接决定了以下如何填充widget的内容
data Any null 在widget中只作为保留选项,无直接作用
url String null 通过ajax方式载入指定url的内容,并且填充widget
html String null 需要填充widget的html内容
iframe String null 需要填充widget的iframe地址
layout Object null 需要填充widget的layout对象,或者layout配置
fixedLayoutWidth Boolean false 当widget出现在layout中的时候,是否不需要layout来调整自身的高度,而是手动设置的固定宽度
fixedLayoutHeight Boolean false 当widget出现在layout中的时候,是否不需要layout来调整自身的高度,而是手动设置的固定高度
on Object null 默认需要绑定的事件,一个Object对象,键名为事件名称,键值为事件触发时候执行的函数
css Object null 默认需要在widget的DOM元素上添加的css风格值
appendTo Object,String null 需要将widget的DOM元素追加到的目标位置,可以为一个widget,DOM元素,或者css选择器
prependTo Object,String null 需要将widget的DOM元素前置到的目标位置,可以为一个widget,DOM元素,或者css选择器

事件


以下这些事件是通过widget来管理的,如果添加的不是以下名称的事件,那么事件会被绑定到widget中的DOM元素上.

继承widget的组件可以在创建模块时候可以在events配置中指定事件名称.

名称 回调参数 描述
create 当widget实例被创建之后,主函数执行之前,create事件将会被触发
beforeRender widget渲染之前触发的事件,当该事件被触发之后widget会随之被渲染
load

当使用html填充数据的时候,回调参数为html字符串

当使用iframe方式填充时候,回调参数为iframe的DOM对象(onload之后触发)

当使用url方式填充的时候,回调参数为url中的数据(数据载入之后触发)

当使用layout方式填充的时候,毁掉参数为layout实例对象

当内容被填充完毕之后才会触发的事件,通常情况下只有当widget作为正文展示的时候才需要填充内容
resize 回调参数是一个Object对象,如果宽度改变了,那么这个Object的键将会是width,高度改变了,键名将会是height,其中值为改变之后的值. 当widget的大小改变的时候,使用width或者height方法之后,resize事件将会在内部被__emit__方法触发
render 当widget被渲染完毕的时候,也就是render方法被执行完毕之后,render方法内部会使用__emit__方法触发render事件
remove 当widget被移除的时候,通常为执行remove方法之后,内部会使用__emit__方法触发render事件
enable 当前的enable状态Boolean值 当执行了enable方法修改状态值之后,enable事件将会被触发
visible 当前的visible状态值(Boolean类型) 当visible方法被执行完毕之后,visible事件将会被触发

相关例子


例子:


//创建一个widget,渲染到body,点击时候删除自身,简单
var widget = Std.ui("widget",{
    renderTo:"body",
    width:100,
    height:100,
    on:{
        click:function(){
            widget.remove();
        }
    }
});