萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery AJAX 入門完整指南:從基礎到實務最佳實踐

核心 AJAX 方法對照

方法用途簡述
$.ajax()最底層、功能最完整所有選項可控,適合複雜場景
$.get()GET 請求簡潔語法,快速查詢
$.post()POST 請求表單提交、資料異動
$.getJSON()GET 並自動解析 JSONREST API 獲取資料
$.getScript()載入並執行 JS 檔案動態載入腳本
.load()載入 HTML 片段插入元素局部頁面更新

一、基礎範例:使用者名稱即時檢查

HTML 頁面

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>jQuery AJAX 使用者名稱檢查</title>
  <style>
    .valid { color: green; }
    .invalid { color: red; }
    .checking { color: orange; }
    #username { padding: 8px; width: 250px; }
    #result { margin-top: 10px; min-height: 24px; }
  </style>
</head>
<body>
  <h3>使用者名稱即時檢查</h3>
  <label>使用者名稱: </label>
  <input type="text" id="username" placeholder="輸入用戶名" autocomplete="off" />
  <div id="result"></div>
  
  <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
  <script src="verify.js"></script>
</body>
</html>

JavaScript (verify.js)

$(function() {
  var $username = $("#username");
  var $result = $("#result");
  var requestTimer = null;
  
  $username.on("input", function() {
    var val = $.trim($(this).val());
    
    // 清除上一次延遲請求
    clearTimeout(requestTimer);
    
    if (!val) {
      $result.removeClass().text("");
      return;
    }
    
    // 顯示檢查中狀態
    $result.removeClass().addClass("checking").text("檢查中...");
    
    // 防抖:300ms 後發送請求
    requestTimer = setTimeout(function() {
      checkUsername(val);
    }, 300);
  });
  
  function checkUsername(username) {
    $.ajax({
      url: "/api/check-username",  // 後端 API
      type: "POST",
      dataType: "json",
      data: { username: username },
      success: function(response) {
        if (response.available) {
          $result.removeClass().addClass("valid").text("✓ 可使用");
        } else {
          $result.removeClass().addClass("invalid").text("✗ " + (response.message || "已被使用"));
        }
      },
      error: function(xhr, status, error) {
        $result.removeClass().addClass("invalid").text("⚠ 檢查失敗:" + error);
      }
    });
  }
});

後端範例 - ASP.NET (WebForms/MVC)

// WebForms Generic Handler (.ashx)
public class CheckUsername : IHttpHandler {
  public void ProcessRequest(HttpContext context) {
    context.Response.ContentType = "application/json";
    var username = context.Request["username"];
    
    bool exists = UserRepository.Exists(username); // 查資料庫
    
    var result = new {
      available = !exists,
      message = exists ? "該使用者名稱已被註冊" : ""
    };
    
    context.Response.Write(Newtonsoft.Json.JsonConvert.SerializeObject(result));
  }
  public bool IsReusable { get { return false; } }
}

// MVC Controller
[HttpPost]
public JsonResult CheckUsername(string username) {
  bool exists = _userService.Exists(username);
  return Json(new { 
    available = !exists, 
    message = exists ? "該使用者名稱已被註冊" : "" 
  });
}

二、$.ajax() 完整選項詳解

$.ajax({
  // 必要
  url: "/api/users",           // 請求地址
  type: "POST",                // HTTP 方法: GET, POST, PUT, DELETE, PATCH
  
  // 資料
  data: { id: 1, name: "test" }, // 物件/字串/陣列,GET 會轉 query string
  dataType: "json",            // 預期回應類型: json, xml, html, text, script, jsonp
  contentType: "application/x-www-form-urlencoded; charset=UTF-8", // 發送類型
  
  // 快取控制
  cache: false,                // GET 時加時間戳防快取
  
  // 非同步 (預設 true,勿改 false)
  async: true,
  
  // 超時 (毫秒)
  timeout: 30000,
  
  // 標頭
  headers: {
    "Authorization": "Bearer " + token,
    "X-CSRF-Token": csrfToken
  },
  
  // 跨域
  xhrFields: { withCredentials: true }, // 攜帶 Cookie
  crossDomain: true,
  
  // 回呼函式
  beforeSend: function(xhr) {
    // 請求前:顯示 loading、設定額外 header
    showLoading();
  },
  success: function(data, textStatus, jqXHR) {
    // 成功:處理資料
    handleData(data);
  },
  error: function(jqXHR, textStatus, errorThrown) {
    // 失敗:網路錯誤、HTTP 錯誤碼、解析失敗
    handleError(jqXHR, textStatus, errorThrown);
  },
  complete: function(jqXHR, textStatus) {
    // 完成 (無論成敗):隱藏 loading
    hideLoading();
  }
});

