# [net]()
XMLHttpRequest模块管理网络请求，与标准HTML中的XMLHttpRequest用途一致，差别在于前者可以进行跨域访问。通过plus.net可获取网络请求管理对象。
### 对象：
- [XMLHttpRequest](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest): 跨域网络请求对象
### 回调方法：
- [XhrStateChangeCallback](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XhrStateChangeCallback): 网络请求状态变化的回调函数
### 权限：
permissions
~~~
"XMLHttpRequest": {
"description": "跨域网络访问"
}
~~~
# [XMLHttpRequest]()
跨域网络请求对象
### 构造：
- [XMLHttpRequest()](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.XMLHttpRequest()): 创建一个XMLHttpRequest 对象，对象创建时不触发任何时间和网络请求，需和open，send方法配合使用。
### 属性：
- [readyState](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.readyState): HTTP 请求的状态
- [response](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.response): 请求从服务器接收到的响应数据
- [responseText](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.responseText): 请求从服务器接收到的响应数据（字符串数据）
- [responseType](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.responseType): 请求响应数据response的类型
- [responseXML](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.responseXML): 请求响应的Document对象
- [status](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.status): 服务器返回的HTTP状态代码
- [statusText](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.statusText): 服务器返回的HTTP状态描述
- [timeout](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.timeout): 请求服务器的超时时间，单位为毫秒（ms）
- [withCredentials](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.withCredentials): 是否支持跨域请求
### 方法：
- [abort](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.abort): 取消当前响应，关闭连接并且结束任何未决的网络活动
- [getAllResponseHeaders](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.getAllResponseHeaders): 获取HTTP响应头部信息
- [getResponseHeader](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.getResponseHeader): 获取指定的HTTP响应头部的值
- [open](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.open): 初始化HTTP请求参数，例如URL和HTTP方法，但是并不发送请求
- [send](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.send): 发送一个HTTP请求
- [setRequestHeader](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.setRequestHeader): 指定一个HTTP请求的Header
### 事件：
- [onreadystatechange](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest.onreadystatechange): 网络请求状态发生变化事件
# [XMLHttpRequest()]()
创建一个XMLHttpRequest 对象，对象创建时不触发任何时间和网络请求，需和open，send方法配合使用。
~~~
var xhr = new plus.net.XMLHttpRequest();
~~~
### 说明：
### 参数：
无
### 返回值：
[XMLHttpRequest](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XMLHttpRequest) :
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8"/>
<script type="text/javascript">
document.addEventListener('plusready', function(){
var xhr = new plus.net.XMLHttpRequest();
xhr.onreadystatechange = function () {
switch ( xhr.readyState ) {
case 0:
alert( "xhr请求已初始化" );
break;
case 1:
alert( "xhr请求已打开" );
break;
case 2:
alert( "xhr请求已发送" );
break;
case 3:
alert( "xhr请求已响应");
break;
case 4:
if ( xhr.status == 200 ) {
alert( "xhr请求成功："+xhr.responseText );
} else {
alert( "xhr请求失败："+xhr.readyState );
}
break;
default :
break;
}
}
xhr.open( "GET", "http://www.baidu.com/" );
xhr.send();
}, false );
</script>
</head>
<body onload="onload();">
</body>
</html>
~~~
# [readyState]()
HTTP 请求的状态
### 说明：
Number 类型
当一个 XMLHttpRequest 初次创建时，这个属性的值从 0 开始，直到接收到完整的 HTTP 响应，这个值增加到 4。 5 个状态中每一个都有一个相关联的非正式的名称，下表列出了状态、名称和含义： 0 Uninitialized，未初始化状态。XMLHttpRequest对象已创建或已被abort()方法重置。 1 Open，open()方法已调用，但是send()方法未调用。请求还没有被发送。 2 Sent，send()方法已调用，HTTP 请求已发送到Web服务器。未接收到响应。 3 Receiving，所有响应头部都已经接收到。响应体开始接收但未完成。 4 Loaded，HTTP响应已经完全接收。
# [response]()
请求从服务器接收到的响应数据
### 说明：
DOMString 类型 只读属性
如果没有从服务器接收到数据，则为null； 否则根据responseType类型决定： 如果responseType设置为空字符串或"text"，则返回空字符串； 如果responseType设置为"document"，则返回Document对象； 如果responseType设置为"json"，则返回JSON对象； 若服务器返回的数据与设置的responseType类型不区配，则返回null。
# [responseText]()
请求从服务器接收到的响应数据（字符串数据）
### 说明：
DOMString 类型
如果还没有接收到数据的话，就是空字符串。 如果 readyState 小于 3，这个属性就是一个空字符串。当 readyState 为 3，这个属性返回目前已经接收的响应部分。如果 readyState 为 4，这个属性保存了完整的响应体。 如果响应包含了为响应体指定字符编码的头部，就使用该编码。否则，假定使用 Unicode UTF-8。
# [responseType]()
请求响应数据response的类型
### 说明：
DOMString 类型
默认值为空字符串，即reponse为DOMString，类型可设置："document"表示Document对象，"json"表示JSON对象，"text"表示字符串。
# [responseXML]()
请求响应的Document对象
### 说明：
DOMString 类型
对请求的响应，解析为 XML 并作为 Document 对象返回。如果请求未成功，或响应的数据无法被解析为XML，则返回null。
# [status]()
服务器返回的HTTP状态代码
### 说明：
Number 类型
由服务器返回的 HTTP 状态代码，如 200 表示成功，而 404 表示 "Not Found" 错误。当 readyState 小于 3 的时候读取这一属性会返回0。
# [statusText]()
服务器返回的HTTP状态描述
### 说明：
DOMString 类型
这个属性用名称而不是数字指定了请求的 HTTP 的状态代码。也就是说，当状态为200的时候它是"OK"，当状态为404的时候它是"Not Found"。和status属性一样，当readyState小于3的时候读取这一属性会返回空。
# [timeout]()
请求服务器的超时时间，单位为毫秒（ms）
### 说明：
Number 类型
超时时间必须在请求发起前设置，否则当前请求将不生效，在当前请求完成后重新发起新请求时生效。其默认值为120秒。
# [withCredentials]()
是否支持跨域请求
### 说明：
Boolean 类型 只读属性
此对象创建的HTTP请求都支持跨域，所以永远返回true。
# [abort]()
取消当前响应，关闭连接并且结束任何未决的网络活动
~~~
void abort();
~~~
### 说明：
这个方法把XMLHttpRequest对象重置为readyState为0的状态，并且取消所有未决的网络活动。 例如，如果请求用了太长时间，而且响应不再必要的时候，可以调用这个方法。
### 参数：
无
### 返回值：
void : 无
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8"/>
<script type="text/javascript">
var xhr=null;
function testXHR(){
if(xhr){
return;
}
xhr=new plus.net.XMLHttpRequest();
xhr.onreadystatechange=xhrStatechange;
xhr.open( "GET", "http://www.baidu.com/" );
xhr.send();
}
function xhrStatechange(){
switch( xhr.readyState ) {
case 0:
console.log( "xhr请求已初始化" );
break;
case 1:
console.log( "xhr请求已打开" );
break;
case 2:
console.log( "xhr请求已发送" );
break;
case 3:
console.log( "xhr请求已响应");
break;
case 4:
if ( xhr.status == 200 ) {
console.log( "xhr请求成功："+xhr.responseText );
} else {
console.log( "xhr请求失败："+xhr.readyState );
}
break;
default :
break;
}
}
function abortXHR(){
if(xhr){
xhr.abort();
xhr=null;
}
}
</script>
</head>
<body>
<button onclick="testXHR()">Test XMLHttpRequest</button><br/>
<button onclick="abortXHR()">Abort XMLHttpRequest</button>
</body>
</html>
~~~
# [getAllResponseHeaders]()
获取HTTP响应头部信息
### 说明：
把HTTP响应头部作为未解析的字符串返回。 如果readyState小于3，这个方法返回null。 否则，它返回服务器发送的所有 HTTP 响应的头部。头部作为单个的字符串返回，一行一个头部。每行用换行符"\r\n"隔开。
### 参数：
无
### 返回值：
DOMString : HTTP 响应头
# [getResponseHeader]()
获取指定的HTTP响应头部的值
~~~
void getResponseHeader( headerName );
~~~
### 说明：
其参数是要返回的 HTTP 响应头部的名称。可以使用任何大小写来制定这个头部名字，和响应头部的比较是不区分大小写的。 该方法的返回值是指定的 HTTP 响应头部的值，如果没有接收到这个头部或者readyState小于3则为空字符串。 如果接收到多个有指定名称的头部，这个头部的值被连接起来并返回，使用逗号和空格分隔开各个头部的值。
### 参数：
- headerName: *( DOMString ) 可选 *HTTP响应头数据名称
### 返回值：
DOMString : HTTP响应头数据值
# [open]()
初始化HTTP请求参数，例如URL和HTTP方法，但是并不发送请求
~~~
void open( method, url, username, password );
~~~
### 说明：
这个方法初始化请求参数以供 send() 方法稍后使用。它把readyState设置为1，删除之前指定的所有请求头部，以及之前接收的所有响应头部，并且把responseText、responseXML、status 以及 statusText 参数设置为它们的默认值。 当readyState为0的时候（当XMLHttpRequest对象刚创建或者abort()方法调用后）以及当readyState为4时（已经接收响应时），调用这个方法是安全的。 当针对任何其他状态调用的时候，open()方法的行为是为指定的。 除了保存供send()方法使用的请求参数，以及重置 XMLHttpRequest 对象以便复用，open()方法没有其他的行为。 要特别注意，当这个方法调用的时候，实现通常不会打开一个到Web服务器的网络连接。
### 参数：
- method: *( DOMString ) 必选 *请求URL的HTTP协议方法
值可以为"GET"、"POST"。
- url: *( DOMString ) 必选 *请求URL地址
- username: *( DOMString ) 可选 *请求URL所需的授权提供认证资格用户名
- password: *( DOMString ) 可选 *请求URL所需的授权提供认证资格密码
### 返回值：
void : 无
### 示例：
~~~
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8"/>
<script type="text/javascript">
var xhr=null;
function testXHR(){
if(xhr){
return;
}
xhr=new plus.net.XMLHttpRequest();
xhr.onreadystatechange=xhrStatechange;
xhr.open( "GET", "http://www.baidu.com/" );
xhr.send();
}
function xhrStatechange(){
switch( xhr.readyState ) {
case 0:
console.log( "xhr请求已初始化" );
break;
case 1:
console.log( "xhr请求已打开" );
break;
case 2:
console.log( "xhr请求已发送" );
break;
case 3:
console.log( "xhr请求已响应");
break;
case 4:
if ( xhr.status == 200 ) {
console.log( "xhr请求成功："+xhr.responseText );
} else {
console.log( "xhr请求失败："+xhr.readyState );
}
break;
default :
break;
}
}
</script>
</head>
<body>
<button onclick="testXHR()">Test XMLHttpRequest</button>
</body>
</html>
~~~
# [send]()
发送一个HTTP请求
~~~
void send( body );
~~~
### 说明：
这个方法导致一个 HTTP 请求发送。如果之前没有调用 open()，或者更具体地说，如果 readyState 不是 1，send() 抛出一个异常。否则，它发送一个 HTTP 请求，该请求由以下几部分组成： 之前调用 open() 时指定的 HTTP 方法、URL 以及认证资格（如果有的话）。 之前调用 setRequestHeader() 时指定的请求头部（如果有的话）。 传递给这个方法的 body 参数。 一旦请求发布了，send() 把 readyState 设置为 2，并触发 onreadystatechange 事件句柄。 如果服务器响应带有一个 HTTP 重定向，send() 方法或后台线程自动遵从重定向。当所有的 HTTP 响应头部已经接收，send() 或后台线程把 readyState 设置为 3 并触发 onreadystatechange 事件句柄。如果响应较长，send() 或后台线程可能在状态 3 中触发 onreadystatechange 事件句柄。最后，当响应完成，send() 或后台线程把 readyState 设置为 4，并最后一次触发事件句柄。
### 参数：
- body: *( DOMString ) 可选 *请求HTTP提交的数据内容
当参数是open方法的method参数为POST时必选
### 返回值：
void : 无
# [setRequestHeader]()
指定一个HTTP请求的Header
~~~
void setRequestHeader( headerName, headerValue );
~~~
### 说明：
这个Http Header应该包含在通过后续send()调用而发起的请求中。这个方法只有当readyState为1的时候才能调用，例如，在调用了open()之后，但在调用send()之前。 如果带有指定名称的头部已经被指定了，这个头部的新值就是：之前指定的值，加上逗号、以及这个调用指定的值（形成一个数组）。 如果Web服务器已经保存了和传递给open()的URL相关联的cookie，适当的Cookie或Cookie2头部也自动地包含到请求中，可以通过调用setRequestHeader()来把这些cookie添加到头部。
### 参数：
- headerName: *( DOMString ) 必选 *HTTP Header名称
- headerValue: *( DOMString ) 必选 *HTTP Header值
### 返回值：
void : 无
### 平台支持：
- Android - 2.2+ (支持): 不支持设置“User-Agent”、“Cookie”的值。
- iOS - 5.1+ (支持): 不支持设置“User-Agent”的值。
# [onreadystatechange]()
网络请求状态发生变化事件
~~~
xhr.onreadystatechange = function(){
// 判断xhr状态
};
~~~
### 说明：
[XhrStateChangeCallback](http://www.dcloud.io/docs/api/zh_cn/xhr.shtml#plus.net.XhrStateChangeCallback) 类型
网络请求状态发生变化时触发，通常在函数中判断对象的state属性值来获取当前请求的状态。
# [XhrStateChangeCallback]()
网络请求状态变化的回调函数
~~~
void onSuccess() {
// State changed code.
}
~~~
### 参数：
无
### 返回值：
void : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS