[Ajax]Microsoft AJAX Library Cheat Sheet

Microsoft AJAX Library Cheat Sheet ——ASP.NET AJAX客户端框架的快速参考系
注：标注有[S]的为静态方法，无须实例化对象即可使用。

1.   Array


[S] Array.add (array, item)

添加一项至Array的结尾。

var a = ['a','b','c','d'];

Array.add(a, 'e');

// a = ['a','b','c','d','e']



[S] Array.addRange (array, items)

将items中的项依次添加到Array的结尾。

var a = ['a', 'b', 'c', 'd', 'e'];

var b = ['f', 'g','h'];

Array.addRange(a, b);

// a = ['a','b','c','d','e','f','g','h']



[S] Array.clear (array)

清除该Array中的所有项。



[S] Array.clone (array)

返回该Array的浅拷贝（Shallow Copy）。

注意：浅拷贝只包含原Array中的项，无论是引用类型还是值类型。但浅拷贝并不会复制被引用的对象，新的Array和原Array中的某个元素引用的是同一个对象的实例。

var a = ['a','b','c','d'];

var b = Array.clone(a);

// b = ['a','b','c','d']



[S] Array.contains (array, item)

判断指定的项是否包含在该Array中。

var a = ['red','green','blue','yellow'];

var b = Array.contains(a, "red");

// b = true



[S] Array.dequeue (array)

从原Array中删除第一项，并返回该项。

var myArray = [],result = "";

Array.add(myArray, 'a');

Array.add(myArray, 'b');

Array.add(myArray, 'c');

Array.add(myArray, 'd');

result = Array.dequeue(myArray);

// myArray = ['b','c', 'd'], result = 'a'



[S] Array.forEach (array, method, context)

依次访问该Array中的每一项，但跳过值为undefined的项。

var a = ['a', 'b', 'c', 'd'];

a[5] = 'e';

var result = '';

function appendToString(arrayElement, index, array) {

    // "this" is the context parameter, i.e. '|'.

    result += arrayElement + this + index + ',';

}

Array.forEach(a, appendToString, '|');

// result = a|0,b|1,c|2,d|3,e|4,



[S] Array.indexOf (array, item, start)

在Array中搜索某一项，并返回其在该Array中的索引。若该Array中不包含该项，则返回-1。

var a = ['red', 'blue', 'green', 'blue'];

var myFirstIndex = Array.indexOf(a, "blue");

var mySecondIndex = Array.indexOf (a, "blue", (myFirstIndex + 1));

// myFirstIndex = 1, mySecondIndex = 3



[S] Array.insert (array, index, item)

在Array中的某一位置插入新项。

var a = ['a', 'b', 'd', 'e'];

Array.insert(a, 2, 'c');

// a = ['a','b','c','d','e']



[S] Array.parse (value)

从字符串表达方式解析出真正的Array对象。

var a = Array.parse ("['red', 'blue', 'green']");

// a[0] = 'red', a[1] = 'blue', a[2] = 'green'



[S] Array.enqueue (array, item)

添加一项至Array的结尾。请同时参考Array.dequeue (array)。



[S] Array.remove(array, item)

从该Array中移除（第一次出现的）该项。

var a = ['a', 'b', 'c', 'd', 'e'];

Array.remove(a, 'c');

// a = ['a','b','d','e']

Array.removeAt(a, 2);

// a = ['a','b','e']



[S] Array.removeAt(array, index)

从该Array中移除指定索引位置上的项。





2.   Boolean
[S] Boolean.parse (value )

从字符串表示的布尔值解析成相应的Boolean类型。value参数必须为“true”或“false”二者之一，不区分大小写，且可以包含空格。

var b = Boolean.parse("true");



3.   Date


Date.format (format)

格式化字符串（区域设定无关）。

var d = new Date();

Sys.Debug.trace (d.format("dddd, dd MMMM yyyy HH:mm:ss"));



Date.localeFormat (format)

格式化字符串（区域设定相关）。使用Sys.CultureInfo.CurrentCulture得到区域属性。

var d = new Date();

Sys.Debug.trace (d.localeFormat("dddd, dd MMMM yyyy HH:mm:ss"));



[S] Date.parseLocale (value, formats)

从字符串表示的本地时间日期解析成相应的Date类型。使用Sys.CultureInfo.CurrentCulture得到区域属性。

Sys.Debug.trace (Date.parseLocale ("4/10/2001", "yyyy-MM-dd",

"MM/dd/yyyy"));

// Date.parseLocale will skip the first format here as invalid and use

// the second one. If it does not find an appropriate format,

// the function throws an exception.



[S] Date.parseInvariant (value, formats)

从字符串表示的区域无关时间日期解析成相应的Date类型。

Sys.Debug.trace (Date.parseInvariant ("4/10/2001", "yyyy-MM-dd",

"MM/dd/yyyy"));

// Date.parseInvariant will skip the first format here as invalid and use

// the second one. If it does not find an appropriate format,

// the function throws an exception.



支持的格式



1.    d： 缩写日期(e.g.: 02/17/2007)：

2.    D： 完整日期(e.g: Saturday, 17 February 2007)

3.    t： 缩写时间(e.g.: 22:10)

4.    T： 完整时间(e.g.: 22:10:30)

5.    F： 完整时间日期(e.g.: Saturday, 17 February 2007 22:10:30)

6.    m (or M)： 月和日(e.g.: February 17)

7.    s： 可排序的时间日期(e.g.: 2007-02-17T22:10:30)

8.    y (or Y)： 年和月(e.g.: 2007 February)



4.   DomElement类


[S] getElementById (id, element)

在element所包含的元素中搜索特定id的元素，若不指定element，则默认为document。

var article = Sys.UI.DomElement.getElementById('article');

var heading = Sys.UI.DomElement.getElementById('heading', article)

// Note: 'article' is an instance of Sys.UI.DomElement

var btn = Sys.UI.DomElement.getElementById('<%= Submit.ClientID %>');

// Note: 'Submit' is an ASP.NET Button server control



[S] $get (id, element)

Sys.UI.DomElement.getElementById的简写形式。

var article = $get('article');

var heading = $get('heading', article)

// Note: 'article' is an instance of Sys.UI.DomElement

var btn = $get('<%= Submit.ClientID %>');

// Note: 'Submit' is an ASP.NET Button server control



[S] addCssClass (element, className)

将指定的CSS Class应用至该元素。

Sys.UI.DomElement.addCssClass($get('heading'), 'highlight');



[S] containsCssClass (element, className)

判断该元素是否应用了指定的CSS Class。

var heading = $get('heading', article)

var isHighlighted = Sys.UI.DomElement.containsCssClass(heading, 'highlight');



[S] removeCssClass (element, className)

从该元素中移除指定的CSS Class。

var heading = $get('heading', article)

Sys.UI.DomElement. removeCssClass (heading, 'highlight');



[S] toggleCssClass (element, className)

若元素已经应用了该CSS Class，则将其移除；否则添加。

var heading = $get('heading', article)

var isHighlighted = Sys.UI.DomElement.toggleCssClass(heading, 'highlight');



[S] getLocation (element)

取得元素相对于浏览器左上角的绝对位置，滚动出页面可见区域之外的距离也计算在内。

var article = $get('article');

var position = Sys.UI.DomElement.getLocation(article);

var x = position.x, y = position.y;



[S] setLocation (element, x, y)

设定元素相对于其定位元素左上角的位置。定位元素是指元素最近的应用了position（非static值）的祖先元素。

var menu = $get('menu');

Sys.UI.DomElement.setLocation(menu, 200, 50);



[S] getBounds (element)

取得元素的绝对位置以及其长宽，返回值对象包括如下几个属性：

1.    x, y：取得元素相对于浏览器左上角的绝对位置，与Sys.UI.DomElement.getLocation()一样。

2.    width：元素的宽度，包括border、padding以及滚动部分。

3.    height：元素的高度，包括border、padding以及滚动部分。

var article = $get('article');

var bounds = Sys.UI.DomElement.getBounds (article);

Sys.Debug.traceDump (bounds, 'Article position and size');

/*

Article position and size {Sys.UI.Bounds}

x: 50

y: 200

height: 268

width: 368

*/

