jQuery ajax - 方法 ajax()

jQuery Ajax 参考手册

实例

加载一段文本通过 AJAX：

jQuery Code:

$(document).ready(function(){
  $("#b01").click(function(){
  htmlobj=$.ajax({url:"/jquery/test1.txt",async:false});
  $("#myDiv").html(htmlobj.responseText);
  });
});

HTML Code:

<div id="myDiv"><h2>Let AJAX change this text</h2></div>
<button id="b01" type="button">Change Content</button>

Try It Yourself

Definition and Usage

Ang method na ajax() ay gumagamit ng HTTP request upang ilagay ang malayong data.

Ang method na ito ay ang panghuli ng jQuery AJAX implementation. Ang simple at madaling gamitin na mataas na antas ng implementation ay ang $.get, $.post, at iba pa. Ang $.ajax() ay ibabalik ang XMLHttpRequest object na nilikha nito. Sa karamihan ng kaso, hindi mo kailangang direktang i-operate ang function na ito, maliban kung kailangan mong i-operate ang hindi pangkaraniwang opsyon upang makakuha ng mas maraming kahandugan.

Sa pinakamaliit na kaso, ang $.ajax() ay maaaring gamitin nang walang anumang parameter.

Babala:Lahat ng mga opsyon ay maaring itakda global na sa pamamagitan ng function na $.ajaxSetup().

Syntax

