SimpleAjax 开发包 v3.1 (简单的Ajax)

http://www.mudcms.com  欢迎进入我们的cms技术讨论论坛。 

下载： http://bbs.mudcms.com/showtopic-13.aspx

☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆

SimpleAjax 开发包 v3.1 (简单的Ajax)

MudCMS开发团队   碳元素
http://www.mudcms.com

Ajax技术从此不再神秘...

☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆☆

说明：

表示可以用、需要用或经常要用的属性、事件或方法。

表示不需要用、不建议用或不能用的属性、事件或方法。 因为核心代码是javascript，大家也知道javascript是弱类型的语言，这里所讲的属性、事件和方法只是看起来类似，但并不真正可以完全做到面向对象，比如限制访问，所以此开发包中很多方法只是给程序内部使用的，但用户也能访问。这里做特别说明：说明是不需要用、不建议用或不能用的属性、事件或方法大家就不要用了。

说明：

为了尽可能的避免命名冲突,本开发包中只有一个SimpleAjax是可能会与别人冲突的,其他的类、属性、事件、方法都放在SimpleAjax下面,所以你可以看到RequestItem类全称是SimpleAjax.RequestItem类.

SimpleAjax v3.1版新功能与变动（2007年11月19日）：

1、就是改了一下示例下面那四个test方法。 2、更改了版权，由原来的成长痕迹软件开发团队改成MudCMS开发团队 ^_^。 3、在Readme里为版本加上了更新时间。

以往版本：

SimpleAjax v3.0版（2006年还在读书时编写） 1、使RequestItem有两种类型，一种是受管理的，一种是游离的，使用isManaged方法来判断他是否是受管理的。 2、为SimpleAjax类添加了createRequestItem静态方法，该方法创建的RequestItem对象是游离的，游离的RequestItem用于进行同步请求。 3、为SimpleAjax类添加了getResponse静态方法，该方法把同步请求过程简单化。 SimpleAjax v2.1版（2006年还在读书时编写） 1、支持了Msxml.XMLHTTP、Msxml2.XMLHTTP、Msxml2.XMLHTTP.3.0、Msxml2.XMLHTTP.6.0、Msxml2.XMLHTTP.7.0、Msxml3.XMLHTTP 2、向Opera、Firefox浏览器兼容 3、新增了testAjax()方法，用于测试环境是否支持Ajax SimpleAjax v2.0版（2006年还在读书时编写） 1、支持了 Msxml2.XMLHTTP.5.0 2、新增的ArrayList类代替Scripting.Dictionary做为键值对，以向更多环境兼容 3、受管理的Querystring 4、可以以POST方式发送Form 5、对解决中文问题的部分支持 SimpleAjax v1.0版（2006年还在读书时编写） 最初的版本，主要解决的问题是为每一个请求都指定了一个ID，以方便在全局跟踪。 另外就是引入OOP来简化Ajax的开发流程，其中有三个事件说明了这一点。

参考：

SimpleAjax类(Ajax管理类，生成和管理请求项) SimpleAjax.RequestItem类(请求项) SimpleAjax.RequestItem.Response类(响应管理类) ArrayList类 (键值对，用于代替Scripting.Dictionary对象) 附：XMLHttpRequest对象(Ajax核心)

SimpleAjax类

方法

public SimpleAjax(name)

return	SimpleAjax	返回SimpleAjax对象
name	string	引用的名字.比如:var aa = SimpleAjax("aa");很无聊的一个参数吧~没办法~这是必须的~内部机制需要

构造函数.不建议使用该构造函数,因为一个页面中有一个这样的对象就行了,我已经在js文件中构造了一个simpleAjax(被称之为固有对象)了,直接使用就行了.

public SimpleAjax.RequestItem createRequestItem()

return

SimpleAjax.RequestItem

返回SimpleAjax.RequestItem对象

创建一个请求项.新创建的请求项会被存放到SimpleAjax对象中.在这之后,还会触发SimpleAjax的onCreate事件.如果创建失败会返回false。
该方法创建的RequestItem是受管理的。可以进行同步和异步请求(同步的我没试过行不行，理论上是可以的)。

public SimpleAjax.RequestItem getRequestItem(key)

return	SimpleAjax.RequestItem	返回SimpleAjax.RequestItem对象
key	string	预得到的RequestItem的key

根据传入的key,得到存放在SimpleAjax中的请求项.

public void removeRequestItem(key)

return	void	无返回值
key	string	预移除的Requestitem的key

根据传入的key,移除存放在SimpleAjax中的请求项.在这之后,还会触发SimpleAjax的onDispose事件

