jQuery ajax - ajax() yöntemi

jQuery Ajax Kılavuzu

Örnek

AJAX ile bir metin yükler:

jQuery kodu：

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

HTML kodu：

<div id="myDiv"><h2>AJAX ile bu metni değiştir</h2></div>
<button id="b01" type="button">İçeriği Değiştir</button>

Kişisel olarak deneyin

Tanım ve Kullanım

ajax() yöntemi HTTP istekleri aracılığıyla uzaktan verileri yükler.

Bu yöntem jQuery'nin alt düzey AJAX implementasyonudur. Daha kolay kullanılabilir yüksek düzey implementasyonlar $.get, $.post vb. görüntülenir。$.ajax() oluşturduğunu döner XMLHttpRequest nesnesi. Çoğu durumda bu fonksiyonu doğrudan işlemek gerekmez, yalnızca daha fazla esneklik elde etmek için nadir seçenekleri işlemek gerekirse.

En basit durumda，$.ajax() herhangi bir parametre olmadan doğrudan kullanılabilir.

Dikkat:Tüm seçenekler $.ajaxSetup() fonksiyonu ile genel olarak ayarlanabilir.

Sözdizimi

jQuery.ajax([settings]
Parametreler Açıklama
settings

Opsiyonel. Ajax isteklerini yapılandırmak için kullanılan anahtar değer kümesi.

Herhangi bir seçeneğin varsayılan değerini $.ajaxSetup() ile ayarlayabilirsiniz.

Parametreler

options

Tür: Object

Opsiyonel. AJAX istek ayarları. Tüm seçenekler opsiyoneldir.

async

Tür: Boolean

Varsayılan değer: true. Varsayılan ayarlar altında, tüm istekler asenkron olarak gönderilir. Eğer同步请求需要，则将此选项设置为 false。

Dikkat,同步请求将锁定浏览器，用户的其他操作必须等待请求完成才能执行。

beforeSend(XHR)

Tür: Fonksiyon

İstek göndermeden önce XMLHttpRequest nesnesini değiştirebileceğiniz fonksiyonlar, örneğin özelleştirilmiş HTTP başlıkları eklemek için.

XMLHttpRequest nesnesi tek parametredir.

Bu bir Ajax olayıdır. false dönerse bu ajax isteklerini iptal edebilirsiniz.

cache

Tür: Boolean

Varsayılan değer: true, dataType script ve jsonp olunca varsayılan olarak false. false olarak ayarlanırsa bu sayfa önbelleklemez.

jQuery 1.2 yeni özellikleri.

complete(XHR, TS)

Tür: Fonksiyon

İstek tamamlandıktan sonra geri çağrı fonksiyonu (istek başarılı veya başarısız olduktan sonra çağrılır).

Parametreler: XMLHttpRequest nesnesi ve istek türünü tanımlayan bir string.

Bu bir Ajax olayıdır.

contentType

Tür: String

Varsayılan Değer: "application/x-www-form-urlencoded". Sunucuya gönderilen bilgilerin içerik kodlama türü.

Bu değer çoğu durum için uygundur. Eğer $.ajax()'a açıkça bir content-type ile iletilirse, bu mutlaka sunucuya gönderilir (veri gönderilmeyecek olsa bile).

context

Tür: Object

Bu nesne, Ajax ile ilgili geri çağrı fonksiyonlarının bağlamını ayarlamak için kullanılır. Yani, geri çağrı fonksiyonları içinde this'in bu nesneye işaret etmesini sağlar (bu parametre belirtilmezse, this, bu AJAX istemini çağıran options parametresine işaret eder). Örneğin, bir DOM elementi context parametresi olarak belirlenirse, bu durumda success geri çağrı fonksiyonunun bağlamı bu DOM elementi olur.

Böyle:

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

Tür: String

Sunucuya gönderilen veriler. Otomatik olarak istek dizgi formatına dönüştürülür. GET isteklerinde URL'nin sonuna eklenir. processData seçeneklerini inceleyerek bu otomatik dönüştürmeyi engelleyebilirsiniz. Anahtar/Değer formatında olmalıdır. Diziyse, jQuery aynı anahtara farklı değerler için otomatik olarak aynı adı kullanır. Örneğin {foo:["bar1", "bar2"]} '&foo=bar1&foo=bar2' olarak dönüştürülür.

dataFilter

Tür: Fonksiyon

Ajax geri döndürebilen temel verileri ön işleyen fonksiyon. İki parametre sunar: data, Ajax geri döndürebilen temel veridir, type ise jQuery.ajax çağrısında sağlanan dataType parametresidir. Fonksiyonun döndürdüğü değer jQuery tarafından daha fazla işlenecektir.

dataType

Tür: String

Beklenen sunucu geri döndürebileceği veri türü. Belirtilmezse, jQuery otomatik olarak HTTP paket MIME bilgilerine göre akıllıca tahmin eder, örneğin XML MIME türü XML olarak tanımlanır. 1.4'te, JSON bir JavaScript nesnesi oluştururken, script ise bu betiği çalıştırır. Sonra sunucu tarafından geri döndürülen veriler bu değere göre çözümlendikten sonra, geri çağrı fonksiyonuna iletilir. Kullanılabilir değerler:

  • "xml": XML belgesi döndürür, jQuery ile işlenebilir.
  • "html": Temiz metin HTML bilgisi döndürür; içeren script etiketleri dom'a eklendiğinde çalışır.
  • "script": Temiz metin JavaScript kodu döndürür. Sonuç otomatik olarak önbelleklemez. "cache" parametresi ayarlanmadıkça. Uyarı: Uzak istekler sırasında (aynı domain'de değilse), tüm POST istekleri GET isteklerine dönüştürülür. (DOM script etiketi kullanılarak yüklenmesi nedeniyle)
  • "json": JSON verileri döndürür.
  • "jsonp": JSONP biçimi. "myurl?callback=?" gibi JSONP biçiminde fonksiyon çağrıldığında, jQuery ?, doğru fonksiyon adını değiştirerek geri çağrı fonksiyonunu çalıştırır.
  • "text": Temiz metin dizesi döndürür
error

Tür: Fonksiyon

Varsayılan değer: otomatik karar verme (xml veya html). İstek başarısız olduğunda bu fonksiyon çağrılır.

Üç parametre vardır: XMLHttpRequest nesnesi, hata bilgisi, (isteğe bağlı) yakalanan istisna nesnesi.

Hata meydana geldiğinde, hata bilgisi (ikinci parametre) null dışında "timeout", "error", "notmodified" ve "parsererror" olabilir.

Bu bir Ajax olayıdır.

global

Tür: Boolean

Küresel AJAX olaylarını tetikler mi. Varsayılan değer: true. False olarak ayarlandığında, küresel AJAX olayları tetiklenmez, örneğin ajaxStart veya ajaxStop farklı Ajax olaylarını kontrol etmek için kullanılabilir.

ifModified

Tür: Boolean

Yalnızca sunucu verileri değiştiğinde yeni verileri almak. Varsayılan değer: false. HTTP paketinin Last-Modified başlık bilgisi kullanılarak otomatik olarak karar verilir. jQuery 1.4'te, aynı zamanda sunucunun belirlediği 'etag' kontrol edilerek verilerin değişmediği belirlenir.

jsonp

Tür: String

Bir jsonp istekte geri çağrı fonksiyonunun adını yeniden yazın. Bu değer, "callback=?" türü GET veya POST isteklerinde URL parametrelerindeki "callback" kısmını değiştirmek için kullanılır, örneğin {jsonp:'onJsonPLoad'} "onJsonPLoad=?" sunucuya iletilmesini sağlar.

jsonpCallback

Tür: String

jsonp istekleri için bir geri çağrı fonksiyon adı belirleyin. Bu değer, jQuery tarafından otomatik olarak oluşturulan rastgele fonksiyon adının yerine kullanılır. Bu, jQuery'nin benzersiz fonksiyon adları oluşturmasını sağlar, böylece isteklerin yönetimi daha kolay olur ve geri çağrı fonksiyonları ve hata işleme kolayca sağlanabilir. GET isteklerini tarayıcı tarafından önbelleğe alınmak istiyorsanız, bu geri çağrı fonksiyon adını belirleyin.

password

Tür: String

HTTP erişim kimlik doğrulama isteğine yanıt veren şifre.

processData

Tür: Boolean

Varsayılan değer: true. Varsayılan olarak, data seçeneği ile gelen veriler, bir nesne (teknik olarak bir string değilse) ise, "application/x-www-form-urlencoded" varsayılan içerik türü ile uyumlu olacak şekilde bir sorgu dizgisi olarak dönüştürülür. DOM ağacı bilgisi veya dönüştürülmesini istemediğiniz diğer bilgileri göndermek istiyorsanız, false olarak ayarlayın.

scriptCharset

Tür: String

İstekte dataType "jsonp" veya "script" olup type "GET" olduğunda charset'i zorla değiştirmek için kullanılır. Genellikle yerel ve uzak içerik kodlamaları farklıysa kullanılır.

success

Tür: Fonksiyon

İstek başarılı olduğunda çağrılan geri dönüş fonksiyonu.

Parametreler: dataType parametresine göre işlenmiş ve sunucudan dönen veriler; durum açıklaması string'i.

Bu bir Ajax olayıdır.

traditional

Tür: Boolean

Verileri geleneksel bir şekilde sıralamak istiyorsanız, true olarak ayarlayın. jQuery.param yöntemine işaret eden araç kategorisinde bakın.

timeout

Tür: Number

İstek zaman aşımını (milisaniye olarak) ayarlayın. Bu ayar, genel ayarı geçersiz kılar.

type

Tür: String

Varsayılan değer: "GET")). İstek yöntemi ("POST" veya "GET"), varsayılan olarak "GET"tir. Dikkat: PUT ve DELETE gibi diğer HTTP istek yöntemleri de kullanılabilir, ancak sadece bazı tarayıcılar destekler.