jQuery.ajax([settings]
Parameter Description
settings

Optional. Isang koleksyon ng key-value pair na ginagamit upang kumpigurahin ang Ajax request.

Maaaring itakda ang default na halaga ng anumang opsyon sa pamamagitan ng $.ajaxSetup().

Parameter

options

Uri: Object

Optional. Mga setting ng Ajax request. Lahat ng mga opsyon ay optional.

async

Uri: Boolean

Default na halaga: true. Sa ilalim ng default na setting, lahat ng mga request ay asynchronous. Kapag kailangan ng synchronous request, itakda ang opsyon na ito bilang false.

Babala, ang mga request na synchronous ay magpipigil sa browser, ang ibang operasyon ng user ay dapat maghintay sa pagkumpleto ng request bago maeeksaktuhan.

beforeSend(XHR)

Uri: Function

Maaaring baguhin ang XMLHttpRequest object bago ipagpadala ang request, tulad ng pagdagdag ng custom HTTP header.

Ang XMLHttpRequest object ay ang tanging argumento.

Ito ay isang Ajax kaganapan. Kapag ibabalik ang false, maaaring ipawalang-bisa ang kasalukuyang Ajax request.

cache

Uri: Boolean

Default na halaga: true, kapag dataType ay script at jsonp, ang default ay false. Kapag itinakda ang false, hindi ito mag-cache ang pahina na ito.

Mga bagong tampok ng jQuery 1.2.

complete(XHR, TS)

Uri: Function

Ang callback function na bubuksan pagkatapos makumpleto ang kahilingan (tulad ng pagkatapos ng tagumpay o pagkabigo ng kahilingan).

Parameter: ang XMLHttpRequest object at ang string na naglalarawan ng uri ng kahilingan.

Ito ay isang Ajax kaganapan.

contentType

Uri: String

Default na halaga: "application/x-www-form-urlencoded". Ang uri ng encoding ng kontento na pinapadala sa server.

Ang default na halaga ay angkop sa karamihan ng mga kaso. Kung matukoy mo ang content-type na ililipat sa $.ajax(), ito ay automatsikong ililipat sa server (kahit walang datos na ililipat).

context

Uri: Object

Ang object na ito ay ginagamit upang itakda ang context ng mga callback function na may kaugnayan sa Ajax. Iyong ibig sabihin, na ipakilala ang this sa loob ng callback function na ito (kung hindi ito itinakda, ang this ay ipakilala sa mga opsyon na inilagay sa paggamit ng AJAX request). Halimbawa, kapag itinakda ang isang DOM element bilang parameter ng context, ito ay nagtatakda ng context ng success callback function bilang ang DOM element na ito.

Kagaya nito:

$.ajax({ url: "test.html", context: document.body, success: function(){
        $(this).addClass("done");
      }});
data

Uri: String

Ang datos na ipapadala sa server. Automatikong pagbabagong anyo sa format ng string ng kahilingan. Sa GET kahilingan, ito ay magdagdag sa URL. Tingnan ang opsyon ng processData upang pigilan ang awtomatikong pagbabagong anyo. Dapat ay sa format ng Key/Value. Kung ito ay isang array, ang jQuery ay awtomatikong magbibigay ng parehong pangalan sa bawat halaga. Halimbawa, {foo:["bar1", "bar2"]} ay pagbabagong anyo sa '&foo=bar1&foo=bar2'.

dataFilter

Uri: Function

Ang function na nag-aanila sa mga orihinal na datos ng Ajax. Binibigay ang dalawang argumento: data ay ang orihinal na datos ng Ajax na ibabalik, at type ay ang dataType argumento na ibinigay sa paggamit ng jQuery.ajax. Ang halaga na ibabalik ng function ay papalalagay ng jQuery para sa pagpapatuloy na pagproseso.

dataType

Uri: String

Inaasahan ang uri ng datos na ibabalik ng server. Kung hindi tinukoy, ang jQuery ay awtomatikong hinahalalang maayos ang MIME ng HTTP pakete, tulad ng XML MIME uri ay kinikilala bilang XML. Sa 1.4, ang JSON ay magpapalabas ng isang JavaScript object, at ang script ay papatakbo ang script na ito. Pagkatapos, ang datos na ibabalik ng server ay pagpapatunayin sa halip na ipasa sa callback function. Ang magagamit na halaga:

  • "xml": ibabalik ang dokumento ng XML, na maaaring ipagtrabaho ng jQuery.
  • "html": ibabalik ang walang kumpigurang HTML information; ang script tag na nakabahagi ay magsasagawa kapag naipasok sa DOM.
  • "script": ibabalik ang walang kumpigurang JavaScript code. Hindi na-caching ang resulta, maliban kapag itinakda ang parameter ng 'cache'. Paalam: Kapag gumagawa ng remote request (hindi nasa parehong domain), lahat ng POST request ay magiging GET request (pagkatapos gamitin ang script tag ng DOM sa pag-load).
  • "json": ibabalik ang datos ng JSON.
  • "jsonp": ang format ng JSONP. Kapag ginagamit ang JSONP format na tumatawag sa function, tulad ng "myurl?callback=?", ang jQuery ay magpapalit ng ? ng tamang pangalan ng function upang maisagawa ang callback function.
  • "text": ibabalik ang walang kumpigurang string ng teksto
error

Uri: Function

Ang default na halaga: automatic detection (xml or html). Ginagamit ang function na ito kapag nagkakasalang ang request.

Mayroong tatlong argumento: ang XMLHttpRequest object, mensahe ng error, at (optional) ang na-catch na exception object.

Kung mayroong error, ang mensahe ng error (ikalawang argumento) maliban sa null ay maaaring maging 'timeout', 'error', 'notmodified', at 'parsererror'.

Ito ay isang Ajax kaganapan.

global

Uri: Boolean

Kung magiging trigger ba ang pangkalahatang AJAX event. Ang default na halaga: true. Kapag ito ay naka-set sa false, hindi gagawa ng pangkalahatang AJAX event, tulad ng ajaxStart o ajaxStop, na maaaring gamitin upang kontrolin ang iba't ibang AJAX event.

ifModified

Uri: Boolean

Makakakuha ng bagong datos lamang kapag nagbabago ang datos ng server. Ang default na halaga: false. Ginagamit ang header ng Last-Modified ng HTTP pakete upang hatulan kung ang datos ay hindi nabago. Sa jQuery 1.4, ito ay gustong suriin din ang 'etag' na inilagay ng server upang matiyak na ang datos ay hindi nabago.

jsonp

Uri: String

Sa isang JSONP request, magsulat muli ang pangalan ng callback function. Ginagamit ang halaga na ito upang palitan ang bahagi ng 'callback' sa URL parameter ng GET o POST request na 'callback=?', halimbawa, {jsonp:'onJsonPLoad'} ay magiging 'onJsonPLoad=?' na ililipat sa server.

jsonpCallback

Uri: String

Tukuyin ang pangalan ng callback function para sa kahilingan ng jsonp. Ang halaga na ito ay magpapalit sa random na pangalan na gumawa ng jQuery. Ito ay pangunahing ginagamit upang gumawa ng natatanging pangalan ng function, upang madaling pamahalaan ang kahilingan at madaling magbigay ng callback function at pagtanggap ng error. Maaari rin itong gamitin upang tukuyin ang pangalan ng callback function kapag gusto mong i-cache ang kahilingan ng GET ng browser.

password

Uri: String

Ginamit para sa pangtugon ng password sa kahilingan ng pagkakabit ng HTTP.

processData

Uri: Boolean

Default na halaga: true. Sa kung saan ang data na ipinasa sa pamamagitan ng opsyon ng data, kung ito ay isang object (teknikal na habang hindi ito string), ay naprosesohin upang maging isang query string, upang pagsama-sama sa default na uri ng nilalaman "application/x-www-form-urlencoded". Kung gusto mong ipasa ang impormasyon ng DOM tree o iba pang impormasyon na hindi dapat pagbabago, magtatakda ito sa false.

scriptCharset

Uri: String

Ginagamit lamang kapag ang dataType ng kahilingan ay "jsonp" o "script", at ang type ay "GET" para sa sapilitang pagbabago ng charset. Karaniwang ginagamit lamang kapag ang encoding ng nilalaman ng lokal at malayong lugar ay magkakaiba.

success

Uri: Function

Ang callback function pagkatapos ng kahilingan ay matagumpay.

Parametro: Ang data na ibabalik ng server at naprosesong ayon sa parametro ng dataType; Ang string na naglalarawan ng estado.

Ito ay isang Ajax kaganapan.

traditional

Uri: Boolean

Kung gusto mong gamitin ang tradisyonal na paraan ng pagkakasunod-sunod ng data, magtatakda ito sa true. Maaaring tingnan ang jQuery.param sa kategorya ng kasangkapan.

timeout

Uri: Number

Itatago ang takbo ng panahon ng kahilingan (milisegundo). Ang pagtatakda na ito ay papalitan ang pangkalahatang pagtatakda.

type

Uri: String

Default na halaga: "GET") Ang paraan ng kahilingan ("POST" o "GET") na default ay "GET". Pagtingin: Ang ibang mga paraan ng kahilingan ng HTTP, tulad ng PUT at DELETE, ay maaaring gamitin, ngunit suportado lamang ng bahagyang mga browser.

