HOWTO · jQuery

jQuery 中的 $.Ajax 資料型別

本教程演示了在 jQuery 中使用 $.ajax 資料型別。

本頁內容

$.ajax 使用 dataType 選項,指定程式碼預期接收的回應類型。回應抵達後,這個選項會影響 jQuery 如何處理它。這與 contentType 不同;後者描述請求主體中所傳送資料的格式。例如,請求可以傳送 JSON,同時預期收到文字回應;請依各自的傳輸方向選擇選項。

$.ajax 中的 dataType 代表什麼

將 dataType 設為 "json" 或 "html" 之類的字串。這個值表示成功處理常式預期使用的回應格式。它不是 MIME 類型:應使用 "json",而不是 "application/json"。如果省略這個選項,jQuery 可能會根據回應的內容類型推斷處理方式。如果應用程式仰賴特定格式,設定預期類型能清楚表明這個意圖。

伺服器仍須傳回符合所指定格式的內容。設定 dataType: "json" 不會把任意回應文字轉成有效的 JSON。同樣地,contentType 不會決定如何剖析回應。

在基本的 $.ajax 請求中設定 dataType

將這個選項放在傳給 $.ajax 的設定物件中。請把範例網址換成應用程式中的端點。這段獨立的 JavaScript 示範設定物件,並印出預期的回應類型;它不會呼叫 $.ajax,也不會傳送網路請求。

執行此範例:

本節中的程式碼以及顯示的標籤或輸出仍為英文。

const request = {
  url: "/api/employees",
  method: "GET",
  dataType: "json"
};
console.log(`${request.method} ${request.url}: expecting ${request.dataType}`);

輸出:

GET /api/employees: expecting json

在載入 jQuery 的應用程式中,將這些設定傳給 $.ajax,然後在 success 或 promise 回呼中處理剖析後的回應。如果請求會傳送主體,請設定 contentType 來描述該主體,並使用 data 提供其值。若 GET 請求沒有主體,除非有明確理由,否則不要加入請求主體的內容類型。

選擇回應類型

請根據應用程式需要處理的回應來選擇值:

  • "xml" 適用於程式碼需要檢查或處理的 XML 文件。
  • "html" 適用於程式碼會當作標記內容使用的 HTML 片段或文件。除非應用程式有安全的處理方式,否則應將傳回的標記視為不可信內容。
  • "script" 適用於預期要當作 JavaScript 執行的回應。只有來源可信且適合執行遠端指令碼時才使用。
  • "json" 適用於程式碼要作為 JavaScript 值使用的結構化資料,例如物件或陣列。
  • "jsonp" 適用於會傳回包裝在回呼中的回應的 JSONP 端點。這是不同的回應機制,不能把任何 JSON 端點都當成跨網域請求的一般解法。
  • "text" 適用於由程式碼自行處理的純文字字串。

選項應符合端點實際傳回的內容。如果回應格式或伺服器行為與預期不同,請檢查回應和請求,而不要隨意更改選項。

各種回應類型的範例

以下每一行都是示意用的 $.ajax 設定物件,並非已執行的請求。端點路徑只是佔位內容;請將各路徑換成會傳回指定格式的網址,並加入應用程式所需的成功處理方式。

  • XML:$.ajax({ url: "/placeholder.xml", method: "GET", dataType: "xml" }) 預期收到 XML 回應,供程式碼檢查或處理。
  • HTML:$.ajax({ url: "/placeholder.html", method: "GET", dataType: "html" }) 預期收到標記內容;請以安全方式處理傳回的 HTML。
  • Script:$.ajax({ url: "/trusted-script.js", method: "GET", dataType: "script" }) 適用於預期要執行的 JavaScript。只有來源可信且適合執行遠端指令碼時才使用。
  • JSON:$.ajax({ url: "/api/employees", method: "GET", dataType: "json" }) 預期收到供成功處理常式使用的結構化資料,例如物件或陣列。
  • JSONP:$.ajax({ url: "/jsonp-capable-endpoint", method: "GET", dataType: "jsonp" }) 需要支援 JSONP 的伺服器,並由伺服器傳回用戶端預期的回呼格式。
  • Text:$.ajax({ url: "/status", method: "GET", dataType: "text" }) 預期收到供程式碼處理或顯示的純文字字串。

這些範例展示如何將各選項搭配合適的端點佔位路徑。它們不表示這些端點確實存在,也不表示曾傳送任何請求。

剖析、快取與跨網域行為

回應剖析、快取行為和跨網域處理方式,可能取決於 jQuery 版本及請求情境。這些範例不保證格式錯誤或空白的 JSON、指令碼快取,或 JSON 與 JSONP 之間的轉換會有特定結果。請查閱應用程式所用版本的文件,並確認端點支援所選的回應類型。

JSONP 不能與一般 JSON 互換:它需要專為傳回回呼包裝回應而設計的端點。跨來源請求也取決於瀏覽器和伺服器的行為;單靠選擇 "json" 並不會授予跨來源存取權。如果請求失敗,請檢查回應主體、回應標頭、瀏覽器主控台和伺服器設定,再與程式碼預期的類型比對。