jQuery ajax - Methode ajax()

Panduan Referensi jQuery Ajax

Contoh

Memuat teks sepotong melalui AJAX:

Kode jQuery:}

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

Kode HTML:

<div id="myDiv"><h2>Biarkan AJAX mengganti teks ini</h2></div>
<button id="b01" type="button">Ganti Konten</button>

Coba sendiri

Definisi dan penggunaan

Metode ajax() mengambil data jarak jauh melalui permintaan HTTP.

Ini adalah implementasi AJAX dasar jQuery. Implementasi tingkat tinggi yang mudah digunakan terdapat di $.get, $.post, dan lainnya. Fungsi $.ajax() mengembalikan objek XMLHttpRequest yang dibuatnya. Dalam sebagian besar kasus, Anda tidak perlu mengoperasikan fungsi ini langsung kecuali Anda memerlukan fleksibilitas yang lebih tinggi untuk opsi yang kurang umum.

Dalam situasi paling sederhana, $.ajax() dapat digunakan tanpa parameter.

Perhatian:Semua opsi dapat disetel secara global melalui fungsi $.ajaxSetup().

Sintaks

jQuery.ajax([settings]
Parameter Deskripsi
settings

Pilihan. Koleksi pasangan kunci nilai yang digunakan untuk mengkonfigurasi permintaan Ajax.

Dapat disetel nilai default untuk setiap opsi melalui $.ajaxSetup().

Parameter

options

Tipe: Object

Pilihan. Pengaturan permintaan AJAX. Semua opsi adalah pilihan.

async

Tipe: Boolean

Nilai default: true. Dengan pengaturan default, semua permintaan adalah permintaan asinkron. Jika ingin mengirim permintaan sinkron, atur opsi ini menjadi false.

Perhatian, permintaan sinkron akan mengunci browser, operasi lain pengguna harus menunggu permintaan selesai sebelum dapat dieksekusi.

beforeSend(XHR)

Tipe: Fungsi

Sebelum mengirim permintaan, fungsi dapat digunakan untuk mengubah objek XMLHttpRequest, seperti menambahkan header HTTP yang disesuaikan.

Objek XMLHttpRequest adalah parameter tunggal.

Ini adalah peristiwa Ajax. Jika mengembalikan false, permintaan ajax ini dapat dibatalkan.

cache

Tipe: Boolean

Nilai default: true, dataType yang diatur untuk script dan jsonp secara default adalah false. Mengatur nilai false akan menonaktifkan pengecapan halaman ini.

Fitur baru jQuery 1.2.

complete(XHR, TS)

Tipe: Fungsi

Fungsi callback yang dipanggil setelah permintaan selesai (di panggil setelah permintaan sukses atau gagal).

Parameter: objek XMLHttpRequest dan string yang mendeskripsikan tipe permintaan.

Ini adalah acara Ajax.

contentType

Tipe: String

Nilai standar: "application/x-www-form-urlencoded". Tipe pengkodean konten saat mengirim informasi ke server.

Nilai standar cocok untuk sebagian besar situasi. Jika Anda secara ekspresi mengirimkan content-type ke $.ajax(), maka itu pasti akan dikirim ke server (bahkan jika tidak ada data yang dikirim).

context

Tipe: Object

Objek ini digunakan untuk menetapkan konteks untuk fungsi callback yang berhubungan dengan Ajax. Artinya, membuat this di dalam fungsi callback menunjuk ke objek ini (jika parameter ini tidak disetting, then this akan menunjuk ke parameter options yang dipasang saat memanggil AJAX request ini). Misalnya, tentukan sebuah elemen DOM sebagai parameter context, lalu menetapkan konteks fungsi callback success untuk elemen DOM ini.

seperti hal ini:

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

Tipe: String

Data yang dikirim ke server. Secara otomatis akan diubah menjadi format string permintaan. Dalam permintaan GET, akan ditambahkan setelah URL. Lihat penjelasan opsi processData untuk melarang konversi otomatis ini. Harus berformat Key/Value. Jika berupa array, jQuery akan otomatis menempatkan nilai yang sama untuk nama yang sama. Misalnya {foo:["bar1", "bar2"]} diubah menjadi '&foo=bar1&foo=bar2'.

dataFilter

Tipe: Fungsi

Fungsi untuk memroses data asli yang dikembalikan oleh Ajax sebelumnya. Menyediakan parameter data dan type: data adalah data asli yang dikembalikan oleh Ajax, dan type adalah parameter dataType yang disediakan saat memanggil jQuery.ajax. Nilai yang dikembalikan oleh fungsi akan diproses lebih lanjut oleh jQuery.

dataType

Tipe: String

Tipe data yang diharapkan untuk data yang kembali dari server. Jika tidak dispecifikasikan, jQuery akan otomatis mengecek secara cerdas informasi MIME HTTP paket untuk menentukan, seperti tipe MIME XML akan diidentifikasi sebagai XML. Pada versi 1.4, JSON akan menghasilkan sebuah objek JavaScript, sedangkan script akan dijalankan. Setelah itu, data yang dikembalikan dari server akan diurai berdasarkan nilai ini dan disampaikan ke fungsi callback. Nilai yang tersedia:

  • "xml": mengembalikan dokumen XML, dapat dihandle dengan jQuery.
  • "html": mengembalikan informasi HTML teks; tag script yang terdapat didalamnya akan dijalankan saat dimasukkan ke DOM.
  • "script": mengembalikan kode JavaScript teks. Tidak akan disimpan dalam cache secara otomatis kecuali parameter "cache" disetel. Perhatian: Saat permintaan jarak jauh (tidak dalam domain yang sama), semua permintaan POST akan diubah menjadi permintaan GET (karena akan digunakan DOM tag script untuk memuat).
  • "json": mengembalikan data JSON.
  • "jsonp": Format JSONP. Saat memanggil fungsi dalam bentuk JSONP, seperti "myurl?callback=?", jQuery akan otomatis mengganti ? dengan nama fungsi yang benar untuk menjalankan fungsi callback.
  • "text": mengembalikan string teks
error

Tipe: Fungsi

Nilai default: pengambilan otomatis (xml atau html). Pemanggilan fungsi ini saat permintaan gagal.

Ada tiga parameter: objek XMLHttpRequest, informasi kesalahan, (opsional) objek eksepsi yang ditangkap.

Jika terjadi kesalahan, informasi kesalahan (parameter kedua) selain null, bisa jadi "timeout", "error", "notmodified", dan "parsererror".

Ini adalah acara Ajax.

global

Tipe: Boolean

Apakah mengaktifkan acara AJAX global. Nilai default: true. Mengatur ke false akan menghentikan acara AJAX global, seperti ajaxStart atau ajaxStop dapat digunakan untuk mengendalikan acara AJAX yang berbeda.

ifModified

Tipe: Boolean

Mengambil data baru hanya saat data server berubah. Nilai default: false. Menggunakan header informasi Last-Modified paket HTTP untuk mengecek. Pada jQuery 1.4, ini juga akan memeriksa 'etag' yang ditentukan server untuk mengecek apakah data belum diubah.

jsonp

Tipe: String

Menulis ulang nama fungsi callback di permintaan jsonp. Nilai ini digunakan untuk menggantikan bagian "callback" di parameter URL dalam permintaan GET atau POST seperti "callback=?", seperti {jsonp:'onJsonPLoad'} akan mengirimkan "onJsonPLoad=?" ke server.

jsonpCallback

Tipe: String

Tentukan nama fungsi kembalikan untuk permintaan jsonp. Nilai ini akan digunakan untuk menggantikan nama fungsi acak yang dihasilkan oleh jQuery. Ini utamanya digunakan untuk membuat nama fungsi unik yang mempermudah pengelolaan permintaan, serta memudahkan penawaran fungsi balik dan penanganan kesalahan. Anda juga dapat menentukan nama fungsi kembalikan ini untuk menghindari peramban mengecache permintaan GET.

password

Tipe: String

Digunakan untuk tanggapan pengakuan akses HTTP sandi.

processData

Tipe: Boolean

Nilai default: true. Dalam halaman saat ini, data yang dikirim melalui opsi data, jika adalah objek (teknisnya bukan string), akan diubah menjadi string query, untuk memadai jenis konten default "application/x-www-form-urlencoded". Jika ingin mengirim informasi DOM pohon atau informasi lain yang tidak diinginkan untuk diubah, atur ke false.

scriptCharset

Tipe: String

Hanya digunakan saat dataType permintaan adalah "jsonp" atau "script", dan type adalah "GET" untuk memaksakan perubahan charset. Biasanya digunakan hanya saat kandungan pengodean lokal dan jarak jauh berbeda.

success

Tipe: Fungsi

Fungsi balik setelah permintaan sukses.

Parameter: Data yang dikembalikan dari server dan diproses berdasarkan parameter dataType; string deskripsi status.

Ini adalah acara Ajax.

traditional

Tipe: Boolean

Jika Anda ingin meng序列化数据的方式，那么就设置为 true. Lihat contoh di bawah kategori alat jQuery.param.

timeout

Tipe: Nomor

Atur waktu tunggu permintaan (dalam milidetik). Pengaturan ini akan menimpa pengaturan global.

type

Tipe: String

Nilai default: "GET"). Cara permintaan ("POST" atau "GET"), default adalah "GET". Perhatian: Metode permintaan HTTP lainnya, seperti PUT dan DELETE, juga dapat digunakan, tetapi hanya beberapa peramban yang mendukung.

url

Tipe: String

Nilai default: Alamat halaman saat ini. Alamat yang dikirim permintaan.

username

Tipe: String

Digunakan untuk tanggapan pengakuan akses HTTP penggunaan nama.

xhr

Tipe: Fungsi

Perlu mengembalikan objek XMLHttpRequest. Default di IE adalah ActiveXObject dan di situasi lain adalah XMLHttpRequest. Digunakan untuk menulis ulang atau menyediakan objek XMLHttpRequest yang ditingkatkan. Parameter ini tidak tersedia di jQuery 1.3 sebelumnya.

Fungsi balik

Untuk mengolah data yang didapatkan dari $.ajax(), Anda harus menggunakan fungsi balik: beforeSend, error, dataFilter, success, complete.

beforeSend

Panggil sebelum mengirim permintaan dan kirim objek XMLHttpRequest sebagai parameter.

error

Panggil saat permintaan gagal. Kirim objek XMLHttpRequest, string yang mendeskripsikan tipe kesalahan, dan objek eksepsi (jika ada).

dataFilter

Panggil setelah permintaan sukses. Kirim data yang dikembalikan dan nilai parameter dataType. Dan harus mengembalikan data baru (bisa disesuaikan) yang akan dikirim ke fungsi balik success.

success

Panggil setelah permintaan selesai. Kirim data yang dikembalikan setelah permintaan dan string yang mengandung kode sukses.

complete

Panggil fungsi ini setelah permintaan selesai, keduanya sukses atau gagal. Kirim objek XMLHttpRequest dan string yang mengandung kode sukses atau kesalahan.

Tipe Data

Fungsi $.ajax() bergantung pada informasi yang disediakan oleh server untuk mengolah data yang dikembalikan. Jika server melaporkan bahwa data yang dikembalikan adalah XML, hasilnya dapat diakses menggunakan metode XML biasa atau pemilih jQuery. Jika terlihat tipe lain, seperti HTML, data akan dianggap sebagai teks.

Dengan pilihan dataType, Anda dapat menentukan cara lain untuk mengolah data. Selain XML saja, Anda dapat menentukan html, json, jsonp, script, atau text.

Diantara mereka, tipe data text dan xml yang dikembalikan tidak akan disesuaikan. Data hanya dengan mudah dijalankan ke fungsi balik success melalui atribut responseText atau responseHTML dari XMLHttpRequest.

Perhatian:Kami harus memastikan bahwa tipe MIME yang dilaporkan oleh server web sama dengan dataType yang dipilih. Misalnya, jika XML, server harus menyatakan text/xml atau application/xml untuk mendapatkan hasil yang konsisten.

Jika disetel ke tipe html, semua JavaScript yang disisipkan akan dijalankan sebelum HTML kembali sebagai string. Secara serupa, jika disetel ke tipe script, JavaScript yang dihasilkan dari server akan dijalankan terlebih dahulu sebelum diubah ke data teks.

Jika ditentukan jenis json, data yang diambil akan diurai sebagai objek JavaScript, dan objek yang dibangun akan dikembalikan sebagai hasil. Untuk mencapai tujuannya, terlebih dahulu akan mencoba menggunakan JSON.parse(). Jika peramban tidak mendukung, maka akan digunakan fungsi untuk membangun.

Data JSON adalah data struktural yang dapat diurai dengan mudah melalui JavaScript. Jika berkas data yang diambil berada di server yang jauh (domain berbeda, yaitu mendapatkan data antar domain), maka perlu menggunakan jenis jsonp. Dengan menggunakan jenis ini, akan dibuat parameter string query callback=? yang ditambahkan di belakang URL permintaan. Server harus menambahkan nama fungsi kembalian di depan data JSON untuk melengkapkan permintaan JSONP yang berlaku. Jika ingin menentukan nama parameter kembalian untuk menggantikan callback default, dapat disetel melalui parameter jsonp dalam $.ajax().

Perhatian:JSONP adalah ekspansi format JSON. Ini memerlukan beberapa kode server untuk mendeteksi dan menangani parameter string query.

Jika ditentukan jenis script atau jsonp, saat menerima data dari server, sebenarnya digunakan tag <script> bukannya objek XMLHttpRequest. Dalam situasi ini, $.ajax() tidak kembali ke objek XMLHttpRequest, dan juga tidak mengirim fungsi penanganan peristiwa, seperti beforeSend.

Mengirim data ke server

Secara default, permintaan Ajax menggunakan metode GET. Jika ingin menggunakan metode POST, dapat menetapkan nilai parameter type. Pilihan ini juga mempengaruhi bagaimana konten opsi data dikirim ke server.

Pilihan data dapat berisi sebuah string query, seperti key1=value1&key2=value2, atau dapat berupa peta, seperti {key1: 'value1', key2: 'value2'}. Jika menggunakan bentuk terakhir, data akan diubah menjadi string query saat dikirim ke pengirim. Proses ini dapat dihindari dengan mengatur opsi processData menjadi false. Jika kami ingin mengirim sebuah objek XML ke server, proses ini mungkin tidak sesuai. Dan dalam situasi ini, kami juga harus mengubah nilai opsi contentType, menggunakan MIME type yang sesuai untuk menggantikan default application/x-www-form-urlencoded.

Opsi tingkat tinggi

Opsi global digunakan untuk mencegah fungsi balikan yang didaftarkan untuk tanggapan, seperti .ajaxSend, atau ajaxError, dan metode yang sama. Ini sangat berguna di beberapa saat, seperti saat permintaan yang dikirim sangat sering dan singkat, dapat menonaktifkan ini di dalam ajaxSend.

Jika server memerlukan autentikasi HTTP, dapat digunakan nama pengguna dan sandi melalui opsi username dan password.

Permintaan Ajax mempunyai batas waktu, jadi setelah kesalahan yang diambil dan diproses, dapat digunakan untuk meningkatkan pengalaman pengguna. Parameter timeout biasanya dijaga di nilai standar, atau diatur secara global melalui jQuery.ajaxSetup, jarang diatur ulang untuk permintaan khusus.

Secara standar, permintaan akan selalu dikirimkan, tetapi peramban mungkin mengambil data dari pustaka penyangga. Untuk melarang penggunaan hasil pustaka, atur parameter cache ke false. Jika ingin melaporkan kesalahan jika data belum berubah sejak permintaan terakhir, atur ifModified ke true.

scriptCharset memungkinkan untuk menetapkan karakter set khusus untuk permintaan <script> tag, untuk script atau data seperti jsonp. Ini sangat berguna ketika script dan karakter set halaman berbeda.

Huruf pertama Ajax adalah awalan dari kata asynchronous, yang berarti semua operasi adalah paralel, tanpa hubungan urutan selesai. Parameter async fungsi $.ajax() selalu diatur ke true, yang menandai bahwa kode lain masih dapat dijalankan setelah permintaan dimulai. Dengan keras disarankan untuk tidak mengatur opsi ini ke false, yang berarti semua permintaan tidak lagi asinkron, hal ini juga dapat menyebabkan peramban terkunci.

Fungsi $.ajax kembalikan objek XMLHttpRequest yang dibuatnya. Biasanya jQuery hanya mengelola dan membuat objek ini secara internal, tetapi pengguna juga dapat mengirimkan objek xhr yang dibuat sendiri melalui opsi xhr. Objek yang kembali biasanya sudah dihapus, tetapi tetap menyediakan antarmuka tingkat bawah untuk mengamati dan mengendalikan permintaan. Misalnya, pemanggilan .abort() pada objek dapat menangguhkan permintaan sebelum selesai.

Panduan Referensi jQuery Ajax