jQuery ajax - ajax() 메서드

jQuery Ajax 참조 가이드

예제

AJAX로 텍스트를 로드하다:

jQuery 코드:

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

HTML 코드:

<div id="myDiv"><h2>AJAX로 이 텍스트를 변경하십시오</h2></div>
<button id="b01" type="button">내용 변경</button>

직접 시도해 보세요

정의와 사용법

ajax() 메서드는 HTTP 요청을 통해 원격 데이터를 로드합니다.

이 메서드는 jQuery의 저층 AJAX 구현입니다. 간단하고 사용하기 쉬운 고층 구현은 $.get, $.post 등입니다. $.ajax()는 생성한 XMLHttpRequest 객체를 반환합니다. 대부분의 경우 이 함수를 직접操作할 필요는 없으며, 비일비재한 옵션을 사용하고 더 많은 유연성을 얻으려면 필요할 때만 사용합니다.

가장 간단한 경우, $.ajax()는 매개변수 없이 직접 사용할 수 있습니다.

주의:모든 옵션은 $.ajaxSetup() 함수를 통해 전역으로 설정할 수 있습니다.

문법

jQuery.ajax([settings]
파라미터 설명
settings

선택 사항. Ajax 요청을 구성하는 키밸류 셋합.

모든 옵션의 기본 값을 설정할 수 있는 $.ajaxSetup()를 통해 설정할 수 있습니다.

파라미터

options

타입: Object

선택 사항. AJAX 요청 설정. 모든 옵션은 선택 사항입니다.

async

타입: Boolean

기본 값: true. 기본 설정에서는 모든 요청이 비동기 요청입니다. 동기 요청을 보내기 위해 이 옵션을 false로 설정하세요.

주의하세요, 동기 요청은 브라우저를 락화시킵니다. 사용자의 다른 작업은 요청이 완료되기 전까지 수행할 수 없습니다.

beforeSend(XHR)

타입: Function

XMLHttpRequest 객체의 값을 변경할 수 있는 함수, 예를 들어 사용자 정의 HTTP 헤더를 추가할 수 있는 함수를 요청 전에 수정할 수 있습니다.

XMLHttpRequest 객체는 유일한 매개변수입니다.

이것은 Ajax 이벤트입니다. false를 반환하면 이번 ajax 요청을 취소할 수 있습니다.

cache

타입: Boolean

기본 값: true, dataType가 script과 jsonp인 경우 기본 값이 false입니다. false로 설정하면 이 페이지를 캐시하지 않습니다.

jQuery 1.2의 새로운 기능.

complete(XHR, TS)

타입: Function

요청이 완료되면 호출되는 콜백 함수 (요청 성공이나 실패 후에도 호출됩니다).

매개변수: XMLHttpRequest 객체와 요청 타입을 설명하는 문자열.

이것은 Ajax 이벤트입니다.

contentType

타입: String

기본 값: "application/x-www-form-urlencoded". 서버로 정보를 전송할 때 내용 인코딩 타입입니다.

기본 값은 대부분의 경우에 적합합니다. content-type를 명시적으로 $.ajax()에 전달하면 그것은 서버로 전송됩니다. (데이터가 전송되지 않더라도)

context

타입: Object

이 객체는 Ajax와 관련된 콜백 함수의 컨텍스트를 설정하는 데 사용됩니다. 즉, 콜백 함수 내에서 this를 이 객체로 설정하는 것입니다. 이 参数을 설정하지 않으면 this는 이번 AJAX 요청을 호출할 때 전달된 options 매개변수를 가리킵니다. 예를 들어 DOM 요소를 context 매개변수로 지정하면 success 콜백 함수의 컨텍스트를 이 DOM 요소로 설정합니다.

이렇게 하면:

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

타입: String

서버로 보내는 데이터입니다. 자동으로 요청 문자열 형식으로 변환됩니다. GET 요청에서 URL에 추가됩니다. processData 옵션 설명을 참조하여 이 자동 변환을 차단할 수 있습니다. 반드시 키/밸류 형식이어야 합니다. 배열이면 jQuery가 다른 값에 대해 동일한 이름을 자동으로 할당합니다. 예를 들어 {foo:["bar1", "bar2"]}은 '&foo=bar1&foo=bar2'로 변환됩니다.

dataFilter

타입: Function

Ajax가 반환하는 원시 데이터를 사전 처리하는 함수입니다. data와 type 두 가지 매개변수를 제공합니다: data는 Ajax가 반환하는 원시 데이터이며, type은 jQuery.ajax을 호출할 때 제공하는 dataType 매개변수입니다. 함수가 반환하는 값은 jQuery가 추가로 처리합니다.

dataType

타입: String

서버가 반환할 데이터 타입을 예상합니다. 지정하지 않으면 jQuery가 HTTP 패킷 MIME 정보를 기반으로 자동으로 판단합니다. 예를 들어 XML MIME 타입은 XML로 인식됩니다. 1.4에서 JSON은 자바스크립트 객체를 생성하며 script은 이 스크립트를 실행합니다. 그런 다음 서버 측에서 반환된 데이터는 이 값에 따라 해석되어 콜백 함수로 전달됩니다. 사용 가능한 값:

  • "xml": XML 문서를 반환하며, jQuery에서 처리할 수 있습니다.
  • "html": 원본 텍스트 HTML 정보를 반환합니다. 포함된 script 태그는 DOM에 삽입될 때 실행됩니다.
  • "script": 원본 텍스트 JavaScript 코드를 반환합니다. 결과를 자동으로 캐시하지 않습니다. "cache" 매개변수를 설정하지 않았다면, 결과가 캐시되지 않습니다. 주의: 원격 요청 시(동일한 도메인이 아닌 경우), 모든 POST 요청은 GET 요청으로 변환됩니다.(DOM의 script 태그를 사용하여 로드하기 때문입니다).
  • "json": JSON 데이터를 반환합니다.
  • "jsonp": JSONP 형식. "myurl?callback=?"와 같은 JSONP 형식으로 함수를 호출할 때, jQuery는 ?를 올바른 함수 이름으로 대체하여 콜백 함수를 실행합니다.
  • "text": 원본 텍스트 문자열을 반환합니다
error

타입: Function

기본 값: 자동 판단 (xml 또는 html). 요청 실패 시 이 함수를 호출합니다.

다음 세 가지 매개변수가 있습니다: XMLHttpRequest 객체, 오류 정보, (선택) 포착된 예외 객체.

에러가 발생하면, 오류 정보(두 번째 매개변수)는 null 외에도 "timeout", "error", "notmodified", "parsererror"와 같은 값이 될 수 있습니다.

이것은 Ajax 이벤트입니다.

global

타입: Boolean

전체 AJAX 이벤트를 트리거하거나하지 않습니다. 기본 값: true. false로 설정하면 전체 AJAX 이벤트(ajaxStart 또는 ajaxStop)를 트리거하지 않습니다.

ifModified

타입: Boolean

서버 데이터가 변경될 때만 새 데이터를 가져옵니다. 기본 값: false. HTTP 패킷 Last-Modified 헤더 정보를 사용하여 판단합니다. jQuery 1.4에서는 서버가 지정한 'etag'도 확인하여 데이터가 변경되지 않았는지 확인합니다.

jsonp

타입: String

jsonp 요청에서 콜백 함수 이름을 다시 작성합니다. 이 값은 "callback=?"와 같은 GET 또는 POST 요청의 URL 매개변수에 "callback" 부분을 대체하는 데 사용됩니다. 예를 들어, {jsonp:'onJsonPLoad'}는 "onJsonPLoad=?"를 서버로 전달하게 됩니다.

jsonpCallback

타입: String

jsonp 요청에 콜백 함수 이름을 지정합니다. 이 값은 jQuery가 자동으로 생성한 랜덤 함수 이름을 대체합니다. 이는 jQuery가 독특한 함수 이름을 생성하여 요청 관리를 쉽게 하고, 콜백 함수와 오류 처리를 쉽게 제공하는 데 사용됩니다. GET 요청을 브라우저가 캐시할 때 콜백 함수 이름을 지정할 수도 있습니다.

password

타입: String

HTTP 접근 인증 요청에 응답하는 비밀번호

processData

타입: Boolean

기본 값: true. 기본적으로 data 옵션을 통해 전달된 데이터는 객체(문자열이 아니라는 기술적으로 말하는 것)이면 모두 처리되어 default 내용 유형 "application/x-www-form-urlencoded"과 일치하게 됩니다. DOM 트리 정보나 변환하지 않고자 하는 다른 정보를 전송하려면 false로 설정하세요.

scriptCharset

타입: String

dataType 매개변수가 "jsonp" 또는 "script"이고 type이 "GET"인 경우에만 charset을 강제로 변경됩니다. 일반적으로 로컬과 원격 내용编码이 다를 때 사용됩니다.

success

타입: Function

요청 성공 후의 콜백 함수.

파라미터: 서버에서 반환된 데이터; dataType 매개변수에 따라 처리된 상태 문자열.

이것은 Ajax 이벤트입니다.

traditional

타입: Boolean

데이터를 전통적인 방식으로 시리얼라이즈하려면 true로 설정하세요. jQuery.param 메서드 아래의 도구 분류를 참조하세요.

timeout

타입: Number

요청 초과 시간(밀리초)을 설정합니다. 이 설정은 전체 설정을 대체합니다.

type

타입: String

기본 값: "GET"). 요청 방식 ("POST" 또는 "GET"), 기본적으로 "GET"입니다. 주의: PUT 및 DELETE와 같은 다른 HTTP 요청 방식도 사용할 수 있지만, 일부 브라우저만 지원합니다.

url

타입: String

기본 값: 현재 페이지 주소. 요청을 보낸 주소.

username

타입: String

HTTP 접근 인증 요청에 응답하는 사용자 이름.

xhr

타입: Function

HTTP 요청 객체를 반환해야 합니다. 기본적으로 IE에서는 ActiveXObject이고 다른 경우에는 XMLHttpRequest입니다. XMLHttpRequest을 재정의하거나 강화된 XMLHttpRequest 객체를 제공하는 데 사용됩니다. 이 매개변수는 jQuery 1.3 이전에는 사용할 수 없습니다.

콜백 함수

$.ajax()에서 얻은 데이터를 처리하려면, beforeSend, error, dataFilter, success, complete와 같은 콜백 함수를 사용해야 합니다.

beforeSend

요청을 전송하기 전에 호출되며, XMLHttpRequest을 매개변수로 전달합니다.

error

요청이 실패할 때 호출됩니다. XMLHttpRequest 객체, 오류 유형을 설명하는 문자열, 예외 객체(있을 경우)를 전달합니다.

dataFilter

요청이 성공한 후 호출됩니다. 반환된 데이터와 "dataType" 매개변수의 값을 전달합니다. 그리고 success 콜백 함수에 전달되는 새로운 데이터(가공된 데이터가 될 수 있습니다)를 반드시 반환해야 합니다.