public int getRequestItemsLength()

return

int

返回整数

返回SimpleAjax中存放请求项的个数,如果只求个数,比getRequestItems()方法生成数组后再求得个数要快.

public Array getRequestItemKeys()

return

Array

返回数组对象

返回的数组中包括所有请求项的Key，你可以遍历该数组来访问所有的Key。
注意,请不要修改此返回的数组

public string getRequestItemKeys(index)

return	string	返回字符串表示的Key
index	int	索引

根据传入的索引，返回对应的Key

public Array getRequestItemValues()

return

Array

返回数组对象

返回的数组中包括所有的请求项，你可以遍历该数组来访问所有的请求项。

public string getRequestItemValues(index)

return	string	返回字符串表示的Key
index	int	索引

根据传入的索引，返回对应的请求项。

public static boolean testAjax()

return

boolean

是否支持Ajax

测试是否支持Ajax

private static XMLHttpRequest createRequest()

return

XMLHttpRequest

返回XMLHttpRequest对象

产生一个新的XMLHttpRequest对象.主要是做多种浏览器兼容处理.如果创建失败会返回false

private static string newId()

return

string

返回字符串

产生一个新的ID.这个ID几乎是没有重复出现的可能的,用此方法生成的ID用来设置请求项的key.

public static boolean testStream()

return

boolean

返回true表示stream可用,false不可用

测试ActiveXObject("adodb.stream")是否可用

public static string bytesToBstr(body,cset)

return	string	返回字符串
body	binary	一般用XMLHttpRequest对象的responseBody属性传入
cset	string	指定编码,如:gbk,bg2312,utf8等...

使用该方法需要stream组件支持,所以最好先用testStream方法测试一下.该方法用于解决中文问题,你可以指定任意的输出编码.但由于需stream组件的支持,所以还是不建议使用.

public static SimpleAjax.RequestItem createRequestItem()

return

SimpleAjax.RequestItem

返回SimpleAjax.RequestItem对象

创建一个请求项.创建失败会返回false。
该方法创建的RequestItem是游离的。只能进行同步请求，这也是他存在的意义(同步的方式比起异步的方式要简单和易理解得多，当然代价就是失去异步优势，需要合理权衡)。

public static SimpleAjax.RequestItem. Response getResponse(url)

return	SimpleAjax.RequestItem.Response	返回SimpleAjax.RequestItem. Response对象
url	string	指定的URL

创建一个游离的请求项，以同步的方式请求指定的URL。并返回请求的结果Response对象。该方法把同步请求过程简单化。

属性

private string name	SimpleAjax的name.应该要与SimpleAjax对象的引用名字是一样的.比如固有对象simpleAjax的name属性应该是"simpleAjax".
private ArrayList _requestItems	一个集合,其实SimpleAjax所有的请求项都存在这个集合中.请不要直接操作这个对象,否则能导致的后果太多了.

事件

public event onCreate(ri)

ri

SimpleAjax.RequestItem

被创建的RequestItem

发生在RequestItem创建时

private event _onDone(ri)

ri

SimpleAjax.RequestItem

得到响应的RequestItem

发生在onDone之前.主要是过滤XMLHttpRequest.readyState!=4的情况

public event onDone(ri)

ri

SimpleAjax.RequestItem

得到响应的RequestItem

发生在RequestItem的请求得到响应后

public event onDispose(key)

key

string

被释放内存的RequestItem的key

发生在RequestItem释放内存后

SimpleAjax.RequestItem类 (请求项)

方法

public SimpleAjax.RequestItem()

return

SimpleAjax.RequestItem

返回SimpleAjax.RequestItem对象

构造函数.请勿使用该构造函数,要构造该对象可以使用SimpleAjax的createRequestItem()方法

public boolean isManaged()

return

boolean

返回是否为受管理的

RequestItem有两种类型，一种是受管理的，一种是游离的，使用isManaged方法来判断他是否是受管理的。

public SimpleAjax getSimpleAjax()

return

SimpleAjax

返回SimpleAjax对象

得到该RequestItem所在的SimpleAjax对象

public void setUrl(url[,buildupArray][,list1][,list2]...)

return	void	无
url	string	要设置的url
buildupArray	string	是否构成数组，可选值： BUILDUP          在出现重复键时，没有明确指定不构成数组的键将构成数组，默认值 NOTBUILDUP 在出现重复键时，没有明确指定构成数组的键将不构成数组(即使原来的值是数组)，后出现的值将覆盖前面的值 AUTO                在出现重复键时，原来的值为数组的将构成数组，原来的值为空或为字符串的将不构成数组
list1,list2...	string	明确指定的键列表