url

Tür: String

Varsayılan değer: mevcut sayfa adresi. İstek gönderilen adres.

username

Tür: String

HTTP erişim kimlik doğrulama isteğine yanıt veren kullanıcı adı.

xhr

Tür: Fonksiyon

Bir XMLHttpRequest nesnesi döndürülmesi gerekiyor. IE altında varsayılan olarak ActiveXObject, diğer durumlar için ise XMLHttpRequest'dir. XMLHttpRequest nesnesini yeniden yazmak veya bir geliştirilmiş XMLHttpRequest nesnesi sağlamak için kullanılır. Bu parametre jQuery 1.3 öncesinde kullanılamaz.

Geri çağrı fonksiyonları

Eğer $.ajax() tarafından alınan verileri işlemek istiyorsanız, beforeSend, error, dataFilter, success, complete gibi geri çağrı fonksiyonlarını kullanmanız gerekir.

beforeSend

İstek göndermeden önce çağrılır ve bir XMLHttpRequest olarak parametre olarak girilir.

error

İstek hata olduğunda çağrılır. XMLHttpRequest nesnesi, hata türünü açıklayan bir dizi ve bir hata nesnesi (varsa) girilir.

dataFilter

İstek başarılı olduğunda çağrılır. Geri dönen veri ve "dataType" parametresinin değeri girilir. ve success geri çağrı fonksiyonuna yeni veri (muhtemelen işlenmiş) geçirilmelidir.