success

요청 후 호출됩니다. 반환된 데이터와 성공 코드를 포함한 문자열을 전달합니다.

complete

요청이 완료된 후 이 함수를 호출합니다. 성공이나 실패에 상관없이 호출됩니다. XMLHttpRequest 객체와 성공이나 오류 코드를 포함한 문자열을 전달합니다.

데이터 타입

$.ajax() 함수는 서버가 제공하는 정보를 기반으로 반환 데이터를 처리합니다. 서버가 반환 데이터가 XML이라고 보고하면, 반환 결과는 일반 XML 메서드나 jQuery 선택자로 탐색할 수 있습니다. 다른 타입, 예를 들어 HTML이 있으면 데이터는 텍스트 형식으로 처리됩니다.

dataType 옵션을 통해 다른 데이터 처리 방식을 지정할 수 있습니다. 단순한 XML 외에도 html, json, jsonp, script 또는 text를 지정할 수 있습니다.

text와 xml 타입으로 반환되는 데이터는 처리되지 않습니다. 데이터는 단순히 XMLHttpRequest의 responseText이나 responseHTML 속성을 success 콜백 함수에 전달합니다.

주의:웹 서버가 보고하는 MIME 타입이 선택한 dataType와 일치해야 합니다. 예를 들어, XML이면 서버는 text/xml이나 application/xml을 선언해야 일관된 결과를 얻을 수 있습니다.