你可以给url属性赋值,但url问号后面的参数不会被管理也不会被发送到服务端.使用此方法给url属性赋值,url问号后面的参数会被管理也会被发送到服务端

public string getUrl([type])

return	string	返回的url
type	string	返回url的类型，可选值： ONLY          仅页面url，即没有问号后面的参数，默认值 ALL             全部url，即包括问号后面的参数 ORIGINAL 原始url，即返回你在给url属性赋值时给的值，或在调用setUrl时给的url参数

你可以取url属性的值,但取到的值等价于getUrl("ORIGINAL").使用该方法取url,你可以得到一个仅页面的url,或是得到从受管理Querystring中提取出参数的完整url

public void send()

return

void

无返回值

发送该请求项.只有调用此方法发送请求项,才有可能收到响应.在收到响应时,会触发SimpleAjax的_onDone事件和onDone事件

public static void setUrl_buildupArray(list ,key ,newValue [,buildupArray])

return	void	无返回值
list	ArrayList	一个受管理的Querystring
key	string	键名
newValue	string	要放入的值
buildupArray	string	放入方式，即是否构成数组，可选值： BUILDUP          在出现重复键时，构成数组，默认值 NOTBUILDUP 即使出现重复键，也不构成数组(即使原来的值是数组)，后出现的值将覆盖前面的值 AUTO                在出现重复键时，原来的值为数组的将构成数组，原来的值为空或为字符串的将不构成数组

把{newValue}值放入到{list}中key为{key}的键值对中。buildupArray决定了放入方式，这里的放入方式与setUrl方法中的放入方式有一点出入，这里没有明确指定构成或不构成的名单
setUrl方法里调用了该方法

public static string getQuerystringString(querystring)

return	string	返回受管理Querystring组成的字符串
querystring	ArrayList	一个受管理的Querystring

传入受管理的Querystring，返回可以向服务器发送的URL问号后面的字符串
send方法和getUrl方法调用了该方法

public static string getFormString(form)

return	string	返回表单组成的字符串
form	Form	一个Form表单

传入一个表单，返回可以向服务器发送的URL问号后面的字符串
send方法调用了该方法

属性

public string key	该请求项的Key
private string name	请求项所属的SimpleAjax的name.要得到所属的SimpleAjax,可以使用getSimpleAjax()方法,用不着此属性了.
private XMLHttpRequest request	XMLHttpRequest对象,Ajax的核心. 不建议直接调用里面的方法或属性
public SimpleAjax.RequestItem.Response response	响应管理对象.你可以使用response==null来判断是否有响应返回(不过这一般是没有必要的,因为在onDone事件里就一定不等于null) 该属性用于管理响应,现在要取得响应字符串,你可以使用ri.response.getText()方法,而不建议使用ri.request.responseText属性了. 请参考SimpleAjax.RquestItem.Response类
publilc ArrayList querystring	受管理Querystring.这是一个很迷人的功能,所有的querystring都被管理起来了,你不用再去使用该死的+号来连接这些参数.现在你只需要在集合里添加一个成员,就等于添加了一人参数 例:ri.querystring.set("action","add"); ri.querystring.set("id","5"); 等价于原来的 url+="?" + "action" + "=" + "add" + "&" ; url+= "id" + "=" + "5"; 显然受管理的Querystring看起来健壮多了,在调用send方法时,send方法会取出受管理Querystring中的键值对组成请求字符串再发送请求
public Form form	表单.在调用send方法时,如果form不为null则会以POST方式发送请求,并且会把该表单提交到服务端
public ArrayList args	(注:该集合与querystring几乎一样,不同的是querystring会提交到服务器,而该集合不会) 参数集合,可以在该集合里放入多个参数,这是一个主要的扩展功能. 因为你在一个页面中可能需要N个请求,而XMLHttpRequest对象在得到响应后,到了响应函数中你应该是没有办法分辨是哪个XMLHttpRequest对象的响应(除非你不同的请求调不同的函数,或在被请求页面中做工作,以便借助返回信息来分辨是哪个XMLHttpRequest对象). 而现在你可以在响应函数(在这里被我称之为"事件")中接到一个参数(这要多谢key属性,才能让我把这个往服务器跑了一圈的家伙认出来,并抓来当做参数传入),这个参数就是存放着XMLHttpRequest对象的RequestItem对象,你可以从该对象的args集合属性中取任意一个之前你安排成员来分辨他们了. 例:ri.args.set("cmd","getOrderDetails"); 那么 ri.args.get("cmd")=="getOrderDetails";
public string url	要请求的url
public boolean async	是否异步,默认为true
public string user	如果请求的资源需要验证身份,user属性指定用户名
public string password	如果请求的资源需要验证身份,password属性指定密码