注意到其中宽度和高度均包含border、padding以及滚动部分。所以对于一个300 * 200像素、20像素border、14像素padding的元素来说，其“宽度”和“高度”将为368 * 268像素。

         



5.   DomEvent类


[S] addHandler (element, eventName, handler)
[S] $addHandler (element, eventName, handler)

为DOM元素添加某一事件的处理函数，事件名称应去掉“on”前缀。

注意：在事件处理函数中，this指向的是element，而不一定是发出该事件的元素。

Sys.UI.DomEvent.addHandler (element, "click", clickHandler);

// Same as $addHandler (element, "click", clickHandler);

function clickHandler (e) { … }



[S] addHandlers (element, events, handlerOwner)
[S] $addHandlers (element, events, handlerOwner)

为DOM元素添加多个事件处理函数，events是一个事件处理函数的字典。

注意：在事件处理函数中，若指定了handlerOwner，那么this将指向该handlerOwner，否则将指向element。

$addHandlers ($get ("article"), {

    mouseover: onMouseOver,

    mouseout: onMouseOut

});

function onMouseOver (e) { this.style.backgroundColor = 'yellow'; }

function onMouseOut (e) { this.style.backgroundColor = 'white'; }



[S] clearHandlers (element)
[S] $clearHandlers (element)

移除指定DOM元素所有的事件处理函数。

Sys.UI.DomEvent.clearHandlers (element);

// Same as $ clearHandlers (element);



[S] removeHandler (element, eventName, handler)
[S] $removeHandler (element, eventName, handler)

为DOM元素移除指定的事件处理函数。

Sys.UI.DomEvent.removeHandler (element, "click", clickHandler);

// Same as $removeHandler (element, "click", clickHandler);



preventDefault ()

阻止执行默认的事件处理函数。例如若阻止了a元素的onclick事件，那么将不会引发页面导航。

$addHandler ($get ("showMoreLink"), "click", showMore);

function showMore (e) { e.preventDefault (); }



stopPropagation ()

阻止事件冒泡传递至父元素。



Event对象的属性

1.    altKey：判断触发事件时Alt键是否被按下。

2.    button：得到触发事件的鼠标按键。可选值为Sys.UI.MouseButton枚举（leftButton、middleButton和rightButton）。

3.    charCode：得到触发事件时的键盘按键代码。可以为Sys.UI.Key枚举（backspace, tab, enter,esc, space, pageUp, pageDown, end, home, left, up, right, down, del）。

4.    clientX：鼠标指针相对于文档可见区域的X坐标。

5.    clientY：鼠标指针相对于文档可见区域的Y坐标。

6.    ctrlKey：判断触发事件时Ctrl键是否被按下。

7.    offsetX：鼠标指针相对于触发事件元素左侧边缘的偏移位置。

8.    offsetY：鼠标指针相对于触发事件元素上边缘的偏移位置。

9.    rawEvent：原始的DOM事件。

10.  screenX：鼠标指针相对于浏览者屏幕的X坐标。

11.  screenY：鼠标指针相对于浏览者屏幕的Y坐标。

12.  shiftKey：判断触发事件时Shift键是否被按下。

13.  target：触发事件的对象。

14.  type：事件名称（例如“click”）。



6.   Number
Number.format (format)

用指定的format格式化数字（区域设定无关）。



Number.localeFormat (format)

用指定的format格式化数字（区域设定相关）。



支持的格式

1.    p：将数字转为百分比字符串（e.g.: -1,234.56 %）

2.    d：将数字装化为十进制字符串，没有逗号分隔符（e.g.: -1234.56）

3.    c：将数字转化为货币金额形式（e.g.: (¤1,234.56)）

4.    n：将数字串化为逗号三位分隔（-d,ddd,ddd.ddd…"）形式（e.g.: -1,234.56）



[S] Number.parseLocale (value)

从字符串表示的本地数字解析成相应的Number类型。使用Sys.CultureInfo.CurrentCulture得到当前的区域属性。



[S] Number.parseInvariant (value)

从字符串表示的本地数字解析成相应的浮点数Number类型。value中可以包含逗号分隔符（,）或是正负（+-）号。

var a = new Number();

a = Number.parseInvariant("4");