url

Uri: String

Default na halaga: Ang kasalukuyang pahina na address. Ang address ng paghahalal ng kahilingan.

username

Uri: String

Ginamit para sa pangtugon ng pangngalan ng user sa kahilingan ng pagkakabit ng HTTP.

xhr

Uri: Function

Kailangan ibalik ang isang XMLHttpRequest object. Ang default sa IE ay ActiveXObject habang sa ibang sitwasyon ay XMLHttpRequest. Ginamit para sa muling pagsusulat o magbigay ng isang pinahusay na XMLHttpRequest object. Ang parametro na ito ay hindi magagamit sa jQuery 1.3 bago pa.

Callback Function

Kapag mayroong kailangan na mahawakan ang datos na nakuha ng $.ajax(), kailangan gamitin ang callback function: beforeSend, error, dataFilter, success, complete.

beforeSend

Tumawag bago magpadala ng kahilingan at ibinigay ang XMLHttpRequest bilang argumento.

error

Tumawag kapag may error sa kahilingan. Ibinigay ang XMLHttpRequest object, ang string na naglalarawan ng uri ng error at ang object ng exception (kapag mayroon).

dataFilter

Tumawag pagkatapos ng tagumpay ng kahilingan. Ibinigay ang ibabalik na datos at ang halaga ng parameter na dataType. At dapat ibabalik ang bagong datos (maaaring naprosesado) na ipasa sa callback function na success.