SimpleAjax.RequestItem.Response类 (响应类，用于管理响应)

方法

public SimpleAjax.RequestItem.Response(ri)

return	SimpleAjax.RequestItem.Response	返回响应对象
ri	SimpleAjax.RequestItem	指定属于哪个请求的响应

构造函数.不建议使用,有响应返回时,_onDemo事件会调用此构造函数构建一个响应对象

public string getText()

return

string

响应的字符串

得到响应的字符串

public string getTextFromStream(cset)

return	string	响应的字符串
cset	string	指定编码,如:gbk,bg2312,utf8等...

按指定编码输出响应字符串,但由于需要stream组件的支持,不建议使用

public DOM getXML()

return

DOM

XML文档对象

得到XML文档对象

public binary getBody()

return

binary

二进制数据

得到二进制数据

public stream getStream()

return

stream

流

得到流

属性

private RequestItem requestItem
private XMLHttpRequest request
public int status	http状态码
public string statusText	http状态的文本形式
public string headersString	http头全部内容的文本形式
public ArrayList headers	受管理的http头,你可以遍历所有的http头或仅读出一个头的内容,请参考ArrayList类

ArrayList类 (键值对，用于代替Scripting.Dictionary对象)

方法

public ArrayList()

return

ArrayList

返回ArrayList对象

构造函数.

public Object get(key)

return	Object	值/对象
key	string	键

根据传入的key，得到对应的值/对象

public void set(key,value)

return	void	无
key	string	键
value	Object	值/对象

根据传入的key，设置对应的值/对象

public void remove(key)

return	void	无
key	string	键

根据传入的key，移除对应的值/对象

public void crear()

return

void

无

清空集合

public boolean exists(key)

return	boolean	true表示存在，false表示不存在
key	string	预检检测是否存在的键

根据传入的key，检测对应的值/对象是否存在于集合中。注意，如果值/对象不存在集合中，使用get方法会返回null，但存在于集合中也有可能存在返回null(因为值正好是null)，这时可以使用该方法判断值/对象是否存在于集合中。

public Array keys()

return

Array

包函key的数组

返回一个数组，数组中包函所有key

public Object keys(index)

return	string	键
index	int	索引

根据传入的索引，返回对应的键

public Array values()

return

void

包函value的数组

返回一个数组，数组中包函所有值/对象

public Object values(index)

return	Object	值/对象
index	int	索引

根据传入的索引，返回对应的值/对象

public ArrayList clone()

return

ArrayList

克隆的ArrayList

克隆一个同样的ArrayList

属性

public int length

集合中的成员总数

附：XMLHttpRequest对象参考

方法

abort()

return

void

无返回值

停止当前请求

getAllResponseHeaders()

return

string

作为字符串返回完整的header

作为字符串返回完整的header

getResponseHeader(headerLabel)

return	string	作为字符串返回单个的header
headerLabel	string	指定header的标签

根据传入的headerLabel找到指定的header,作为字符串返回

open(method,url [,asyncFlag] [,userName] [,password])

return	void	无返回值
method	string	设置请求的方式,三个可选值: HEAD、POST、GET
url	string	设置要请求的url
asyncFlag	boolean	可选,默认为true.是否异步连接.此处为Ajax的关键.
userName	string	可选,设置访问目标url所使用的用户对应的用户名
password	string	可选,设置访问目标url所使用的用户对应的密码

设置未决的请求的目标URL,方法和其它参数

send(content)

return	void	无返回值
content	object	发送的内容

发送请求

setRequestHeader(label,value)

return	void	无返回值
label	string	指定header的标签
value	string	为header指定值

设置header并和请求一起发送

属性

onreadystatechange	状态改变的事件触发器
readyState	对象状态:0="未初使化"、1="读取中"、2="已读取"、3="交互中"、4="完成".
responseText	服务器返回数据的文本版本
responseXML	服务器返回数据的XML版本.此属性为兼容DOM的XML文档对象.
responseBody	以unsigned array格式表示直接从服务器返回的未经解码的二进制数据
responseStream	以Ado Stream对象的形式返回响应信息
status	服务器返回的状态码,如:404="文件未找到"、200="成功"
statusText	服务器返回的状态文本

.