html 타입으로 지정된 경우, 내장된 JavaScript는 HTML이 문자열로 반환되기 전에 실행됩니다. 마찬가지로 script 타입으로 지정된 경우, 서버에서 생성된 JavaScript를 먼저 실행한 후, 스크립트를 텍스트 데이터로 반환합니다.

json 유형으로 지정되면, 받은 데이터를 JavaScript 객체로 파싱하여 결과로 반환합니다. 이를 위해 먼저 JSON.parse()를 사용합니다. 브라우저가 지원하지 않으면 함수를 사용하여 구성합니다.

JSON 데이터는 JavaScript를 통해 쉽게 파싱할 수 있는 구조화된 데이터입니다. 데이터 파일이 원격 서버에 저장되어 있을 때(도메인이 다르므로 크로스 도메인에서 데이터를 가져오는 경우), jsonp 유형을 사용해야 합니다. 이러한 유형을 사용하면 callback=?라는 쿼리 문자열 파라미터를 추가하여 요청 URL 뒤에 추가합니다. 서버 측은 JSON 데이터 앞에回调 함수 이름을 추가하여 유효한 JSONP 요청을 완료하도록 해야 합니다. callback의 파라미터 이름을 기본 callback 대신 설정하려면 $.ajax()의 jsonp 파라미터를 설정할 수 있습니다.

주의:JSONP은 JSON 형식의 확장입니다. 이는 서버 측 코드가 쿼리 문자열 파라미터를 감지하고 처리하도록 요구합니다.

script 또는 jsonp 유형을 지정하면 서버에서 데이터를 수신할 때 <script> 태그가 아니라 XMLHttpRequest 객체를 사용합니다. 이 경우 $.ajax()는 XMLHttpRequest 객체를 반환하지 않으며, beforeSend와 같은 이벤트 처리 함수도 전달되지 않습니다.

서버로 데이터 전송

기본적으로, Ajax 요청은 GET 메서드를 사용합니다. 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 요청은 시간 제한이 있기 때문에, 오류 경고가 캡처되고 처리된 후, 사용자 경험을 향상시킬 수 있습니다. timeout 파라미터는 일반적으로 기본값을 유지하거나 jQuery.ajaxSetup을 통해 전역으로 설정되며, 특정 요청에 대해 timeout 옵션을 다시 설정하는 경우는 드뭅니다.

기본적으로, 요청은 항상 보내집니다. 하지만 브라우저는缓存에서 데이터를 가져올 수 있습니다.缓存의 결과를 사용하지 않도록 하려면 cache 파라미터를 false로 설정할 수 있습니다. 데이터가 마지막 요청 이후 변경되지 않았다면 오류를 보고하려면 ifModified를 true로 설정할 수 있습니다.

scriptCharset는 <script> 태그의 요청에 특정 문자셋을 설정할 수 있게 하며, script나 jsonp과 같은 데이터에 사용됩니다. 스크립트와 페이지 문자셋이 다를 때 특히 유용합니다.

Ajax의 첫 번째 글자는 asynchronous의 첫 번째 글자입니다. 이는 모든 작업이 병行的하다는 것을 의미하며, 완료 순서가 이전이나 후속이 없다는 것입니다. $.ajax()의 async 파라미터는 항상 true로 설정되며, 이는 요청이 시작된 후에도 다른 코드가 실행될 수 있음을 나타냅니다. 이 옵션을 false로 설정하는 것은 강력히 권장하지 않으며, 이는 모든 요청이 동기화되지 않게 되고, 이는 브라우저가 잠기는 원인이 될 수 있습니다.

$.ajax 함수는 생성한 XMLHttpRequest 객체를 반환합니다. 일반적으로 jQuery는 내부에서 처리하고 이 객체를 생성하지만, 사용자는 xhr 옵션을 통해 직접 생성한 xhr 객체를 전달할 수 있습니다. 반환된 객체는 일반적으로 버려지지만, 요청을 관찰하고 제어하기 위한 하위 인터페이스를 제공합니다. 예를 들어, 객체에 .abort()를 호출하면 요청이 완료되기 전에 요청을 일시 중지할 수 있습니다.

jQuery Ajax 참조 가이드