success

Tumawag pagkatapos ng kahilingan. Ibinigay ang ibabalik na datos at ang string na naglalaman ng kahilingang code.

complete

Tumawag sa function na ito pagkatapos makumpleto ang kahilingan, kahit na matagumpay o hindi. Ibinigay ang XMLHttpRequest object at ang string na naglalaman ng kahilingang code o error code.

Uri ng Datos

Ang function na $.ajax() ay umaasa sa impormasyon na ibinibigay ng server upang mahawakan ang ibabalik na datos. Kapag inireport ng server na ang ibabalik na datos ay XML, ang resulta ay magiging magagamit sa mga ordinaryong method ng XML o sa selector ng jQuery para sa paglalathala. Kapag makikita ang iba pang uri, tulad ng HTML, ang datos ay magiging teksto.

Sa pamamagitan ng opsyon na dataType, maaari ring itukoy ang iba't ibang paraan ng pagproseso ng datos. Maliban sa plain XML, maaari ring itukoy ang html, json, jsonp, script o text.

Sa kanila, ang uri na text at xml ay hindi ipapagproseso ang datos. Ang datos lamang ay madaling ipasa sa callback function na success ang responseText o responseHTML na property ng XMLHttpRequest.

Babala:Kailangan naming tiyakin na ang MIME uri na inireport ng web server ay tumutugma sa dataType na pinili namin. Halimbawa, kapag XML, ang server sa server ay dapat ideklara ng text/xml o application/xml upang makakuha ng isang pagkakamit na resulta.

Kung tinukoy na ang uri ay html, ang anumang naka-impluwensyong JavaScript ay magsasauli bago ang HTML ay ibabalik bilang string. Gayundin, kapag tinukoy ang uri ay script, ang JavaScript na ginawa ng server ay magsasauli muna bago ang script ay ibabalik bilang teksto ng datos.

Kung tinukoy bilang uri ng json, ang nakakuha na data ay maging JavaScript object na pinapaliwanag, at ipapakita bilang resulta ang gumagawa na object. Upang mapansin ang layunin na ito, sinubukan muna nito ang paggamit ng JSON.parse(). Kung hindi suportado ng browser, ginagamit ang isang function upang gumawa.

Ang JSON data ay isang estrukturadong data na madaling mapapaliwanag sa pamamagitan ng JavaScript. Kung ang file ng data na inaaksaya ay nasa remote server (kaugnay ang domain, o ang pagkuha ng data sa cross-domain), kailangan gamitin ang uri ng jsonp. Kapag ginagamit ang ganitong uri, ay maglalagay ng string ng query parameter na callback=? sa huli ng URL ng request. Dapat magdagdag ng pangalan ng callback function sa unahan ng JSON data sa server upang makumpleto ang isang epektibong JSONP request. Kung nais baguhin ang pangalan ng parameter ng callback function sa lugar ng default na callback, maaaring itakda ang parameter ng jsonp ng $.ajax().

Babala:Ang JSONP ay isang ekspansyon ng JSON. Ito ay nangangailangan ng ilang code sa server side upang makita at mahawakan ang mga parameter ng string ng query.

Kung tinukoy ang uri ng script o jsonp, kapag natanggap ang data mula sa server, sa katunayan ay ginagamit ang <script> tag sa halip ng XMLHttpRequest object. Sa ganitong sitwasyon, ang $.ajax() ay hindi na nagbibigay ng XMLHttpRequest object, at hindi na ipapasa ang mga event handler, tulad ng beforeSend.

Magpadala ng data sa server