success

İstekten sonra çağrılır. Geri dönen veri ve başarılı kod içeren bir dizi giren.

complete

İstek tamamlanır sonra bu fonksiyon çağrılır, ne başarılı ne de başarısız olsun. XMLHttpRequest nesnesi ve bir başarılı veya hata kodu içeren bir dizi giren.

Veri türü

$.ajax() fonksiyonu, sunucu tarafından sağlanan bilgilere dayanarak dönen verileri işler. Sunucu, dönen verilerin XML olduğunu bildirirse, sonuçlar normal XML yöntemleri veya jQuery seçicileri ile taranabilir. Diğer türler, örneğin HTML varsa, veri metin olarak ele alınır.

dataType seçeneği, diğer farklı veri işleme yöntemlerini de belirlemek için kullanılabilir. Sadece XML değil, aynı zamanda html, json, jsonp, script veya text de belirtilebilir.

Text ve xml türünde dönen veriler işlenmez. Veri sadece XMLHttpRequest'in responseText veya responseHTML özellikleri, success geri çağrı fonksiyonuna basitçe geçirilir.

Dikkat:Web sunucusunun bildirdiği MIME türünün seçtiğimiz dataType ile uyumlu olduğundan emin olmamız gerekir. Örneğin, XML ise, tutarlı sonuçlar elde etmek için sunucu tarafından text/xml veya application/xml beyan edilmesi gerekir.

Eğer html türü belirlenirse, içe gömülen herhangi bir JavaScript HTML bir dizi olarak döndürülmeden önce çalıştırılır. Benzer şekilde, script türü belirlenirse, sunucu tarafından oluşturulan JavaScript önce çalıştırılır ve ardından metin verisi olarak döndürülür.

json türü belirlenirse, alınan veriler bir JavaScript nesnesi olarak解析 edilir ve oluşturulan nesne sonuç olarak döndürülür. Bu amacı gerçekleştirmek için önce JSON.parse() kullanılır. Eğer tarayıcı bu işlevi desteklemiyorsa, bir fonksiyon kullanılarak yapılandırılır.

JSON verileri, JavaScript tarafından kolayca解析 edilebilen yapılandırılmış verilerdir. Eğer veri dosyası uzak sunucuda saklanıyorsa (alan adı farklı, yani veri çapraz alanı), jsonp türü kullanılmalıdır. Bu türde, bir sorgu dizgisi parametresi callback=? oluşturulur ve bu parametre, istek URL'sinin sonuna eklenir. Sunucu tarafı, geçerli bir JSONP isteği oluşturmak için JSON verilerine önceden belirtilen geri çağrı fonksiyon adını eklemelidir. Geri çağrı fonksiyon adının parametre adını varsayılan callback yerine değiştirmek için $.ajax() jsonp parametresini ayarlayabilirsiniz.

