1.1. YAHOO 工具库提供的方法
l namespace
用于创建一个全局的命名空间,使用 YUI 时,首先会自动创建 widget,util,example 三个命名空间,使用时也可以自定义命名空间。类似于在程序中建了了一个 static 变量。
l lang
javascript 扩展的语言工具,用于判别对象的类型。
l lang.extend
用于从一个对象上扩展出另一个对象,模拟了类的继承的方式,但不同的是,在创建子对象时,父对象的构造函数不会自动调用。父对象的引用存放在了子对象的 supperclass 中,构成了一个链状继承关系。在 2.2.2 的版本中, YAHOO.lang.extend 和 YAHOO.extend 指向同一函数对象。
l lang.augment
将一个对象的属性(部分或全部)复制到另一个对象,但并非真正意义上的复制,只是一种引用。 YAHOO.augment=YAHOO.lang.augment 。
l log
用来调试的一个工具,将信息显示到 log 控件。
l env
环境信息和 YUI 组件信息
l YUI_config.listener
可以定义自己的回调函数,当有新的 YUI 组件加载到页面时将会调用 YUI_config.listener 指向的函数。
2. YUI 提供的 Dom 操作
特点: 对于大部分 DOM 操作提供了批量操作的功能,而对用户只需使用统一的函数接口就能完成单个或批量的操作,主要得益于 DOM 内部的 batch 方法。
2.1. Element 的查找
YAHOO.util.Dom.get(element)
调用 document.getElementById(element) ,获取指定的页面元素。
YAHOO.util.Dom.getElementsBy(method,tagName,rootNode)
在 rootNode 的子节点中按照用户提供的 method 方法在所有标签为 tagName 的 element 中查找符合条件的节点。 rootNode 不指定则在整个 Document 中查找, method 是一个 method(elementID) 类型的函数对象,该函数对象的返回值为 Boolean 值。
YAHOO.util.Dom.getElementsByClassName(className, tagName, rootNode)
返回指定根节点下所有标签为 tagName,class 为 className 的 DOM 节点数组。根节点为可选参数,不指定时在整个页面中查找
YAHOO.util.Dom.inDocument (el)
判断元素 el 是否在当前的 DOM 中,支持批量操作。
2.2. 样式控制和访问
YAHOO.util.Dom.hasClass(element, className)
判断 element 标签上是否指明了 className 的 class ,支持批量操作
YAHOO.util.Dom.addClass(element, className)
给指定标签增加名为 className 的 class ,支持批量操作 .
YAHOO.util.Dom.removeClass(element, className)
删除 element 上的名为 className 的 class ,支持批量操作
YAHOO.util.Dom.replaceClass(element, oldClassName, newClassName)
替换 element 上的 oldClassName 样式为 newClassName ,支持批量操作
YAHOO.util.Dom.getStyle(element, property)
获取 element 的 style 中的 property 属性,支持批量操作
YAHOO.util.Dom.setStyle(element,property,pValue)
设置 element 的 style 的 property 属性为 pValue ,支持批量操作
注:本节中的 class 指的是 CSS 中定义的 class 。
2.3. 位置控制和访问
位置控制的相关函数
YAHOO.util.Dom.setX
YAHOO.util.Dom.setY
YAHOO.util.Dom.setXY
YAHOO.util.Dom.getX
YAHOO.util.Dom.getXY 返回元素坐标 [ left,top ]
YAHOO.util.Dom.getRegion
获取元素的坐标 Region 对象 {left,top,right,bottom}
可支持批量操作
获取页面可视面积的高度和宽度
YAHOO.util.Dom.getClientWidth
YAHOO.util.Dom.getClientHeight
获取 Document 的高度和宽度
YAHOO.util.Dom.getDocumentWidth
YAHOO.util.Dom.getDocumentHeight
获取页面可视区域的高度和宽度(不包含滚动条)
YAHOO.util.Dom.getViewportHeight
YAHOO.util.Dom.getViewportWidth
Region 对象: {left,top,right,bottom}
YUI 提供的一个对象,用于完成多个矩形区域间的计算(如相交,包含。
YAHOO.util.Region.contains(region)
判断是否包含了 region 区域
YAHOO.util.Region.getArea
计算面积
YAHOO.util.Region.intersect(region)
计算与 region 区域的交迭区域
YAHOO.util.Region.union(region)
计算与 region 区域求并集(即包含两个区域的最小区域)
Point 对象: {x,y}
YUI 提供的对象,用于定义坐标点。
3. YUI 提供的 element 工具
YUI 提供了一组操作页面 element 的工具,是对标准 HTML elements 的一种封装,能够直接通操作 element 的实例,使得增加监听器,操作 DOM ,设置 / 获取 element 的属性等工作变得很简单。部分方法是直接调用 YUI 的 DOM 工具集提供的方法,如对 class 操作的相关方法、获取 element 的相关方法等等,在此不再重复。
YAHOO.util.Element(elementId)
创建 element ,如果 elementId 在 Document 中还不存在,仍然可以通过 YUI 对他进行属性设置,增加监听器等操作, Element 工具集会自动等到该 elementId 可用后执行这些操作,实际上真正的操作是等到 contentReady 事件发生后才进行的。
YAHOO.util.Element.appendChild(child)
在 DOM 结构中 element 下增加子节点
YAHOO.util.Element.getElementsByTagName (tag)
获取 tagName 为 tag 的所有页面元素
YAHOO.util.Element.hasChildNodes
判断是否具有子节点
YAHOO.util.Element.insertBefore (element, before)
在元素 before 前插入 element
YAHOO.util.Element.removeChild(child)
删除 DOM 中元素的 child 子节点
YAHOO.util.Element.replaceChild (newNode , oldNode)
替换子节点 oldNode 为 newNode
4. YUI 提供的 Event 工具集
YUI 提供的 Event 工具集简化了浏览器中事件驱动程序的编写,提供了一种简单的接口来定制事件和检查浏览器中的 event 对象。 YUI 事件工具集提供了自定义事件对象 (Custom Event) ,通过自定义事件对象可以 “ 发布 ” 自己感兴趣的时刻或事件,页面中的 YUI 组件能够响应这些自定义的事件并做出回应。
YUI 对事件响应的顺序 :通过 YUI Event 工具集添加的事件,默认是在冒泡过程中执行事件处理函数的。从 DOM 节点上来说,是从子节点向根节点响应事件。
Event 需要的引入
<!-- Dependency -->
build/yahoo/yahoo-min.js
<!-- Event source file -->
build/event/event-min.js
Event 和 Custom Event 分别定义在 YAHOO.util.Event 和 YAHOO.util.CustomEvent 中
Event 工具集提供的方法
YAHOO.util.Event.addListener(element,eventType,fn,obj,override)
参数:
element :为绑定事件的元素 id ,可以是一个数组,以支持批量操作
eventType :为事件类型
fn :为事件响应的回调函数
obj :当 override 为 true 时,为回调函数传入的参数对象;当 override 为 false 时,该参数被忽略。
override :
返回值类型: Boolean
功能: 给指定的 element 绑定事件响应函数
YAHOO.util.Event.removeListener:function(element,eventType,fn)
参数:
element :为绑定事件的元素 id,
eventType :事件类型
fn :为事件响应函数
返回值类型: Boolean
功能: 给指定的 element 解除绑定事件
YAHOO.util.Event.purgeElement ( el , recurse , sType )
参数:
el :为绑定事件的元素 id,
recurse : Boolean 值,是否解除子节点的事件绑定
sType :事件类型
返回值类型: Boolean
功能: 给指定的 element 解除绑定的同一类型的事件,也可以解除子节点上绑定的这一类型的事件
YAHOO.util.on
addListener 的函数别名
YAHOO.util.Event.onAvailable ( p_id , p_fn , p_obj , p_override )
参数:
p_id :为绑定事件的元素 id,
p_fn :为事件响应函数
p_obj :同 addListener 的 obj 参数
p_override :同 addListener 的 override 参数
返回值类型: 无
功能: 当指定的 element 的 p_id 出现时,执行事件响应函数。如果在页面初始化之前执行这一函数,当页面加载时(可能还未完成时),就会执行响应的事件响应函数;如果放在页面加载之后执行这一函数,将以固定的时间轮询,当 element 可用时响应这一事件。这个轮询的的时间是可以配置的,缺省的时间是 10 秒一次。
YAHOO.util.Event.onContentReady ( p_id , p_fn , p_obj , p_override )
参数:
p_id :为绑定事件的元素 id,
p_fn :为事件响应函数
p_obj :同 addListener 的 obj 参数
p_override :同 addListener 的 override 参数
返回值类型: 无
功能: 与 onAvailable 类似,但不同的是事件响应函数是等到 element 可以安全的修改的时候才响应。
YAHOO.util.Event.onDOMReady ( p_fn , p_obj , p_scope )
参数:
p_fn :为事件响应函数
p_obj :同 addListener 的 obj 参数
p_scope :同 addListener 的 override 参数
返回值类型: 无
功能: 当 DOM 第一次可用时执行响应函数。
YAHOO.util.Event.preventDefault ( event)
参数:
event :事件对象
返回值类型: 无
功能: 阻止事件的缺省行为发生。
YAHOO.util.Event.getListeners ( el , sType )
参数:
el : HTML element
sType :事件类型, String 类型
返回值类型: Object{
type :事件类型
fn : addListener 添加的事件响应函数
obj :提供给事件响应函数的参数对象
adjust :否获取缺省的事件监听器
index : UI 事件监听器列表中的位置
}
功能: 阻止事件的缺省行为发生。
YAHOO.util.Event.getTime( event)
参数:
event :事件对象
返回值类型: Date 对象
功能: 获取事件发生时的时间。
YAHOO.util.Event.getTarget(ev , resolveTextNode)
参数:
evt :事件对象
resolveTextNode :
返回值类型: HTML element
功能: 获取事件发生时的页面标签。对于 IE 即 window.event.srcElement
5. YUI 提供的 CSS 样式
5.1. Fonts
字体的规范样式,需要引入 build/fonts/fonts-min.css
5.2. Reset
规范了所有 HTML element 的缺省样式,需要引入 build/fonts/reset-min.css
5.3. Grids
提供了用于页面排版的 CSS 样式,需要引入 build/fonts/grids-min.css
6. YUI 组件
6.1. Connection Manager
提供了访问 XMLHttpRequest 对象的一个简单接口
对象定义:
YAHOO.util.Connect.asyncRequest
Connection 的引入:
<!-- Dependency -->
build/yahoo/yahoo-min.js
<!— 可选项 : 用到事件时引入 -->
build/event/event-min.js
build/connection/connection-min.js
Connection 的使用
1. 创建对象
var transaction = YAHOO.util.Connect.asyncRequest('GET', sUrl, callback, null);
第一个参数:指明 http 请求的方式,可用的方式包括 GET 、 POST 、 HEAD 、 PUT 、 DELETE ,但 PUT 和 DELETE 可能在一些 A 级浏览器上不支持。
第二个参数:请求的 URL
第三个参数:回调函数,用于服务器返回数据时调用的客户端处理程序
第四个参数: POST 方式时,提供给 URL 的 POST 参数信息。
[ 注 ] : A 级浏览器 A-Grade browsers 是 YUI 对浏览器的一个等级划分,具体划分原则详见 http://developer.yahoo.com/yui/articles/gbs/index.html
2. 定义回调函数
l 在异步事物中,可以创建回调函数处理服务器的响应和相关数据,如果你不关心服务器的返回信息,也可以忽略这些回调函数,所有这些回调函数对象都是可选的,然而在大多数情况下,应该至少提供以下三个回调函数:
success :服务器做出有效响应时的回调函数
failure :服务器响应了但提供了错误信息时的回调函数
argument : success 和 failure 为了处理返回信息需要的参数,可以是对象、字符串、数字或者包含了数据的数组。
l 在使用 YAHOO.util.Connect.setForm 上载文件时,需要定义 upload 回调函数代替 success 和 failure
l 在回调函数中 this 将失去作用范围,这种情况下需要通过一个指向父对象的引用的参数来访问对象的成员。为了能够使用对象的方法作为回调函数,并维持成员的作用范围,需要定义回调函数对象的成员 scope ,作为 this 的值。
6.2. Button
对象定义: YAHOO.widget.Button
与传统 HTML Form 的按钮类似,不同的是它的 label 可以与 value 不一致。还可以创建带菜单的按钮,或者 radio button 、 checkbox
分类:
可以创建几种类型的按钮:
button: 普通的下压式按钮,可以在按钮按下时执行用户指定的代码
link: 按下时导航至相应的 URL
submit: 作用相当于 form 的提交按钮
reset:form 的 reset 按钮
checkbox:
radio:
menubutton: 按下时显示隐藏按钮
splitbutton: 按下时执行命令或显示菜单的按钮
使用 Button 必需的引入 :
<!-- CSS -->
build/fonts/fonts-min.css
build/button/assets/button.css
<!-- Dependencies -->
build/yahoo-dom-event/yahoo-dom-event.js
build/element/element-beta-min.js
<!— 使用 menubutton 和 splitbutton 要用到的 -->
build/container/container_core-min.js
build/menu/menu-min.js
<!-- Source file -->
build/button/button-beta-min.js
初始化的方式:
1. 使用替换 <input> 或 <span> 的方式
constructor : YAHOO.widget.Button(sourceElementId,{ 配置集 })
Button 的构造器首先根据 sourceElementId 在 DOM 中查找 <input> ,一旦找到,就通过 DOM 的 replaceChild 方法替换掉 <input>
2. 使用新建的方式
constructor:YAHOO.widget.Button({ 配置集 })
这种情况下根据配置集中指明的父 id(Container) 创建按钮,如果配置集中没有指明按钮则使用 YAHOO.Dom.generateId 生成 button 的 ID,
Button 的配置集
属性名称 | 含义 | 备注 |
id | 替换后的新的 element id |
|
label | 按钮上显示的文字 |
|
check | 按钮选中 / 未选中的状态 | checkbox 用到 |
type | 缺省为 button | |
container | 按钮的父 id | 使用新建方式时会用到 |
srcelement | 使用替换方式时 |
|
menu | 按钮对应的菜单 YAHOO.widget.menu |
|
title | 按钮 title | 没有指定 label 时使用 title |
href | 按钮导航 URL | 仅在按钮类型为 link 时有效 |
target | <a> 中的 target | 仅在按钮类型为 link 时有效 |
tabindex | 按 tab 切换焦点时的顺序号 |
|
onclick | click 事件的响应函数 | onclick:{ |
|
|
|
6.3. ButtonGroup
对象定义: YAHOO.widget.ButtonGroup
ButtonGroup 是一组按钮,同组中只能有一个按钮被选中。根节点为 <div>
6.4. AutoComplete
用户在文本输入框中输入文字时,该组件通过输入的内容查找符合输入条件的内容,并显示出所有符合条件的内容,供用户能够很快的完成正确的输入。
AutoComplete 的引入
<!-- 必须引入 -->
build/yahoo-dom-event/yahoo-dom-event.js
<!-- 可选 : Connection( 用到 XHR 数据源时需要的引入 ) -->
build/connection/connection-min.js
<!-- 可选 : 用到动画效果时需要的引入 -->
build/animation/animation-min.js
<!-- Source file -->
build/autocomplete/autocomplete-min.js
控制 AutoComplete 的配置集
属性名称 | 含义 | 备注 |
animVert | 控制下拉框向下展开的动画效果 |
|
animHoriz | 控制下拉框水平方向展开的动画效果 |
|
animSpeed | 控制动画的速度 |
|
delimChar | 一行显示多条记录时的分隔符,可以是字符串数组或字符串 |
|
maxResultsDisplayed | 结果集的最大显示行数 |
|
minQueryLength | 进行查询前的输入的字符个数 |
|
queryDelay | 用户键入字符后多少秒开始查询,默认 0.5 |
|
autoHighlight | 查询出来的结果集显示后,是否高亮显示第一条,默认为 true |
|
highlightClassName | 高亮显示的样式名,默认为 yui-ac-highlight |
|
prehightlightClassName | 鼠标移动到下拉框的一行上时,那一行的样式,默认为 yui-ac-prehighlight |
|
useShadow | 下拉框是否有阴影 |
|
useIFrame | 下拉框欠套在一个 iframe 中,用于解决 IE 中覆盖 <select> 的问题 |
|
forceSelection | 限制输入内容必须为查询结果中的内容,如果不是则输入内容被删除 |
|
typeAhead | 是否自动根据查询结果的第一条补齐到 autocomplete 中 |
|
allowBrowserAutocomplete | 是否允许浏览器提供的输入框记忆功能,默认为 false |
|
alwaysShowContainer | 是否始终显示查询结果的下拉框,默认为 false |
|
AutoComplete 的使用
1 自定义事件 (CustomEvent)
AutoComplete 除了默认的事件外,还有自定义的事件,以下为 AutoComplete 用到的各种 CustomEvent
事件回调函数 | 含义 | 备注 |
textboxFocusEvent | 输入框获得焦点的事件 | textboxFocus |
textboxKeyEvent | 按键弹起时的事件 | textboxKey |
dataRequestEvent | 发出数据查询请求时的事件 | dataRequest |
dataReturnEvent | 数据查询请求返回时的事件 | dataReturn |
dataErrorEvent | 返回结果为空时的事件 | dataError |
containerExpandEvent | 展开下拉框时的事件 | containerExpand |
typeAheadEvent | 符合条件的结果自动用到第一条记录补齐时的事件 | typeAhead |
itemMouseOverEvent | 鼠标移动到结果项上的事件 | itemMouseOver |
itemMouseOutEvent | 鼠标移出结果项的事件 | itemMouseOut |
itemArrowToEvent | 移动到某一选择项时的事件 | itemArrowTo |
itemArrowFromEvent | 移出某一选择项时的事件 | itemArrowFrom |
itemSelectEvent | 选中某一选择项的事件 | itemSelect |
unmatchedItemSelectEvent | forceSelection 为 false 时,如果输入了不符合查询结果的内容时触发本事件。 | unmatchedItemSelect |
selectionEnforceEvent | 强制从结果集中选择输入项时触发的事件 | selectionEnforce |
containerCollapseEvent | 下拉框收缩时的事件 | containerCollapse |
textboxBlurEvent | 输入框失去焦点时的事件 | textboxBlur |
可以根据需要重载自定义的事件
例:输入框获得焦点时自动进行查询,可以重载 textboxFocusEvent
myAutoComp.textboxFocusEvent.subscribe(
// 发送一个查询条件为空的查询请求
function(){myAutoComp.sendQuery("");}
);
2 格式化下拉框的输出
如果返回的结果集中有多个属性,可以通过重载 formatResult 来格式化结果项的输出
oAutoComp.formatResult = function(oResultItem, sQuery) {
var sMarkup = oResultItem[0] + " (" + oResultItem[1] + ")" ;
return (sMarkup);
}
3 AutoComplete 的数据源
l DS_JSArray
data = ["AAA","BBB","BCC"];
var myDataSource = new YAHOO.widget.DS_JSArray(data);
可以通过 DWR 的方式调用 java 方法获得一字符串数组作为查询的下拉框,并在回调函数中可以直接使用,如:
l DS_JSFunction
l DS_XHR
对于 JSArray 方式取数时, AutoComplete 可以自动根据输入的内容查在 JSArray 中查找符合条件的结果项,但在使用 XHR 方式时, YUI 并没有提供默认的查找功能,必须由用户通过控制 URL 参数方式来实现这一功能。
JSON 方式:
使用 JSON 格式时,创建数据源 YAHOO.widget.DS_XHR 时第一个参数为请求的 URL ,第二个参数为一数组,这一数组的第一条记录表示结果集在 JSON 对象的哪个对象属性下,如类似于下面结构的 JSON 对象
{
Result:{
data:[ {username:”Tom”,oldname:”Tom”,age:12”},
{username:”Jack”,oldname:”Jack”,age:16”}
]
}
}
如果是要查询 username 则结果集应该表示为 ”Result.data” ,
第二条记录为搜索的主键,同上面的例子中如果是要查找出符合条件的 username ,则第二个数组应为 ”username”, 如果返回的结果集中还需要返回 oldname 属性,则应该指名数组的第三条记录 ”oldname”, 后面还可以指定更多的需要返回的属性。
因此第二个数组对象参数可以用以下方法表示:
[ 结果对象 , 搜索的主键 , 额外的返回属性 1,… 额外的返回属性 N]
function initAutocomplete(){
var myDataSource1 = new YAHOO.widget.DS_XHR(
"./queryUsername.action",
["data","username"]);
myDataSource1.responseType = YAHOO.widget.DS_XHR.TYPE_JSON;
//myDataSource1.scriptQueryAppend = "output=json&results=100";
var oAutoComp = new YAHOO.widget.AutoComplete("user_username",
"usernameContainer", myDataSource1);
oAutoComp.dataRequestEvent.subscribe(
function(oSelf,sQuery){
myDataSource1.scriptQueryParam = "username";
});
}
XML 方式:
应用方式与 JSON 方式类似,只是将 reponseType 指定为
myDataSource1.responseType = YAHOO.widget.DS_XHR.TYPE_XML
FlatData 方式: