jQuery.ajax()

ארגומנטים

מפת זוגות fieldName-fieldValue כדי לקבוע על האובייקט יליד XHR. לדוגמה, אתה יכול להשתמש בו כדי להגדיר withCredentials ל- true עבור בקשות בין דומיינים במידת הצורך.

$.ajax({
   url: a_cross_domain_url,
   xhrFields: {
      withCredentials: true
   }
});

ב- jQuery 1.5, תכונה withCredentials אינה חלה על ילד XHR וכך בקשות CORS דורשות להתעלם מדגל הזה. מסיבה זו, אנו ממליצים להשתמש ב-jQuery 1.5.1+.

יותר פשוט, את פונקציה $.ajax() ניתן להפעיל ללא ארגומנטים:

$.ajax();

שימו לב: הגדרות ברירת מחדל יכולות להיות גלובליות על ידי שימוש בפונקציה $.ajaxSetup().

דוגמה הזו, לא משתמשת באופציות, טעינת תוכן של דף הנוכחי, אבל לא עושה כלום עם תוצאה. כדי להשתמש בתוצאה, אנחנו יכולים להשתמש באחת מהפונקציות של קריאה חוזרת .

אובייקט jqXHR

אובייקט jQuery XMLHttpRequest (jqXHR) מוחזר באמצעות $.ajax() החל מ- jQuery 1.5 הוא הרחבה של אובייקט XMLHttpRequest של הדפדפן. לדוגמה, הוא מכיל תכונות responseText ו- responseXML, כמו גם השיטה getResponseHeader(). כאשר מנגנון העברה הוא משהו אחר מאשר XMLHttpRequest (לדוגמה, תג של תסריט עבור בקשה JSONP) אובייקט jqXHR מדמה פונקציונליות של XHR, במידת האפשר.

החל מ- jQuery 1.5.1, אובייקט jqXHR מכיל שיטה overrideMimeType() (הוא זמין גם ב- jQuery 1.4.x, אבל נמחק זמנית ב-jQuery 1.5). בשיטה .overrideMimeType() ניתן להשתמש בפונקציה של קריאה חוזרת beforeSend(), לדוגמה, עבור שינוי של סוג תוכן של כותרת התשובה:

$.ajax({
  url: 'http://fiddle.jshell.net/favicon.png',
  beforeSend: function( xhr ) {
    xhr.overrideMimeType( 'text/plain; charset=x-user-defined' );
  },
  success: function( data ) {
    if (console && console.log){
      console.log( 'Sample of data:', data.slice(0,100) );
    }
  }
});

אובייקט jqXHR, המוחזר באמצעות $.ajax() מיישם את הממשק Promise, הנותן להם את כל המאפיינים, שיטות והתנהגות Promise (ראו אובייקט נדחה עבור מידע נוסף). לנוחות ועקביות עם שמות של פונקציות קריאה חוזרת, המשומשות ב- $.ajax(),ש jqXHR גם מספק שיטות .error(), .success(), ו- .complete(). שיטות אלה מקבלות ארגומנט של פונקציה, שמופעלת בסיום vבקשה $.ajax(), ופונקציה מקבלת אותם ארגומנטים, בהתאם לשם של פונקציה קריאה חוזרת $.ajax(). ב- jQuery 1.5 זה מאפשר לך להקצות פונקציות קריאה חוזרת מרובות על בקשה אחת, ואף להקצות פונקציות קריאה חוזרת אחרי סיום הבקשה. (אם הבקשה היא הסתיימה, פונקציה של קריאה חוזרת תופעל מייד.)

// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.ajax({ url: "example.php" })
    .success(function() { alert("success"); })
    .error(function() { alert("error"); })
    .complete(function() { alert("complete"); });

// perform other work here ...

// Set another completion function for the request above
jqxhr.complete(function(){ alert("second complete"); });

כדי להבטיח תאימות לאחור עם XMLHttpRequest, אובייקט jqXHR מספק את המאפיינים הבאים ושיטות:

• readyState
• status
• statusText
• responseXML ו/או responseText, כאשר הבקשה הבסיסית התקבלה עם XML ו/או טקסט, בהתאמה
• setRequestHeader(name, value), אשר שונה מפונקציות סטנדרטיות, מחליפה ערך ישן לחדש, במקום איחוד של ערכים ישנים וחדשים
• getAllResponseHeaders()
• getResponseHeader()
• abort()

לא מסופק מנגנון onreadystatechange, עם זאת, success, error, complete ו- statusCode מכסה את כל הדרישות המתקבלות על הדעת.

הערה: jqXHR.success() ו- jqXHR.error() יהיו מיושנות ב-jQuery 1.8 לטובת שימוש ב- jqXHR.done() ו- jqXHR.fail(). זה כדי למנוע בלבול לגבי שמות של פונקציות קריאה חוזרת.

פונקציות של קריאה חוזרת

אופציות beforeSend, error, dataFilter, success ו- complete מקבלות פונקציות של קריאה חוזרת, שמופעלות ברגעים מתאימים:

1. beforeSend מופעלת לפני שבקשה נשלחה, ונשלח אובייקט XMLHttpRequest כפרמטר.
2. error מופעלת עם בקשה לא הצליחה. הוא שולח אובייקט XMLHttpRequest, מחרוזת מציינת סוג של שגיאה, ואובייקט חריגה.
3. dataFilter מופעלת במיקרה הצלחה. הוא מעביר נתונים שהתקבלו וערך dataType, וצריך להחזיר ( ניתן לשנות ) נתונים להבערה ל- success.
4. success מופעלת אם בקשה הסתיימה בהצלחה. הוא מעביר נתונים שהתקבלו, מחרוזת שמכילה קוד מוצלח, ואובייקט XMLHttpRequest.
5. complete מופעלת כשה בקשה הסתיימה, גם אם הצלחה או כישלון. הוא מעביר אובייקט XMLHttpRequest, וגם מחרוזת שמכילה success או קוד שגיאה.

סוגי נתונים

פונקציה $.ajax() מבוססת על שרת, כדי להגיש מידע על נתונים שהתקבלו. אם שרת מקבל נתונים כי XML, תוצאה ניתן לקרוא באמצעות שיטות רגילות של XML או סלקטורים jQuery. אם זוהה סוג אחר, כמו HTML בדוגמה לעיל, נתונים יוגשו כטקסט.

מטופלי נתונים שונים ניתן להשיג באמצעות אופציה dataType. חוץ מ- xml פשוט, dataType יכול להיות html, json, jsonp, script, או text.

סוגים text ו- xml מחזירים נתונים ללא עיבוד. נתונים פשוט מועברים למטפל success, או דרך responseText או תכונה responseHTML של אובייקט XMLHttpRequest, בהתאם.

שימו לב: אנחנו צריכים להיות בטוחים שסוג MIME שדווח על ידי שרת ווב, תואם לבחירה שלנו של dataType. בפרט, XML חייב להיות צוין על ידי שרת כי text/xml או application/xml עבור תוצאות עקביות.

אם html צוין, כל JavaScript מוטבע בתוך מקור נתונים יבוצע לפני ש- HTML יוחזר כמחרוזת. באופן דומה, script יבצע JavaScript שהוחזר משרת, אחרי זה יוחזר סקריפט בעצמו כנתוני טקסט.

סוג json מעבד נתונים של קובץ שהתקבלו כאובייקט JavaScript ומחזיר אובייקט שנוצר כתוצאת נתונים. כדי לעשות זאת, הוא משתמש ב- JSON.parse() כאשר דפדפן תומך בה; אחרת הוא משתמש ב- Function constructor. נתוני JSON שימושים עבור העברת נתונים מובנים בדרך שקצרה ונוחה עבור עיבוד של JavaScript. אם נתונים שהתקבלו קיימים בשרת מרוחק, סוג jsonp ניתן להשתמש במקומו. סוג הזה מפעיל פרמטר של מחרוזת בקשת callback=? שצורף ל- URL; שרת צריך לשים לפני נתונים של JSON שם של הפונקציה קריאה חוזרת עבור בניית בקשה מסוימת של JSONP. אם שם של פרמטר שצוין נדרש במקום callback, הוא יכול להיות צוין עם אופציה jsonp עבור $.ajax().

שימו לב: JSONP זה הרחבה של פורמט JSON, נדרש איזה שהו קוד של שרת כדי לאתר ולטפל בבקשת מחרוזת פרמטר. מידע מלא על זה ניתן למצוא ב- מקור שימוש.

כשה נתונים מתקבלים משרת מרוחק ( שמאפשר להשתמש בסוגי נתונים script או jsonp ), פעולה מתבצעת באמתעות תג " title="תגי HTML"><script> במקום אובייקט XMLHttpRequest. במקרה הזה אף אובייקט XMLHttpRequest לא יוחזר מ- $.ajax(), וגם אף אחד לא ישלח למטפל של פונקציות, למשל beforeSend.

שליחת נתונים לשרת

בברירת מחדל, בקשות Ajax נשלחות באמצעות שיטה GET HTTP. אם שיטה POST דרושה, שיטה הזו ניתן לציין על ידי הגדרת ערך עבור אופציה type. אופציה הזאת משפיעה כיצד תוכן של data ישלח לשרת.

אופציה data יכולה להכיל גם מחרוזת של בקשה של טופס key1=value1&key2=value2, או מפה של טופס {key1: 'value1', key2: 'value2'}. אם אתם משתמשים באחרון, נתונים יהפכו לתוך מחרוזת שאילתה לפני שנשלחו. תהליך הזה ניתן לעקוף באמצעות הגדרה processData ל- false. תהליך יכול להיות לא רצוי אם אנחנו רוצים לשלוח אובייקט XML לשרת; במקרה הזה, אנחנו היינו רוצים לשנות אופציה contentType מ- application/x-www-form-urlencoded לסוג של MIME שמתאים יותר.

אופציות מתקדמות

אופציה global מונעת שימוש ב- .ajaxSend() למטפלים רשומים, .ajaxError(), ושיטות דומות מהפעלה, כשה בקשה הזו מפעילה אותם. זה יכול להיות שימושי, לדוגמה, לעצור טעינת מדד שמיושם עם .ajaxSend() אם שאילתות תכופות וקצרות. ראו תיאור של שיטות האלה מטה ליותר מידע.

אם שרת מבצע זיהוי HTTP לפני הגשת תשובה, זוג, שם של משתמש וסיסמה יכול להישלח דרך האופציות username ו- password.

בקשות Ajax מוגבלות בזמן, לכן שגיאות יכולות להיטפס ולהטפל כדי לתת ניסיון משתמש טוב יותר. שאילתה של פסק זמן, בדרך כלל, או נשארה בברירת מחדל או הוגדרה בתור ערך גלובלי בברירת מחדל באמצעות $.ajaxSetup() במקום לשנות שאילתות מסוימות עם אופציה timeout.

בברירת מחדל, שאילתות תמיד מונפקות, אבל דפדפן יכול להגיש תוצאות ממטמון. כדי לבטל שימוש בתוצאות ממטמון, תגדירו cache ל- false. כדי לקרוא בקשה עם הודעה על כישלון אם נכסים לא השתנו מבקשה אחרונה, תגדירו ifModified ל- true.

scriptCharset מאפשרת לסט של תווים להיות צוין במפורש עבור בקשות, שמשתמשות בתג " title="תגי HTML"><script> ( כלומר סוג של script או jsonp ). זה שימושי אם לסקריפט ולדף ראשי יש סטים תווים שונים.

פירוש של אות ראשונה ב- Ajax היא "אסינכרוני", זה אומר, שפעולות מתבצעות במקביל וסדר של פעולות לא מובטח. אופציה async ב- $.ajax() מוגדרת בברירת מחדל ל- true, מציין שביצוע קוד יכול להמשיך אחרי ששאילתה נעשתה. הגדרת אופציה הזו ל- false ( ולפיכך עושה קריאה לא אסינכרונית יותר ) מאוד לא מומלצת, מכיוון שזה יכול להיות סיבה שדפדפן יפסיק לענות לבקשות.

פונקציה $.ajax() מחזירה אוביייקט XMLHttpRequest, שהיא יצרה. בדרך כלל jQuery מטפל ביצירה אובייקט הזה בתוכו, ופונקציית משתמש עבור יצירת יחידה אחת יכולה להיות מוגדרת באמצעות אופציה xhr. אובייקט שמוחזר באופן כללי ניתן להשליך, אבל זה יספק רמה של הממשק נמוכה יותר עבור התבוננות ומניפולציה של השאילתה. בפרט, קריאה .abort() לאובייקט תעצור בקשה לפני הסיום.

דוגמאות

דוגמה 1

$.ajax({
   type: "GET",
   url: "test.js",
   dataType: "script"
 });

דוגמה 2

$.ajax({
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){
     alert( "Data Saved: " + msg );
   }
 });

דוגמה 3

$.ajax({
  url: "test.html",
  cache: false,
  success: function(html){
    $("#results").append(html);
  }
});

דוגמה 4

var html = $.ajax({
  url: "some.php",
  async: false
 }).responseText;

דוגמה 5

var xmlDocument = [create xml document];
 $.ajax({
   url: "page.php",
   processData: false,
   data: xmlDocument,
   success: handleResponse
 });

דוגמה 6

bodyContent = $.ajax({
      url: "script.php",
      global: false,
      type: "POST",
      data: ({id : this.getAttribute('id')}),
      dataType: "html",
      success: function(msg){
         alert(msg);
      }
   }
).responseText;