Dikkat:JSONP, JSON formatının bir genişletimidir. Sunucu tarafında bazı kodlar, sorgu dizgisi parametrelerini tespit ve işlemek zorundadır.

script veya jsonp türü belirlenirse, sunucudan gelen veri <script> etiketi yerine XMLHttpRequest nesnesi kullanılarak alınır. Bu durumda $.ajax() bir XMLHttpRequest nesnesi dönmeyebilir ve beforeSend gibi olay işleyicilerini de geçirmeyebilir.

Veri sunucuya gönderme

Varsayılan olarak, Ajax istekleri GET yöntemini kullanır. POST yöntemini kullanmak istiyorsanız, type parametresinin değerini belirleyebilirsiniz. Bu seçenek data seçeneğindeki içeriğin nasıl sunucuya gönderileceğini de etkiler.

data seçeneği hem bir sorgu dizgisini içerebilir, örneğin key1=value1&key2=value2, hem de bir harita olabilir, örneğin {key1: 'value1', key2: 'value2'}. Eğer ikinci formu kullanırsanız, veri gönderici tarafından sorgu dizgisi olarak dönüştürülür. Bu işlemi de processData seçeneğini false olarak ayarlayarak önleyebilirsiniz. XML nesnesi göndermek istediğimizde, bu işlem uygun olmayabilir. Ayrıca bu durumda contentType seçeneğinin değerini de değiştirmeliyiz, varsayılan application/x-www-form-urlencoded MIME türünü yerine uygun bir MIME türü ile değiştirmeliyiz.

Gelişmiş Seçenekler

Global seçenek, .ajaxSend veya ajaxError gibi yanıt kaydedilen geri çağrı fonksiyonlarını engellemek için kullanılır. Bu, gönderilen istekler çok sık ve kısa olduğunda, ajaxSend içinde bu özelliği devre dışı bırakmak gibi bazı durumlarda faydalı olabilir.

Sunucu HTTP kimlik doğrulaması gerekiyorsa, username ve password seçenekleri aracılığıyla kullanıcı adı ve parola ayarlanabilir.

Ajax istekleri zamanlıdır, bu yüzden hata uyarıları yakalanıp işlendikten sonra, kullanıcı deneyimini artırmak için kullanılabilir. Genellikle timeout parametresi varsayılan değerini korur veya jQuery.ajaxSetup ile genel olarak ayarlanır, belirli istekler için timeout seçeneğini yeniden ayarlama nadir bir durumdur.

Varsayılan olarak, istek her zaman gönderilir, ancak tarayıcı, veritabanından veri çekebilir. Kullanıcı aracılığıyla kullanılan sonuçları kullanmayı engellemek için cache parametresini false olarak ayarlayabilirsiniz. Eğer verilerin son istekten bu yana değişmediğini belirlemek ve bu durumda hata bildirmek istiyorsanız, ifModified parametresini true olarak ayarlayabilirsiniz.

scriptCharset, <script> etiketinin isteklerine belirli bir karakter seti ayarlamayı sağlar, bu da script veya jsonp benzeri veriler için kullanılır. Script ve sayfa karakter setleri farklıysa, bu özellik özellikle faydalıdır.

Ajax'ın ilk harfi asynchronous'un baş harfi, bu da tüm işlemlerin paralel olduğunu ve tamamlanma sırasının önemsiz olduğunu anlamına gelir. $.ajax()'nın async parametresi her zaman true olarak ayarlanır, bu da istek başladıktan sonra diğer kodun hala çalışabileceğini belirtir. Bu seçeneği false olarak ayarlamanın, tüm isteklerin artık asenkron olmadığını ve bunun tarayıcıyı dondurabileceğini belirten kesin bir tavsiye edilmez.

$.ajax fonksiyonu, oluşturduğu XMLHttpRequest nesnesini döner. Genellikle jQuery, bu nesneyi içsel olarak işler ve oluşturur, ancak kullanıcı da xhr seçenekleri aracılığıyla kendi oluşturduğu xhr nesnesini iletebilir. Dönen nesne genellikle atılır, ancak hala temel bir arayüz sağlanarak istek gözlemlenmesi ve kontrolü yapılır. Örneğin, .abort() çağrısı, istek tamamlanmadan önce istekten çekilebilir.

jQuery Ajax Kılavuzu