1. 소개
이 섹션은 비권장입니다.
XMLHttpRequest
객체는 리소스 가져오기를 위한 API입니다.
XMLHttpRequest
라는 이름은 역사적인 것으로, 이 기능과 관련이 없습니다.
네트워크를 통해 가져온 XML 문서의 데이터를 처리하는 간단한 코드 예제:
function processData( data) {
// 데이터를 처리합니다.
}
function handler() {
if ( this . status == 200 &&
this . responseXML != null &&
this . responseXML. getElementById( 'test' ). textContent) {
// 성공!
processData( this . responseXML. getElementById( 'test' ). textContent);
} else {
// 문제가 발생했습니다.
…
}
}
var client = new XMLHttpRequest();
client. onload = handler;
client. open( "GET" , "unicorn.xml" );
client. send();
서버에 메시지를 로그로 남기고 싶다면:
function log( message) {
var client = new XMLHttpRequest();
client. open( "POST" , "/log" );
client. setRequestHeader( "Content-Type" , "text/plain;charset=UTF-8" );
client. send( message);
}
또는 서버 문서의 상태를 확인하고 싶다면:
function fetchStatus( address) {
var client = new XMLHttpRequest();
client. onload = function () {
// 네트워크 오류가 있는 경우 신뢰할 수 없는 결과를 반환할 수 있습니다.
returnStatus( this . status);
}
client. open( "HEAD" , address);
client. send();
}
1.1. 명세 히스토리
XMLHttpRequest
객체는 초기에는 WHATWG의 HTML 작업의 일환으로 정의되었습니다. (수년 전 Microsoft의 구현을 기반으로 함.)
2006년에 W3C로 이동했습니다. XMLHttpRequest
의 확장(예: 진행 이벤트 및 교차 출처 요청)은 별도의 초안(XMLHttpRequest Level 2)으로 2011년 말까지 개발되었으며,
그 후 두 초안이 병합되어 표준 관점에서 XMLHttpRequest
는 다시 하나의 엔터티가 되었습니다. 2012년 말에는 WHATWG로 다시 이동했습니다.
현재 초안으로 이어진 논의는 다음 메일링 리스트 아카이브에서 찾을 수 있습니다:
2. 용어
이 명세는 Infra 표준에 의존합니다. [INFRA]
이 명세는 DOM, DOM Parsing and Serialization, Encoding, Fetch, File API, HTML, URL, Web IDL, XML의 용어를 사용합니다.
[DOM] [DOM-PARSING] [ENCODING] [FETCH] [FILEAPI] [HTML] [URL] [WEBIDL] [XML] [XML-NAMES]
3. 인터페이스 XMLHttpRequest
[Exposed =(Window ,DedicatedWorker ,SharedWorker )]interface :XMLHttpRequestEventTarget EventTarget { // event handlersattribute EventHandler onloadstart ;attribute EventHandler onprogress ;attribute EventHandler onabort ;attribute EventHandler onerror ;attribute EventHandler onload ;attribute EventHandler ontimeout ;attribute EventHandler onloadend ; }; [Exposed =(Window ,DedicatedWorker ,SharedWorker )]interface :XMLHttpRequestUpload XMLHttpRequestEventTarget { };enum {XMLHttpRequestResponseType ,"" ,"arraybuffer" ,"blob" ,"document" ,"json" }; ["text" Exposed =(Window ,DedicatedWorker ,SharedWorker )]interface :XMLHttpRequest XMLHttpRequestEventTarget {constructor (); // event handlerattribute EventHandler onreadystatechange ; // statesconst unsigned short UNSENT = 0;const unsigned short OPENED = 1;const unsigned short HEADERS_RECEIVED = 2;const unsigned short LOADING = 3;const unsigned short DONE = 4;readonly attribute unsigned short readyState ; // requestundefined open (ByteString ,method USVString );url undefined open (ByteString ,method USVString ,url boolean ,async optional USVString ?=username null ,optional USVString ?=password null );undefined setRequestHeader (ByteString ,name ByteString );value attribute unsigned long timeout ;attribute boolean withCredentials ; [SameObject ]readonly attribute XMLHttpRequestUpload upload ;undefined send (optional (Document or XMLHttpRequestBodyInit )?=body null );undefined abort (); // responsereadonly attribute USVString responseURL ;readonly attribute unsigned short status ;readonly attribute ByteString statusText ;ByteString ?getResponseHeader (ByteString );name ByteString getAllResponseHeaders ();undefined overrideMimeType (DOMString );mime attribute XMLHttpRequestResponseType responseType ;readonly attribute any response ;readonly attribute USVString responseText ; [Exposed =Window ]readonly attribute Document ?responseXML ; };
XMLHttpRequest
객체는 다음과 연관됩니다:
- 업로드 객체
XMLHttpRequestUpload객체.- 상태
- unsent, opened, headers received, loading, done 중 하나; 초기값은 unsent.
send()호출됨- 불리언이며, 초기값은 false.
- 타임아웃
- 부호 없는 정수이며, 초기값은 0.
- 교차 출처 자격 증명
- 불리언이며, 초기값은 false.
- 요청 메서드
- 메서드.
- 요청 URL
- URL.
- 작성자 요청 헤더
- 헤더 리스트이며, 초기값은 비어 있음.
- 요청 본문
- 초기값은 null.
- 동기
- 불리언이며, 초기값은 false.
- 업로드 완료
- 불리언이며, 초기값은 false.
- 업로드 리스너
- 불리언이며, 초기값은 false.
- 타임아웃됨
- 불리언이며, 초기값은 false.
- 응답
- 응답이며, 초기값은 네트워크 오류.
- 수신된 바이트
- 바이트 시퀀스이며, 초기값은 빈 바이트 시퀀스.
- 응답 타입
- 빈 문자열, "
arraybuffer", "blob", "document", "json", "text" 중 하나; 초기값은 빈 문자열. - 응답 객체
- 객체, 실패, 또는 null이며, 초기값은 null.
- fetch 컨트롤러
- fetch 컨트롤러이며, 초기값은 새 fetch
컨트롤러.
send()메서드는 이를 유용한 fetch 컨트롤러로 설정하지만, 단순화를 위해 항상 fetch 컨트롤러를 보유한다. - 재정의 MIME 타입
- MIME
타입 또는 null이며, 초기값은 null.
overrideMimeType()이 호출되면 값을 얻을 수 있다.
3.1. 생성자
client = new XMLHttpRequest()- 새로운
XMLHttpRequest객체를 반환합니다.
new XMLHttpRequest()
생성자 단계는 다음과 같습니다:
3.2. 가비지 컬렉션
XMLHttpRequest
객체는 그
상태가
send()
호출됨이 true인 opened,
headers received, 또는 loading 중 하나이고, 다음 중 하나의 type을 가진
이벤트 리스너가
하나 이상 등록되어 있으면, 가비지 컬렉션되어서는 안 된다:
readystatechange,
progress,
abort,
error,
load,
timeout,
그리고
loadend.
XMLHttpRequest
객체가 연결이 여전히 열려 있는 동안 가비지 컬렉션되면, 사용자 에이전트는 종료해야 합니다. 해당 XMLHttpRequest
객체의
페치 컨트롤러를.
3.3. 이벤트 핸들러
다음은
이벤트 핸들러(및 해당
이벤트 핸들러 이벤트 타입)
로, XMLHttpRequestEventTarget
인터페이스를 상속한 객체에서 속성으로 지원해야 합니다:
| 이벤트 핸들러 | 이벤트 핸들러 이벤트 타입 |
|---|---|
onloadstart
| loadstart
|
onprogress
| progress
|
onabort
| abort
|
onerror
| error
|
onload
| load
|
ontimeout
| timeout
|
onloadend
| loadend
|
다음은
이벤트 핸들러
(및 해당
이벤트 핸들러 이벤트 타입)로,
XMLHttpRequest
객체에서만 속성으로 지원되어야 합니다:
| 이벤트 핸들러 | 이벤트 핸들러 이벤트 타입 |
|---|---|
onreadystatechange
| readystatechange
|
3.4. 상태
client . readyState-
client의 상태를 반환합니다.
readyState getter 단계는 아래 표에서 첫 번째 열의 값이 this의 상태인 행에서 두 번째 열의 값을 반환하는 것입니다:
| unsent | UNSENT (숫자 값 0)
| 객체가 생성되었습니다. |
| opened | OPENED (숫자 값 1)
| open() 메서드가 성공적으로 호출되었습니다. 이 상태에서는 요청
헤더를 setRequestHeader() 메서드를
사용하여 설정할 수 있으며,
send() 메서드를 사용하여 페치를 시작할 수 있습니다.
|
| headers received | HEADERS_RECEIVED
(숫자 값 2)
| 모든 리디렉션(있는 경우)이 따라졌으며 응답의 모든 헤더가 수신되었습니다. |
| loading | LOADING (숫자 값 3)
| 응답 본문이 수신되고 있습니다. |
| done | DONE (숫자 값 4)
| 데이터 전송이 완료되었거나 전송 중에 문제가 발생했습니다(e.g., 무한 리디렉션). |
3.5. 요청
하나 이상의 이벤트 리스너를
XMLHttpRequestUpload
객체에 등록하면 CORS 프리플라이트 요청이 발생한다. (이는
이벤트 리스너를 등록하면 업로드
리스너가 true로 설정되고, 이것이 다시
use-CORS-preflight 플래그가 설정되도록 하기 때문이다.)
3.5.1. open() 메서드
client . open(method, url [, async = true [, username = null [, password = null]]])-
요청 메서드, 요청 URL, 그리고 요청이 동기인지 여부를 설정한다.
만약 method가 유효한 메서드가 아니거나 url을 파싱할 수 없는 경우 "
SyntaxError"DOMException을 던집니다.만약 method가 `
CONNECT`, `TRACE`, 또는 `TRACK`와 대소문자를 구분하지 않고 일치하는 경우 "SecurityError"DOMException을 던집니다.만약 async가 false이고, 현재 전역 객체가
Window객체이며,timeout속성이 0이 아니거나responseType속성이 빈 문자열이 아닌 경우 "InvalidAccessError"DOMException을 던집니다.
작업자 외부에서 동기 XMLHttpRequest
는 최종 사용자 경험에 해로운 영향을 미치기 때문에 웹 플랫폼에서 제거되는 과정에 있습니다. (이는 여러 해에 걸친 긴 과정입니다.) 개발자는 현재 전역 객체가 Window
객체일 때 async 인수로 false를 전달해서는 안 됩니다. 사용자 에이전트는 개발자 도구에서 이러한 사용에 대해 강력하게 경고하도록 권장되며, 발생 시 "InvalidAccessError"
DOMException
을 던지는 실험을 수행할 수 있습니다.
open(method, url)
및
open(method, url, async, username, password)
메서드 단계는 다음과 같습니다:
-
만약 this의 관련 전역 객체(relevant global object)가
Window객체이고 그 객체의 연결된Document가 완전히 활성화(fully active)되지 않았다면, throw an "InvalidStateError"DOMException. -
만약 method가 method가 아니라면, throw an "
SyntaxError"DOMException. -
만약 method가 금지된 메서드(forbidden method)라면, throw an "
SecurityError"DOMException. -
parsedURL을 URL을 인코딩-파싱한 결과로 설정합니다. 이는 this의 관련 설정 객체를 기준으로 수행됩니다.
-
만약 parsedURL이 실패(failure)라면, throw an "
SyntaxError"DOMException. -
async 인수가 생략된 경우, async를 true로 설정하고, username과 password를 null로 설정합니다.
레거시 콘텐츠로 인해 async 인수가
undefined일 때와 생략될 때를 동일하게 처리하는 것이 불가능합니다. -
parsedURL의 host가 null이 아니라면:
-
username 인수가 null이 아니면, parsedURL과 username을 사용하여 username을 설정합니다.
-
password 인수가 null이 아니면, parsedURL과 password를 사용하여 password를 설정합니다.
-
-
만약 async가 false이고, 현재 전역 객체(current global object)가
Window객체이며, this의 timeout이 0이 아니거나 this의 response type이 빈 문자열이 아니라면, throw an "InvalidAccessError"DOMException. -
fetch가 이 시점에서 진행 중일 수 있습니다.
-
객체와 관련된 변수들을 다음과 같이 설정한다:
-
this의
send()호출됨을 false로 설정한다.
재정의 MIME 타입은 여기서 재정의되지 않는다. 이는
overrideMimeType()메서드가open()메서드보다 먼저 호출될 수 있기 때문이다. -
-
-
이벤트를 발화한다. 이름은
readystatechange이고, 대상은 this다.
open() 메서드가 두 개 정의된 이유는 XMLHttpRequest 표준을 작성하는 데 사용된 편집 소프트웨어의 제한
때문입니다.
3.5.2.
setRequestHeader() 메서드
client . setRequestHeader(name, value)-
기존 요청 헤더에 값을 덧붙이거나 새 요청 헤더를 추가한다.
상태가 opened가 아니거나
send()호출됨이 true이면, "InvalidStateError"DOMException을 던진다.name이 헤더 이름이 아니거나 value가 헤더 값이 아니면, "
SyntaxError"DOMException을 던진다.
setRequestHeader(name, value)
메서드 단계는 다음과 같다:
-
this의 상태가 opened가 아니면, "
InvalidStateError"DOMException을 던진다. -
this의
send()호출됨이 true이면, "InvalidStateError"DOMException을 던진다. -
value를 정규화한다.
-
name이 헤더 이름이 아니거나 value가 헤더 값이 아니면, "
SyntaxError"DOMException을 던진다.빈 바이트 시퀀스는 빈 헤더 값을 나타낸다.
-
(name, value)가 금지된 요청 헤더이면, 반환한다.
같은 헤더를 두 번 설정할 때의 결과를 보여주는 간단한 코드 예제:
// 다음 스크립트:
var client = new XMLHttpRequest();
client. open( 'GET' , 'demo.cgi' );
client. setRequestHeader( 'X-Test' , 'one' );
client. setRequestHeader( 'X-Test' , 'two' );
client. send();
// …다음 헤더가 전송됩니다:
// X-Test: one, two
3.5.3.
timeout getter와 setter
client . timeout-
밀리초 단위의 시간으로 설정할 수 있다. 0이 아닌 값으로 설정하면 주어진 시간이 지난 후 fetch 수행이 종료된다. 시간이 지나고, 요청이 아직 완료되지 않았으며, 동기가 false이면, 그때
timeout이벤트가 디스패치되며, 그렇지 않으면 "TimeoutError"DOMException이 (send()메서드에서) 던져진다.설정 시: 동기가 true이고 현재 전역 객체가
Window객체이면, "InvalidAccessError"DOMException을 던진다.
timeout 게터 단계는
this의 타임아웃을 반환하는 것이다.
timeout
세터 단계는 다음과 같다:
-
현재 전역 객체가
Window객체이고 this의 동기가 true이면, "InvalidAccessError"DOMException을 던진다.
이는
timeout
속성을
fetch 수행이 진행 중인 동안 설정할 수 있음을
뜻한다. 그런 일이 발생하면 여전히 fetch 수행의 시작 시점을 기준으로
측정된다.
3.5.4.
withCredentials getter와 setter
client . withCredentials-
교차 출처 요청에 자격 증명이 포함되어야 할 때 true이다. 교차 출처 요청에서 그것들이 제외되어야 할 때와 그 응답에서 쿠키가 무시되어야 할 때는 false이다. 초기값은 false.
설정 시: 상태가 unsent 또는 opened가 아니거나,
send()호출됨이 true이면, "InvalidStateError"DOMException을 던진다.
withCredentials 게터 단계는
this의 교차 출처
자격 증명을 반환하는 것이다.
withCredentials
세터 단계는 다음과 같다:
-
this의 상태가 unsent 또는 opened가 아니면, "
InvalidStateError"DOMException을 던진다. -
this의
send()호출됨이 true이면, "InvalidStateError"DOMException을 던진다. -
this의 교차 출처 자격 증명을 주어진 값으로 설정한다.
3.5.5. upload getter
client . upload-
연결된
XMLHttpRequestUpload객체를 반환한다. 데이터가 서버로 전송될 때 전송 정보를 수집하는 데 사용할 수 있다.
upload 게터 단계는
this의 업로드 객체를 반환하는 것이다.
3.5.6. send() 메서드
client . send([body = null])-
요청을 시작한다. body 인수는 있다면 요청 본문을 제공하며, 요청 메서드가
GET또는HEAD이면 무시된다.상태가 opened가 아니거나
send()호출됨이 true이면, "InvalidStateError"DOMException을 던진다.
send(body) 메서드
단계는 다음과 같다:
-
this의 상태가 opened가 아니면, "
InvalidStateError"DOMException을 던진다. -
this의
send()호출됨이 true이면, "InvalidStateError"DOMException을 던진다. -
body가 null이 아니면:
-
extractedContentType을 null로 둔다.
-
body가
Document이면, this의 요청 본문을 body가 직렬화되고, 변환되고, UTF-8 인코딩된 것으로 설정한다. -
그렇지 않으면:
-
originalAuthorContentType을 가져오기, 즉 `
Content-Type`을 this의 작성자 요청 헤더에서 가져온 결과로 둔다. -
originalAuthorContentType이 null이 아니면:
-
body가
Document객체,URLSearchParams객체, 또는 문자열이면:-
contentTypeRecord를 originalAuthorContentType를 구문 분석한 결과로 둔다.
-
contentTypeRecord가 failure가 아니고, contentTypeRecord의 매개변수["
charset"]가 존재하며, 매개변수["charset"]가 "UTF-8"에 대한 ASCII 대소문자 무시 일치가 아니면:
-
-
-
그렇지 않으면:
-
-
this의 업로드 객체에 이벤트 리스너가 하나 이상 등록되어 있으면, this의 업로드 리스너를 true로 설정한다.
-
req를 다음과 같이 초기화된 새 요청으로 둔다:
- 메서드
- This의 요청 메서드.
- URL
- This의 요청 URL.
- 헤더 리스트
- This의 작성자 요청 헤더.
- unsafe-request 플래그
- 설정됨.
- 본문
- This의 요청 본문.
- 클라이언트
- This의 관련 설정 객체.
- 모드
- "
cors". - use-CORS-preflight 플래그
- this의 업로드 리스너가 true이면 설정됨.
- 자격 증명 모드
- this의 교차 출처 자격 증명이 true이면
"
include"; 그렇지 않으면 "same-origin". - use-URL-credentials 플래그
- this의 요청 URL이 자격 증명을 포함하면 설정됨.
- 개시자 타입
- "
xmlhttprequest".
-
this의
send()호출됨을 true로 설정한다. -
-
진행 이벤트를 발화한다. 이름은
loadstart이고, 대상은 this이며, 0과 0을 사용한다. -
requestBodyTransmitted를 0으로 둔다.
-
requestBodyLength를 req의 본문의 길이로 둔다. 단, req의 본문이 null이 아닌 경우이다; 그렇지 않으면 0으로 둔다.
-
Assert: requestBodyLength는 정수이다.
-
this의 업로드 완료가 false이고 this의 업로드 리스너가 true이면, 진행 이벤트를 발화한다. 이름은
loadstart이고, 대상은 this의 업로드 객체이며, requestBodyTransmitted와 requestBodyLength를 사용한다. -
this의 상태가 opened가 아니거나 this의
send()호출됨이 false이면, 반환한다. -
bytesLength가 주어졌을 때 processRequestBodyChunkLength를 다음 단계들로 둔다:
-
requestBodyTransmitted를 bytesLength만큼 증가시킨다.
-
이 단계들이 마지막으로 호출된 이후 대략 50ms가 지나지 않았다면, 반환한다.
-
this의 업로드 리스너가 true이면, 진행 이벤트를 발화한다. 이름은
progress이고, 대상은 this의 업로드 객체이며, requestBodyTransmitted와 requestBodyLength를 사용한다.
이 단계들은 새 바이트가 전송될 때만 호출된다.
-
-
processRequestEndOfBody를 다음 단계들로 둔다:
-
진행 이벤트를 발화한다. 이름은
progress이고, 대상은 this의 업로드 객체이며, requestBodyTransmitted와 requestBodyLength를 사용한다. -
진행 이벤트를 발화한다. 이름은
load이고, 대상은 this의 업로드 객체이며, requestBodyTransmitted와 requestBodyLength를 사용한다. -
진행 이벤트를 발화한다. 이름은
loadend이고, 대상은 this의 업로드 객체이며, requestBodyTransmitted와 requestBodyLength를 사용한다.
-
response가 주어졌을 때 processResponse를 다음 단계들로 둔다:
-
이벤트를 발화한다. 이름은
readystatechange이고, 대상은 this다. -
this의 응답의 본문이 null이면, 응답 본문 끝 처리를 this에 대해 실행하고 반환한다.
-
length가 정수가 아니면, 이를 0으로 설정한다.
-
bytes가 주어졌을 때 processBodyChunk를 다음 단계들로 둔다:
-
이 단계들이 마지막으로 호출된 이후 대략 50ms가 지나지 않았다면, 반환한다.
-
이벤트를 발화한다. 이름은
readystatechange이고, 대상은 this다.웹 호환성 때문에
readystatechange는 this의 상태가 변경되는 것보다 더 자주 발화된다. -
진행 이벤트를 발화한다. 이름은
progress이고, 대상은 this이며, this의 수신된 바이트의 길이와 length를 사용한다.
-
processEndOfBody를 이 단계로 둔다: 응답 본문 끝 처리를 this에 대해 실행한다.
-
processBodyError를 다음 단계들로 둔다:
-
점진적으로 읽는다. 대상은 this의 응답의 본문이고, processBodyChunk, processEndOfBody, processBodyError, 그리고 this의 관련 전역 객체가 주어진다.
-
this의 fetch 컨트롤러를 req를 fetch 수행한 결과로 설정한다. 여기서 processRequestBodyChunkLength는 processRequestBodyChunkLength로 설정되고, processRequestEndOfBody는 processRequestEndOfBody로 설정되며, processResponse는 processResponse로 설정된다.
-
now를 현재 시각으로 둔다.
-
다음 단계들을 병렬로 실행한다:
-
-
-
processedResponse를 false로 둔다.
-
response와 nullOrFailureOrBytes가 주어졌을 때 processResponseConsumeBody를 다음 단계들로 둔다:
-
this의 fetch 컨트롤러를 req를 fetch 수행한 결과로 설정한다. 여기서 processResponseConsumeBody는 processResponseConsumeBody로 설정되고, useParallelQueue는 true로 설정된다.
-
now를 현재 시각으로 둔다.
-
processedResponse가 true이거나, this의 타임아웃이 0이 아니고 now 이후 this의 타임아웃 밀리초가 지날 때까지 일시 중지한다.
-
processedResponse가 false이면, this의 타임아웃됨을 true로 설정하고 종료한다. 대상은 this의 fetch 컨트롤러다.
-
타이밍을 보고한다. 대상은 this의 fetch 컨트롤러이고, 현재 전역 객체가 주어진다.
-
응답 본문 끝 처리를 this에 대해 실행한다.
-
XMLHttpRequest
객체 xhr에 대해 응답 본문 끝 처리를 하려면, 다음 단계들을 실행한다:
-
xhr에 대해 오류를 처리한다.
-
length가 정수가 아니면, 이를 0으로 설정한다.
-
xhr의 동기가 false이면, 진행 이벤트를 발화한다. 이름은
progress이고, 대상은 xhr이며, transmitted와 length를 사용한다. -
xhr의 상태를 done으로 설정한다.
-
xhr의
send()호출됨을 false로 설정한다. -
이벤트를 발화한다. 이름은
readystatechange이고, 대상은 xhr다. -
진행 이벤트를 발화한다. 이름은
load이고, 대상은 xhr이며, transmitted와 length를 사용한다. -
진행 이벤트를 발화한다. 이름은
loadend이고, 대상은 xhr이며, transmitted와 length를 사용한다.
XMLHttpRequest
객체 xhr에 대해 오류
처리를 하려면,
다음 단계들을 실행한다:
-
xhr의
send()호출됨이 false이면, 반환한다. -
xhr의 타임아웃됨이 true이면, xhr,
timeout, 그리고 "TimeoutError"DOMException에 대해 요청 오류 단계를 실행한다. -
그렇지 않고, xhr의 응답의 중단됨 플래그가 설정되어 있으면, xhr,
abort, 그리고 "AbortError"DOMException에 대해 요청 오류 단계를 실행한다. -
그렇지 않고, xhr의 응답이 네트워크 오류이면, xhr,
error, 그리고 "NetworkError"DOMException에 대해 요청 오류 단계를 실행한다.
XMLHttpRequest
객체 xhr,
event, 그리고 선택적으로 exception에 대한 요청 오류
단계는 다음과 같다:
-
xhr의 상태를 done으로 설정한다.
-
xhr의
send()호출됨을 false로 설정한다. -
이벤트를 발화한다. 이름은
readystatechange이고, 대상은 xhr다.이 시점에서는 xhr의 동기가 false임이 분명하다.
-
xhr의 업로드 완료가 false이면:
-
xhr의 업로드 완료를 true로 설정한다.
-
xhr의 업로드 리스너가 true이면:
-
진행 이벤트를 발화한다. 이름은 event이고, 대상은 xhr의 업로드 객체이며, 0과 0을 사용한다.
-
진행 이벤트를 발화한다. 이름은
loadend이고, 대상은 xhr의 업로드 객체이며, 0과 0을 사용한다.
-
-
-
진행 이벤트를 발화한다. 이름은 event이고, 대상은 xhr이며 0과 0을 사용한다.
-
진행 이벤트를 발화한다. 이름은
loadend이고, 대상은 xhr이며 0과 0을 사용한다.
3.5.7. abort() 메서드
client . abort()- 모든 네트워크 활동을 취소한다.
abort() 메서드 단계는 다음과 같다:
-
중단한다. 대상은 this의 fetch 컨트롤러다.
-
this의 상태가 this의
send()호출됨이 true인 opened, headers received, 또는 loading이면, this와abort에 대해 요청 오류 단계를 실행한다. -
this의 상태가 done이면, this의 상태를 unsent로 설정하고, this의 응답을 네트워크 오류로 설정한다.
readystatechange이벤트는 디스패치되지 않는다.
3.6. 응답
3.6.1.
responseURL getter
responseURL 게터 단계는
this의 응답의 URL이
null이면 빈 문자열을 반환하고, 그렇지 않으면 exclude fragment flag가 설정된 그
직렬화를 반환하는 것이다.
3.6.2. status getter
status getter 단계는 this의 응답의 상태를 반환합니다.
3.6.3.
statusText getter
statusText getter 단계는 this의 응답의 상태 메시지를 반환합니다.
3.6.4.
getResponseHeader() 메서드
getResponseHeader(name) 메서드 단계는
name을 가져오는 결과를 반환합니다. 대상: this의 응답의 헤더 목록.
Fetch 현행 표준은 this의 응답의 헤더 목록을 필터링합니다. [FETCH]
다음 스크립트에 대해:
var client = new XMLHttpRequest();
client. open( "GET" , "unicorns-are-awesome.txt" , true );
client. send();
client. onreadystatechange = function () {
if ( this . readyState == this . HEADERS_RECEIVED) {
print( client. getResponseHeader( "Content-Type" ));
}
}
print() 함수는 다음과 같은 내용을 처리할 수 있습니다:
text/plain; charset=UTF-8
3.6.5. getAllResponseHeaders()
메서드
바이트 시퀀스 a가 legacy-uppercased-byte보다 작은 바이트 시퀀스 b라면, 다음 단계가 true를 반환합니다:
-
A를 a의 byte-uppercased 값으로 설정합니다.
-
B를 b의 byte-uppercased 값으로 설정합니다.
-
A가 바이트 기준으로 작은지 B와 비교해 반환합니다.
getAllResponseHeaders() 메서드 단계는 다음과
같습니다:
-
output을 빈 바이트 시퀀스로 설정합니다.
-
headers를 initialHeaders를 오름차순 정렬한 결과로 설정합니다. 조건: a의 이름이 legacy-uppercased-byte 기준으로 b의 이름보다 작다면.
안타깝게도, 이는 배포된 콘텐츠와의 호환성을 위해 필요합니다.
-
각 header에 대해, header의 이름, 뒤에 0x3A 0x20 바이트 쌍, header의 값, 그리고 0x0D 0x0A 바이트 쌍을 output에 추가합니다.
-
output을 반환합니다.
Fetch 현행 표준은 this의 응답의 헤더 목록을 필터링합니다. [FETCH]
다음 스크립트에 대해:
var client = new XMLHttpRequest();
client. open( "GET" , "narwhals-too.txt" , true );
client. send();
client. onreadystatechange = function () {
if ( this . readyState == this . HEADERS_RECEIVED) {
print( this . getAllResponseHeaders());
}
}
print() 함수는 다음과 같은 내용을 처리할 수 있습니다:
connection: Keep-Alive
content-type: text/plain; charset=utf-8
date: Sun, 24 Oct 2004 04:58:38 GMT
keep-alive: timeout=15, max=99
server: Apache/1.3.31 (Unix)
transfer-encoding: chunked
3.6.6. 응답 본문
응답 MIME 타입 가져오기를
XMLHttpRequest
객체 xhr에 대해 실행하려면, 다음 단계를 따르십시오:
-
mimeType을 MIME 타입 추출 결과로 설정합니다. 대상: xhr의 응답의 헤더 목록.
-
만약 mimeType이 실패라면, mimeType을
text/xml로 설정합니다. -
mimeType을 반환합니다.
최종 MIME 타입 가져오기를
XMLHttpRequest
객체 xhr에 대해 실행하려면, 다음 단계를 따르십시오:
-
만약 xhr의 override MIME 타입이 null이라면, 응답 MIME 타입 가져오기 결과를 반환합니다. 대상: xhr.
-
xhr의 override MIME 타입을 반환합니다.
최종 인코딩 가져오기를
XMLHttpRequest
객체 xhr에 대해 실행하려면, 다음 단계를 따르십시오:
-
label을 null로 설정합니다.
-
responseMIME을 응답 MIME 타입 가져오기 결과로 설정합니다. 대상: xhr.
-
만약 responseMIME의 매개변수["
charset"]이 존재하면, label을 해당 값으로 설정합니다. -
만약 xhr의 override MIME 타입의 매개변수["
charset"]이 존재하면, label을 해당 값으로 설정합니다. -
만약 label이 null이라면, null을 반환합니다.
-
encoding을 인코딩 가져오기 결과로 설정합니다. 대상: label.
-
만약 encoding이 실패라면, null을 반환합니다.
-
encoding을 반환합니다.
위 단계는 최종 MIME 타입 가져오기를 사용하지 않도록 의도적으로 설계되었습니다. 이는 웹 호환성을 위해 필요합니다.
문서 응답 설정을
XMLHttpRequest
객체 xhr에 대해 실행하려면, 다음 단계를 따르십시오:
-
finalMIME을 최종 MIME 타입 가져오기 결과로 설정합니다. 대상: xhr.
-
만약 finalMIME이 HTML MIME 타입 또는 XML MIME 타입이 아니라면, 반환합니다.
-
만약 xhr의 응답 타입이 빈 문자열이고, finalMIME이 HTML MIME 타입이라면, 반환합니다.
이는 xhr의 응답 타입이 "
document"인 경우로 제한되어 기존 콘텐츠를 깨뜨리는 것을 방지합니다. -
만약 finalMIME이 HTML MIME 타입이라면:
-
charset을 최종 인코딩 가져오기 결과로 설정합니다. 대상: xhr.
-
만약 charset이 null이라면, 바이트 스트림의 처음 1024 바이트를 사전 스캔합니다. 이 작업이 실패하지 않으면, charset을 해당 반환값으로 설정합니다.
-
만약 charset이 null이라면, charset을 UTF-8로 설정합니다.
-
document를 문서(document)로 설정합니다. 이는 HTML 표준의 HTML 파서 규칙에 따라 스크립팅이 비활성화된 상태로 xhr의 수신된 바이트를 구문 분석한 결과를 나타냅니다. 이때 확실히 알려진 인코딩은 charset입니다. [HTML]
-
document를 HTML 문서로 플래그를 설정합니다.
-
-
그 외의 경우, document를 문서(document)로 설정합니다. 이는 XML 파서를 XML 스크립팅 지원 비활성화 상태로 xhr의 수신된 바이트에서 실행한 결과를 나타냅니다. 이 작업이 실패하면(지원되지 않는 문자 인코딩, 네임스페이스 잘못된 형식 오류 등), null을 반환합니다. [HTML]
참조된 리소스는 로드되지 않으며, 관련된 XSLT도 적용되지 않습니다.
-
만약 charset이 null이라면, charset을 UTF-8로 설정합니다.
-
document의 인코딩을 charset으로 설정합니다.
-
document의 컨텐츠 타입을 finalMIME으로 설정합니다.
-
document의 원점(origin)을 xhr의 관련 설정 객체의 원점(origin)으로 설정합니다.
-
xhr의 응답 객체를 document로 설정합니다.
텍스트 응답 가져오기를
XMLHttpRequest
객체 xhr에 대해 실행하려면, 다음 단계를 따르십시오:
-
charset을 최종 인코딩 가져오기 결과로 설정합니다. 대상: xhr.
-
만약 xhr의 응답 타입이 빈 문자열이고, charset이 null이며, 최종 MIME 타입 가져오기 결과가 XML MIME 타입이라면, XML 명세에 설정된 규칙을 사용해 인코딩을 결정합니다. charset을 결정된 인코딩으로 설정합니다. [XML] [XML-NAMES]
이는 xhr의 응답 타입이 빈 문자열로 유지되도록 제한하며, 비-레거시 응답 타입 값 "
text"를 간단하게 유지합니다. -
만약 charset이 null이라면, charset을 UTF-8로 설정합니다.
작성자는 항상 리소스를 UTF-8로 인코딩하도록 강력히 권장됩니다.
3.6.7.
overrideMimeType() 메서드
client . overrideMimeType(mime)-
응답의 `
Content-Type` 헤더 값을 mime로 간주합니다. (헤더를 변경하지는 않습니다.)InvalidStateErrorDOMException을 발생시킵니다. 조건: state가 loading 또는 done인 경우.
overrideMimeType(mime) 메서드 단계는
다음과 같습니다:
-
this의 상태가 loading 또는 done이면, "
InvalidStateError"DOMException을 던진다. -
this의 재정의 MIME 타입을 mime을 구문 분석한 결과로 설정한다.
-
this의 재정의 MIME 타입이 failure이면, this의 재정의 MIME 타입을
application/octet-stream으로 설정한다.
3.6.8.
responseType getter 및 setter
client . responseType [ = value ]-
응답 타입을 반환한다.
응답 타입을 변경하도록 설정할 수 있다. 값은 다음과 같다: 빈 문자열(기본값), "
arraybuffer", "blob", "document", "json", 그리고 "text".설정 시: 현재 전역 객체가
Window객체가 아니면, "document"로 설정하는 것은 무시된다.설정 시: 상태가 loading 또는 done이면, "
InvalidStateError"DOMException을 던진다.설정 시: 동기가 true이고 현재 전역 객체가
Window객체이면, "InvalidAccessError"DOMException을 던진다.
responseType 게터 단계는
this의 응답 타입을 반환하는 것이다.
responseType
세터 단계는 다음과 같다:
-
this의 상태가 loading 또는 done이면, "
InvalidStateError"DOMException을 던진다. -
현재 전역 객체가
Window객체이고 this의 동기가 true이면, "InvalidAccessError"DOMException을 던진다.
3.6.9.
response getter
client . response-
응답 본문을 반환합니다.
response getter 단계는 다음과 같습니다:
-
this의 응답 타입이 빈 문자열 또는 "
text"이면:-
this에 대해 텍스트 응답을 가져온 결과를 반환한다.
-
this의 응답 타입이 "
arraybuffer"이면, this의 응답 객체를 this의 수신된 바이트를 나타내는 새ArrayBuffer객체로 설정한다. 이것이 예외를 던지면, this의 응답 객체를 failure로 설정하고 null을 반환한다.ArrayBuffer객체 할당은 성공이 보장되지 않는다. [ECMASCRIPT] -
그렇지 않고 this의 응답 타입이 "
blob"이면, this의 응답 객체를 this의 수신된 바이트를 나타내는 새Blob객체로 설정한다. 이때type은 this에 대해 최종 MIME 타입을 가져온 결과로 설정된다. -
그렇지 않고 this의 응답 타입이 "
document"이면, this에 대해 문서 응답을 설정한다. -
그렇지 않으면:
3.6.10.
responseText 가져오기
client . responseText-
응답을 텍스트로 반환합니다.
InvalidStateErrorDOMException을 발생시킵니다. 조건:responseType이 빈 문자열 또는 "text"가 아닌 경우.
responseText getter 단계는 다음과 같습니다:
-
this의 응답 타입이 빈 문자열 또는 "
text"가 아니면, "InvalidStateError"DOMException을 던진다. -
this에 대해 텍스트 응답을 가져온 결과를 반환한다.
3.6.11.
responseXML 가져오기
client . responseXML-
응답을 문서로 반환합니다.
InvalidStateErrorDOMException을 발생시킵니다. 조건:responseType이 빈 문자열 또는 "document"가 아닌 경우.
responseXML getter 단계는 다음과 같습니다:
-
this의 응답 타입이 빈 문자열 또는 "
document"가 아니면, "InvalidStateError"DOMException을 던진다. -
문서 응답을 설정한다. 대상은 this다.
3.7. 이벤트 요약
이 섹션은 규범적이지 않습니다.
다음 이벤트는 XMLHttpRequest
또는 XMLHttpRequestUpload
객체에서 디스패치됩니다:
| 이벤트 이름 | 인터페이스 | 디스패치 조건 |
|---|---|---|
readystatechange
| Event
| readyState
속성 값이 변경될 때, 단 UNSENT로 변경될 때는 제외.
|
loadstart
| ProgressEvent
| 페치가 시작될 때. |
progress
| ProgressEvent
| 데이터를 전송 중일 때. |
abort
| ProgressEvent
| 페치가 중단되었을 때. 예를 들어, abort()
메서드를 호출한 경우.
|
error
| ProgressEvent
| 페치가 실패했을 때. |
load
| ProgressEvent
| 페치가 성공했을 때. |
timeout
| ProgressEvent
| 작성자가 지정한 타임아웃이 페치 완료 전에 초과되었을 때. |
loadend
| ProgressEvent
| 페치가 완료되었을 때(성공 또는 실패). |
4. 인터페이스 FormData
typedef (File or USVString ); [FormDataEntryValue Exposed =(Window ,Worker )]interface {FormData constructor (optional HTMLFormElement ,form optional HTMLElement ?=submitter null );undefined append (USVString ,name USVString );value undefined append (USVString ,name Blob ,blobValue optional USVString );filename undefined delete (USVString );name FormDataEntryValue ?get (USVString );name sequence <FormDataEntryValue >getAll (USVString );name boolean has (USVString );name undefined set (USVString ,name USVString );value undefined set (USVString ,name Blob ,blobValue optional USVString );filename iterable <USVString ,FormDataEntryValue >; };
각 FormData
객체에는 연관된
entry list (즉,
entry list)가 있습니다. 이는 초기에는 비어 있습니다.
이 섹션은 이전에 entry, entry의 name 및 value, 그리고 create an entry 알고리즘을 정의했습니다. 이러한 정의는 HTML 표준으로 이동되었습니다. [HTML]
new FormData(form, submitter)
생성자의 단계는 다음과 같습니다:
-
form이 주어졌다면:
-
submitter가 null이 아니라면:
-
submitter가 submit button이 아니라면, throw a
TypeError. -
submitter의 form owner가 form이 아니라면, throw a "
NotFoundError"DOMException.
-
-
list를 constructing the entry list의 결과로 form과 submitter를 사용해 설정합니다.
-
list가 null이라면, throw an "
InvalidStateError"DOMException. -
this의 entry list를 list로 설정합니다.
-
append(name, value)
및
append(name, blobValue, filename)
메소드의 단계는 다음과 같습니다:
-
value를 주어진 경우 value로, 그렇지 않으면 blobValue로 설정합니다.
-
entry를 creating an entry의 결과로 name, value 및 filename (주어진 경우)을 사용해 설정합니다.
-
Append entry를 this의 entry list에 추가합니다.
value와 blobValue라는 매개변수가 존재하는 이유는 XMLHttpRequest 표준을 작성하는 데 사용된 편집 소프트웨어의 제한 때문입니다.
delete(name)
메서드 단계는 this의
엔트리
리스트에서
이름이 name인 모든 엔트리를
제거하는
것이다.
get(name) 메서드
단계는 다음과 같다:
getAll(name)
메서드 단계는 다음과 같다:
has(name) 메서드
단계는 this의
엔트리
리스트 안에
이름이 name인 엔트리가 있으면 true를 반환하고,
그렇지 않으면 false를 반환하는 것이다.
set(name, value)
및
set(name, blobValue, filename)
메서드 단계는 다음과 같다:
-
value를 주어진 경우 value로, 그렇지 않으면 blobValue로 둔다.
-
entry를 name, value, 그리고 filename이 주어진 경우 그것을 사용해 엔트리를 생성한 결과로 둔다.
-
this의 엔트리 리스트 안에 이름이 name인 엔트리들이 있으면, 첫 번째 그러한 엔트리를 entry로 교체하고, 나머지는 제거한다.
value라는 이름의 인수가 blobValue와 함께 있는 이유는 XMLHttpRequest Standard를 작성하는 데 사용되는 편집 소프트웨어의 한계 때문이다.
반복할 값 쌍은 this의 엔트리 리스트의 엔트리들이다. 키는 이름이고, 값은 값이다.
5. 인터페이스 ProgressEvent
[Exposed =(Window ,Worker )]interface :ProgressEvent Event {(constructor DOMString ,type optional ProgressEventInit = {});eventInitDict readonly attribute boolean lengthComputable ;readonly attribute double loaded ;readonly attribute double total ; };dictionary :ProgressEventInit EventInit {boolean =lengthComputable false ;double = 0;loaded double = 0; };total
이벤트는
ProgressEvent
인터페이스를 사용하여 어떤 종류의 진행 상황을 나타냅니다.
lengthComputable,
loaded, 그리고
total
getter 단계는 이들이 초기화된 값을 반환하도록 합니다.
5.1. ProgressEvent
인터페이스를 사용하여 이벤트 발생
진행 이벤트를
발생시키려면
이름이 e이고 target, transmitted, length가 주어졌을 때, 이벤트를 발생시킨다
이름이 e이고 target에서, ProgressEvent를
사용하며,
loaded
속성이 transmitted으로 초기화되고, length가 0이 아닌 경우,
lengthComputable
속성이 true로 초기화되며,
total
속성이 length로 초기화됩니다.
5.2. ProgressEvent
인터페이스를 사용하는 이벤트에 대한 권장 이름
이 섹션은 규범적이지 않습니다.
다음을 사용하는 경우 권장되는 type
속성 값은
이벤트입니다.
ProgressEvent
인터페이스는 아래 표에 요약되어 있습니다.
사양 편집자는 특정 시나리오에 맞게 세부 사항을 조정할 수 있지만,
관련 주제에 익숙한 사람들의 의견을 받을 수 있도록 WHATWG 커뮤니티와 사용에 대해 논의할 것을 강력히 권장합니다.
type
속성 값
| 설명 | 횟수 | 시기 |
|---|---|---|---|
loadstart
| 진행이 시작되었습니다. | 한 번. | 처음. |
progress
| 진행 중입니다. | 한 번 이상. | loadstart가
발생한 후.
|
error
| 진행 실패. | 0회 또는 1회(상호 배타적). | 마지막 progress가
발생한 후.
|
abort
| 진행이 종료되었습니다. | ||
timeout
| 설정된 시간이 만료되어 진행이 종료되었습니다. | ||
load
| 진행이 성공적으로 완료되었습니다. | ||
loadend
| 진행이 중단되었습니다. | 한 번. | error, abort, timeout 또는 load 중 하나가
발생한 후.
|
error, abort, timeout, 그리고
load 이벤트 타입은 상호 배타적입니다.
웹 플랫폼 전반에서 error, abort,
timeout, 그리고 load 이벤트 타입은
bubbles
및 cancelable
속성이 false로 초기화되므로, 일관성을 위해
이벤트는
ProgressEvent
인터페이스를 사용하여 동일하게 초기화하는 것이 제안됩니다.
5.3. 보안 고려 사항
교차 출처 요청의 경우, Fetch 표준에서 정의된
CORS
프로토콜과 같은 어떤 형태의 옵트인이 필요하며, 이는
이벤트가
ProgressEvent
인터페이스를 사용하여
디스패치
되기 전에 사용되어야 하며, 그렇지 않으면 정보(예: 크기)가 공개될 수 있습니다. [FETCH]
5.4. 예시
이 예시에서는 XMLHttpRequest와,
이전 섹션에서 정의된 개념들 그리고 HTML
progress
요소를 결합하여 리소스를
페치(fetch)하는 과정을 표시합니다.
<!DOCTYPE html>
< title > 마법의 유니콘을 기다리는 중</ title >
< progress id = p ></ progress >
< script >
var progressBar = document. getElementById( "p" ),
client = new XMLHttpRequest()
client. open( "GET" , "magical-unicorns" )
client. onprogress = function ( pe) {
if ( pe. lengthComputable) {
progressBar. max = pe. total
progressBar. value = pe. loaded
}
}
client. onloadend = function ( pe) {
progressBar. value = pe. loaded
}
client. send()
</ script >
완전한 작동 코드는 물론 더 정교하며 네트워크 오류 또는 최종 사용자가 요청을 종료하는 등의 시나리오를 처리해야 합니다.
감사의 글
감사의 말씀을 전합니다: Addison Phillips, Adrian Bateman, Ahmed Kamel, Alan Thomas, Alex Hopmann, Alex Vincent, Alexey Proskuryakov, Ali Alabbas, Andrea Marchesini, Asbjørn Ulsberg, Bertrand Guay-Paquet, Björn Höhrmann, Boris Zbarsky, Caitlin Potter, Cameron McCormack, 白丞祐 (Cheng-You Bai), Chris Marrin, Christophe Jolif, Charles McCathieNevile, Chirag S Kumar, Dan Winship, David Andersson, David Flanagan, David Håsäther, David Levin, Dean Jackson, Denis Sureau, Domenic Denicola, Dominik Röttsches, Doug Schepers, Douglas Livingstone, Elliott Sprehn, Elliotte Harold, Eric Lawrence, Eric Uhrhane, Erik Arvidsson, Erik Dahlström, Feras Moussa, Gideon Cohn, Glenn Adams, Gorm Haug Eriksen, Gregory Terzian, Håkon Wium Lie, Hallvord R. M. Steen, Henri Sivonen, Hiroshige Hayashizaki, Huub Schaeks, Ian Clelland, Ian Davis, Ian Hickson, Ivan Herman, Jake Archibald, Jared Jacobs, Jarred Nicholls, Jeff Walden, Jens Lindström, Jim Deegan, Jim Ley, Joe Farro, Jonas Sicking, Julian Reschke, 송정기 (Jungkee Song), 呂康豪 (Kang-Hao Lu), Karl Dubost, Keith Yeung, 田村健人 (Kent TAMURA), Lachlan Hunt, Maciej Stachowiak, Magnus Kristiansen, Manish Goregaokar, Marc Hadley, Marcos Caceres, Mark Baker, Mark Birbeck, Mark Nottingham, Mark S. Miller, Martin Hassman, Mike Pennisi, Mohamed Zergaoui, Ms2ger, Noam Rosenthal, Odin Hørthe Omdal, Olli Pettay, Pawel Glowacki, Peter Michaux, Philip Jägenstedt, Philip Taylor, Rashika Jaggi, Robin Berjon, Rune F. Halvorsen, Ruud Steltenpool, Ryo Onodera, Sam Sneddon, Sergiu Dumitriu, Shivakumar Jagalur Matt, Sigbjørn Finne, Simon Pieters, Stewart Brodie, Sunava Dutta, Takeshi Kurosawa, Takeshi Yoshino, Thomas Roessler, Thomas Wisniewski, Tom Magliery, Travis Leithead, triple-underscore, Yaron Tausky, Yehuda Katz, Youenn Fablet, 그리고 Zhenbin Xu 이 표준에 기여해 주신 모든 분들께 감사를 표합니다.
특별히 Microsoft 직원들에게 감사를 드립니다. 이들은
XMLHttpRequest
인터페이스를 처음 구현했으며, 이는 Windows Internet Explorer 브라우저에서 처음 널리 배포되었습니다.
특별히 Ian Hickson에게 감사를 드립니다. HTML 표준(당시 Web Applications 1.0)에서 이 사양의 초기 버전을 작성해 주셨습니다. [HTML]
특별히 W3C SVG WG에게 감사를 드립니다. 이들은
ProgressEvent
클래스를
SVG Micro DOM의 일환으로 초안 작성해
주셨습니다.
이 표준은 Anne van Kesteren (Apple, annevk@annevk.nl)에 의해 작성되었습니다.
지적 재산권
Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). 이 작업은 Creative Commons Attribution 4.0 International License 하에 라이선스가 부여되었습니다. 소스 코드에 통합된 일부는 BSD 3-Clause License 하에 라이선스가 부여됩니다.
이는 현행 표준입니다. 특허 검토 버전에 관심이 있는 분은 Living Standard Review Draft를 확인하시기 바랍니다.