三、Promise 介面 (jQuery 1.5+)

// 返回 Promise-like 物件 (jqXHR),支援 .done/.fail/.always/.then
var request = $.ajax({ url: "/api/data", dataType: "json" });

request.done(function(data) {
  console.log("成功", data);
}).fail(function(jqXHR, status, error) {
  console.error("失敗", status, error);
}).always(function() {
  console.log("完成 (無論成敗)");
});

// 串聯
$.ajax({ url: "/api/step1" })
  .then(function(data1) {
    return $.ajax({ url: "/api/step2", data: { id: data1.id } });
  })
  .then(function(data2) {
    return $.ajax({ url: "/api/step3", data: { id: data2.id } });
  })
  .done(function(finalData) {
    console.log("流程完成", finalData);
  })
  .fail(function(jqXHR, status, error) {
    console.error("任一步驟失敗", error);
  });

// 並行
$.when(
  $.ajax({ url: "/api/users" }),
  $.ajax({ url: "/api/roles" }),
  $.ajax({ url: "/api/perms" })
).done(function(usersRes, rolesRes, permsRes) {
  // 參數為 [data, status, jqXHR]
  initPage(usersRes[0], rolesRes[0], permsRes[0]);
});

四、現代化:Fetch API + async/await (推薦新專案)

// 封裝通用 fetch
async function apiRequest(url, options = {}) {
  const defaultOptions = {
    headers: {
      "Content-Type": "application/json",
      "X-Requested-With": "XMLHttpRequest"
    },
    credentials: "same-origin" // 攜帶 Cookie
  };
  
  const config = { ...defaultOptions, ...options };
  if (config.data && !(config.data instanceof FormData)) {
    config.body = JSON.stringify(config.data);
    delete config.data;
  }
  
  const response = await fetch(url, config);
  
  if (!response.ok) {
    const error = new Error(`HTTP ${response.status}`);
    error.response = response;
    throw error;
  }
  
  const contentType = response.headers.get("content-type");
  if (contentType && contentType.includes("application/json")) {
    return response.json();
  }
  return response.text();
}

// 使用
async function checkUsername(username) {
  try {
    const result = await apiRequest("/api/check-username", {
      method: "POST",
      data: { username }
    });
    return result.available;
  } catch (error) {
    console.error("檢查失敗", error);
    throw error;
  }
}

五、常見問題與解決

問題原因解決方案
跨域 (CORS) 錯誤瀏覽器同源策略後端設定 Access-Control-Allow-Origin、Credentials、Headers
CSRF 攻擊偽造跨站請求雙重 Cookie 驗證、CSRF Token、SameSite Cookie
重複提交使用者連點按鈕按鈕 loading 狀態禁用、Token 一致性、冪等性設計
中文亂碼編碼不一致統一 UTF-8,Content-Type 指定 charset,URL 參數 encodeURIComponent
大檔案上傳預設限制、超時FormData + 分片上傳、WebUploader、調整伺服器限制
快取問題GET 請求被快取cache: false、URL 加時間戳、後端 Cache-Control: no-cache

六、檔案上傳 (FormData + AJAX)

$("#uploadForm").on("submit", function(e) {
  e.preventDefault();
  
  var formData = new FormData(this); // 自動收集 form 所有欄位含檔案
  // 或手動構建
  // var formData = new FormData();
  // formData.append("file", $("#fileInput")[0].files[0]);
  // formData.append("folder", "images");
  
  $.ajax({
    url: "/api/upload",
    type: "POST",
    data: formData,
    processData: false,  // 關鍵:不要處理資料
    contentType: false,  // 關鍵:不要設 Content-Type (瀏覽器自動設 multipart/form-data)
    xhr: function() {
      var xhr = $.ajaxSettings.xhr();
      // 上傳進度
      xhr.upload.addEventListener("progress", function(e) {
        if (e.lengthComputable) {
          var percent = Math.round((e.loaded / e.total) * 100);
          $("#progressBar").css("width", percent + "%").text(percent + "%");
        }
      }, false);
      return xhr;
    },
    success: function(res) {
      if (res.success) LG.showSuccess("上傳成功");
      else LG.showError(res.message);
    }
  });
});

七、總結

jQuery AJAX 提供簡潔 API 處理非同步請求。基礎專案用 $.get/post,複雜場景用 $.ajax 完整控制。現代專案建議遷移至 **Fetch API + async/await**,獲得原生 Promise 支援、更好的錯誤堆疊、Request/Response 物件操作、Service Worker 相容性。核心概念不變:非同步請求、回呼/處理、錯誤處理、載入狀態管理、安全防護 (CORS/CSRF)。

copyright © 萬盛學電腦網 all rights reserved