var b = new Number(2);

var c = Number.parseInvariant("1.53") + a + b;

// c = 7.53



7.   Error
Error相关的方法

1.    [S] Error.argument：根据指定的异常信息和非法的参数创建一个Sys.ArgumentException类型的异常。

2.    [S] Error.argumentNull：根据指定的异常信息和为Null的参数创建一个Sys.ArgumentNullException 类型的异常。

3.    [S] Error.argumentType：根据指定的异常信息、期待参数类型和实际参数类型创建一个Sys.ArgumentTypeException 类型的异常。

4.    [S] Error.argumentUndefined：根据指定的异常信息和为定义的参数创建一个Sys.ArgumentUndefinedException类型的异常。

5.    [S] Error.create：根据指定的异常信息创建一个Error对象。

6.    [S] Error.invalidOperation：根据指定的异常信息和引发该异常的参数创建一个Sys.InvalidOperationException 类型的异常。

7.    [S] Error.notImplemented：根据指定的异常信息创建一个Sys.NotImplementedException类型的异常。

8.    [S] Error.argumentOutOfRange：根据指定的异常信息和引发该异常的参数创建一个Sys.ArgumentOutOfRangeException类型的异常。

9.    [S] Error.parameterCount：根据指定的异常信息创建一个Sys.ParameterCountException 类型的异常。

10.  Error.popstackFrame：将该Error实例的fileName和lineNumber字段更新为该Error被掷出时的位置，而不是该Error被创建时的位置。

// Throw a standard exception type

var err = Error.argumentNull("input", "A parameter was undefined.");

throw err;

// Throw a generic error with a message and associated errorInfo object.

var errorInfoObj = { name: "SomeNamespace.SomeExceptionName",

someErrorID: "436" };

var err = Error.create("A test message", errorInfoObj);

throw err;





8.   String


String.endsWith (suffix)

判断该String是否以指定的后缀结束。

var isTxt = myString.endsWith ("some_file.txt", ".txt");
// isTxt = true


[S] String.format (format, args)

将该String中的各个格式化项用相应的参数值替代。args可以为单一的Object，或是一个包含多个项的Array。

var user = {
    FirstName: 'John',
    LastName : 'Doe',
    DOB: new Date (1975, 1, 17) };
var label = String.format ("User name: {0} {1}, born {2:d}",
    user.FirstName, user.LastName, user.DOB));
// label = "User name: John Doe, born 02/17/1975"


[S] String.localeFormat (format, args)

功能与String.format (format, args)类似，不过格式化时与区域设定相关。



String.startsWith (prefix)

判断该String是否以指定的前缀开始。请参考String.endsWith (suffix)。



String.trim ()

返回一个原String的拷贝，但将原String开头和结尾部分的所有空白字符（例如空格或Tab）都移除。

var myString = "   A string   ";
myString = myString.trim();
// myString = "A string"


String.trimEnd ()

返回一个原String的拷贝，但将原String结尾部分的所有空白字符（例如空格或Tab）都移除。

var myString = "A string   ";
myString = myString.trim();
// myString = "A string"


String.trimStart ()

返回一个原String的拷贝，但将原String开头部分的所有空白字符（例如空格或Tab）都移除。

var myString = "   A string";
myString = myString.trim();
// myString = "A string"




9.   Object


[S] Object.getType (instance)

返回指定对象的类型，请参考Object.getTypeName (instance)。



[S] Object.getTypeName (instance)

返回一个表示对象在运行时的完全限定类型的字符串。

Type.registerNamespace("Samples");
// Define and register a Samples.Rectangle class.
Samples.Rectangle = function(width, height) {
    this._width = width;
    this._height = height;
}
Samples.Rectangle.registerClass("Samples.Rectangle");
var a = new Samples.Rectangle(200, 100);
var name = Object.getTypeName(a);
var type = Object.getType (a);
Sys.Debug.trace ("The type name of object \"a\" is: " + name);
Sys.Debug.traceDump (type);
/* The result is:
    The type name of object "a" is: Samples.Rectangle
    traceDump {Function}
    prototype {Samples.Rectangle}
        __typeName: Samples.Rectangle
        __class: true
*/