Sa kakaibang kalagayan, ang mga request ng Ajax ay gumagamit ng paraan ng GET. Kung nais gamitin ang paraan ng POST, maaaring itakda ang halaga ng parameter na type. Ang opsyon na ito ay makakaapekto sa kung paano ipapadala ang nilalaman ng opsyon ng data sa server.

Ang opsyon ng data ay maaaring maglalaman ng isang string ng query, tulad ng key1=value1&key2=value2, o isang map, tulad ng {key1: 'value1', key2: 'value2'}. Kung ginamit ang ikalawang paraan, ang data ay maging string ng query sa pagpapadala. Ang prosesong ito ay maaaring maiwasan sa pamamagitan ng pagtatakda ng processData opsyon bilang false. Kung nais nating magpadala ng isang XML object sa server, ang prosesong ito ay maaaring hindi angkop. At sa ganitong sitwasyon, dapat nating baguhin ang halaga ng contentType opsyon gamit ang ibang magkakaugnay na MIME type upang kahalili ng default na application/x-www-form-urlencoded.

Advanced Options

Ang opsyon na global ay ginagamit upang ipagbawal ang pagtatalaga ng callback function na tumutugon sa response, tulad ng .ajaxSend, o ajaxError, at kahit anong kaparehong method. Ito ay napaka-maganda sa ilang mga sitwasyon, tulad ng pagpapadala ng maraming maliit na request nang napakadaling panahon, kung saan maaaring i-disable ang ito sa loob ng ajaxSend.

Kung ang server ay nangangailangan ng HTTP authentication, maaaring gamitin ang username at password upang itakda sa pamamagitan ng username at password opsyon.

Ang request ng Ajax ay may limitasyon ng oras, kaya nangangamit ang error alert sa pagkatapos ng pagkapis sa request at pagproseso nito, upang mapabuti ang karanasan ng user. Ang parameter ng timeout na ito ay palaging binibigyan ng default na halaga, o maaring itakda sa pamamagitan ng jQuery.ajaxSetup, na bihira ang pagpapaanyaya ng timeout opsyon sa espesyal na request.

Sa normal na kaso, ang request ay maaring ihaharap, ngunit ang browser ay maaring kumuha ng datos mula sa kanyang cache. Upang ipagbawal ang paggamit ng resulta ng cache, maaring itakda ang cache parameter bilang false. Kung nais na makita na ang datos ay hindi nagbago mula sa huling request, maaring itakda ang ifModified bilang true.

Ang scriptCharset ay nagbibigay ng kapahintulutan upang itakda ang isang espesyal na charset sa request ng <script> tag, na ginagamit para sa script o jsonp na katulad ng datos. Kung ang charset ng script at ng pahina ay hindi magkapareho, ito ay napaka-maganda.

Ang unang titik ng Ajax ay ang pangunahing titik ng 'asynchronous', na nangangahulugan na ang lahat ng operasyon ay paralel, walang kaugnayang orde ng pagkakumpleto. Ang async parameter ng $.ajax() ay palaging nakatatakang true, na nangangahulugan na pagkatapos ng pagsisimula ng request, ang ibang code ay maaring magsagawa pa rin. Hindi itinuturing na mabuti na itong opsyon ay nilagay sa false, na nangangahulugan na ang lahat ng request ay hindi na asynchronous, na maaring madalas na magdulot ng pagkakatutugan ng browser.

Ang $.ajax function ay nagbibigay ng XMLHTTPRequest object na ginawa nito. Karaniwang nag-aayos lamang ang jQuery ang paggawa ng object na ito, ngunit maaaring ipasa ng user ang sariling ginawa na XMLHTTPRequest object sa pamamagitan ng xhr opsyon. Ang ibig sabihin ng object na ito ay madaling itapon, ngunit binibigyan din ng isang low-level interface upang makita at kontrolin ang request. Halimbawa, ang pagtawag sa .abort() ng object ay maaring ihamon ang request bago ito makumpleto.

jQuery Ajax 参考手册