파일 API

1. 소개

이 섹션은 참고용입니다.

웹 애플리케이션은 사용자가 원격 서버로 업로드하거나 풍부한 웹 애플리케이션 내에서 다루고자 하는 파일을 포함하여, 가능한 한 다양한 범위의 사용자 입력을 다룰 수 있어야 합니다. 이 명세는 파일의 기본 표현, 파일 목록, 파일 접근 중 발생하는 오류, 그리고 프로그래밍 방식으로 파일을 읽는 방법을 정의합니다. 또한 이 명세는 "원시 데이터"를 나타내는 인터페이스도 정의하며, 이는 적합한 사용자 에이전트의 메인 스레드에서 비동기적으로 처리될 수 있습니다. 이 명세에서 정의된 인터페이스와 API는 웹 플랫폼에 노출된 다른 인터페이스 및 API와 함께 사용할 수 있습니다.

File 인터페이스는 일반적으로 기본 파일 시스템에서 얻은 파일 데이터를 나타내며, Blob 인터페이스 ("Binary Large Object" - 본래 Google Gears에서 웹 API에 도입된 명칭) 는 불변의 원시 데이터를 나타냅니다. File 또는 Blob 읽기는 메인 스레드에서 비동기적으로 처리되어야 하며, 스레드 기반 웹 애플리케이션에서는 선택적으로 동기 API를 사용할 수 있습니다. 파일을 비동기적으로 읽는 API는 사용자 에이전트의 메인 스레드가 블로킹되거나 UI가 "멈추는" 것을 방지합니다. 이 명세는 이벤트 모델 기반의 비동기 API를 정의하여 File 또는 Blob의 데이터를 읽고 접근할 수 있도록 합니다. FileReader 객체는 파일 데이터를 비동기적으로 읽을 수 있는 메서드를 제공하며, 이벤트 핸들러 콘텐츠 속성과 이벤트 발생을 통해 파일 데이터를 접근할 수 있습니다. 이벤트와 이벤트 핸들러를 사용함으로써 개별 코드 블록이 읽기 진행 상황(특히 원격 드라이브나 마운트된 드라이브 등, 파일 접근 성능이 로컬 드라이브와 다를 수 있는 경우) 및 파일 읽기 중 발생할 수 있는 오류 상황을 모니터링할 수 있습니다. 아래 예제가 이를 보여줍니다.

function startRead() {
  // DOM을 통해 input 요소 얻기

  var file = document.getElementById('file').files[0];
  if(file){
    getAsText(file);
  }
}

function getAsText(readFile) {

  var reader = new FileReader();

  // 파일을 UTF-16으로 메모리에 읽기
  reader.readAsText(readFile, "UTF-16");

  // 진행 상황, 성공, 오류 처리
  reader.onprogress = updateProgress;
  reader.onload = loaded;
  reader.onerror = errorHandler;
}

function updateProgress(evt) {
  if (evt.lengthComputable) {
    // evt.loaded와 evt.total은 ProgressEvent 속성입니다
    var loaded = (evt.loaded / evt.total);
    if (loaded < 1) {
      // 진행 바 길이 증가
      // style.width = (loaded * 200) + "px";
    }
  }
}

function loaded(evt) {
  // 읽은 파일 데이터 얻기
  var fileString = evt.target.result;
  // UTF-16 파일 덤프 처리
  if(utils.regexp.isChinese(fileString)) {
    // 한자 + 이름 검증
  }
  else {
    // 다른 문자셋 테스트 실행
  }
  // xhr.send(fileString)
}

function errorHandler(evt) {
  if(evt.target.error.name == "NotReadableError") {
    // 파일을 읽을 수 없음
  }
}

2. 용어 및 알고리즘

이 명세에서 알고리즘을 종료한다라고 할 때, 사용자 에이전트는 현재 수행 중인 단계를 마친 후 알고리즘을 종료해야 합니다. 이 명세에서 정의된 비동기 읽기 메서드는 해당 알고리즘이 종료되기 전에 반환될 수 있으며, abort() 호출로 종료될 수 있습니다.

이 명세의 알고리즘과 단계에서는 다음 수학 연산을 사용합니다:

• max(a,b)는 a와 b 중 더 큰 값을 반환하며, WebIDL [WebIDL]에서 정의된 정수로 항상 수행됩니다; 예를 들어 max(6,4) 연산의 결과는 6입니다. 이 연산은 ECMAScript [ECMA-262]에서도 정의되어 있습니다.

• min(a,b)는 a와 b 중 더 작은 값을 반환하며, WebIDL [WebIDL]에서 정의된 정수로 항상 수행됩니다; 예를 들어 min(6,4) 연산의 결과는 4입니다. 이 연산은 ECMAScript [ECMA-262]에서도 정의되어 있습니다.

• < (작다), ≤ (작거나 같다), > (크다)와 같은 수학 비교 연산은 ECMAScript [ECMA-262]와 동일하게 동작합니다.

Unix Epoch 용어는 이 명세에서 1970년 1월 1일 00:00:00 UTC (또는 1970-01-01T00:00:00Z, ISO 8601)를 가리키며, ECMA-262 [ECMA-262]에서 개념적으로 "0"에 해당하는 시간입니다.

3. Blob 인터페이스와 바이너리 데이터

Blob 객체는 바이트 시퀀스를 참조합니다. size 속성은 바이트 시퀀스의 전체 바이트 수를 나타내며, type 속성은 바이트 시퀀스의 미디어 타입을 나타내는 소문자 ASCII 인코딩 문자열입니다.

각 Blob은 내부적으로 스냅샷 상태를 가져야 하며, 해당 기저 저장소가 존재한다면 그 저장소의 상태로 최초 설정되어야 합니다. 스냅샷 상태에 대한 추가 규범적 정의는 File에서 찾아볼 수 있습니다.

[Exposed=(Window,Worker), Serializable]
interface Blob {
  constructor(optional sequence<BlobPart> blobParts,
              optional BlobPropertyBag options = {});

  readonly attribute unsigned long long size;
  readonly attribute DOMString type;

  // slice Blob into byte-ranged chunks
  Blob slice(optional [Clamp] long long start,
            optional [Clamp] long long end,
            optional DOMString contentType);

  // read from the Blob.
  [NewObject] ReadableStream stream();
  [NewObject] Promise<USVString> text();
  [NewObject] Promise<ArrayBuffer> arrayBuffer();
  [NewObject] Promise<Uint8Array> bytes();
};

enum EndingType { "transparent", "native" };

dictionary BlobPropertyBag {
  DOMString type = "";
  EndingType endings = "transparent";
};

typedef (BufferSource or Blob or USVString) BlobPart;

Blob 객체는 직렬화 가능한 객체입니다. 직렬화 단계는 value, serialized가 주어졌을 때 다음과 같습니다:

1. serialized.[[SnapshotState]]를 value의 스냅샷 상태로 설정합니다.

2. serialized.[[ByteSequence]]를 value의 기저 바이트 시퀀스로 설정합니다.

역직렬화 단계는 serialized, value가 주어졌을 때 다음과 같습니다:

1. value의 스냅샷 상태를 serialized.[[SnapshotState]]로 설정합니다.

2. value의 기저 바이트 시퀀스를 serialized.[[ByteSequence]]로 설정합니다.

3.1. 생성자

3.1.1. 생성자 매개변수

Blob() 생성자는 아래의 매개변수들로 호출될 수 있습니다:

blobParts sequence

다음 타입의 요소들을 아무 순서로든 여러 개 받을 수 있습니다:

• BufferSource 요소.

• Blob 요소.

• USVString 요소.

선택적 BlobPropertyBag

다음 선택 멤버를 받을 수 있습니다:

• type, Blob의 미디어 타입을 나타내는 소문자 ASCII 인코딩 문자열. 규범적 조건은 § 3.1 생성자에서 제공됩니다.

• endings, "transparent" 또는 "native" 값을 가질 수 있는 enum. 기본값은 "transparent"입니다. "native"로 설정된 경우 USVString 요소의 줄 끝 처리가 native로 변환됩니다.

// 새 Blob 객체 생성

var a = new Blob();

// 1024바이트 ArrayBuffer 생성
// buffer는 File을 읽어서도 얻을 수 있음

var buffer = new ArrayBuffer(1024);

// buffer로 ArrayBufferView 객체 생성

var shorts = new Uint16Array(buffer, 512, 128);
var bytes = new Uint8Array(buffer, shorts.byteOffset + shorts.byteLength);

var b = new Blob(["foobarbazetcetc" + "birdiebirdieboo"], {type: "text/plain;charset=utf-8"});

var c = new Blob([b, shorts]);

var a = new Blob([b, c, bytes]);

var d = new Blob([buffer, b, c, bytes]);

3.2. 속성

size, 타입 unsigned long long, 읽기 전용

바이트 시퀀스의 크기를 바이트 수로 반환합니다. 가져올 때, 적합한 사용자 에이전트는 FileReader 또는 FileReaderSync 객체로 읽을 수 있는 총 바이트 수를 반환해야 하며, Blob에 읽을 바이트가 없으면 0을 반환해야 합니다.

type, 타입 DOMString, 읽기 전용

Blob의 미디어 타입을 나타내는 소문자 ASCII 인코딩 문자열입니다. 가져올 때, 사용자 에이전트는 Blob의 타입을 소문자 ASCII 인코딩 문자열로 반환해야 하며, 바이트 시퀀스로 변환되었을 때 파싱 가능한 MIME 타입이어야 합니다. 타입을 결정할 수 없는 경우에는 빈 문자열(0 바이트)을 반환해야 합니다.

type 속성은 웹 애플리케이션에서 생성자 호출이나 slice() 호출을 통해 직접 설정할 수 있습니다. 이 경우, 이 속성에 대한 추가 규범 조건은 § 3.1 생성자, § 4.1 생성자, 그리고 § 3.3.1 slice() 메서드에 각각 정의되어 있습니다. 사용자 에이전트는 또한 바이트 시퀀스가 디스크 파일에서 얻어진 경우 등 Blob의 타입을 자체적으로 결정할 수도 있습니다. 이 경우에는 파일 타입 가이드라인에 추가 규범 조건이 있습니다.

참고: Blob의 타입 t는 파싱 가능한 MIME 타입으로 간주됩니다. 만약 Blob 객체의 타입을 나타내는 ASCII 인코딩 문자열을 바이트 시퀀스로 변환해 MIME 타입 파싱 알고리즘을 수행했을 때 실패를 반환하지 않으면 파싱 가능한 타입입니다.

참고: type 속성의 사용은 패키지 데이터 알고리즘에 영향을 주며, fetch를 통해 blob URL을 가져올 때 Content-Type 헤더를 결정합니다.

3.3. 메서드 및 매개변수

3.3.1. slice() 메서드

// DOM을 통해 input 요소 얻기

var file = document.getElementById('file').files[0];
if(file)
{
  // 파일의 동일한 복사본 생성
  // 아래 두 호출은 동일함

  var fileClone = file.slice();
  var fileClone2 = file.slice(0, file.size);

  // 파일의 중간부터 1/2 청크로 슬라이스 (음수 사용)
  var fileChunkFromEnd = file.slice(-(Math.round(file.size/2)));

  // 파일의 시작부터 1/2 청크로 슬라이스

  var fileChunkFromStart = file.slice(0, Math.round(file.size/2));

  // 파일의 시작부터 끝에서 150 바이트 전까지 슬라이스

  var fileNoMetadata = file.slice(0, -150, "application/experimental");
}

3.3.2. stream() 메서드

stream() 메서드는 호출 시 get stream을 this에 대해 호출한 결과를 반환해야 합니다.

3.3.3. text() 메서드

text() 메서드는 호출 시 다음 단계를 실행해야 합니다:

1. stream을 get stream을 this에 대해 호출한 결과로 설정합니다.

2. reader를 stream에서 reader 얻기의 결과로 설정합니다. 만약 예외가 발생하면, 해당 예외로 거부된 새로운 프라미스를 반환합니다.

3. promise를 reader와 함께 stream에서 모든 바이트 읽기의 결과로 설정합니다.

4. promise를 UTF-8로 디코드(UTF-8 decode)한 결과를 반환하는 이행 핸들러로 변환한 결과를 반환합니다.

참고: 이 동작은 readAsText()의 동작과 다르며, Fetch의 text()와 더 잘 맞추기 위한 것입니다. 이 메서드는 항상 UTF-8 인코딩을 사용하며, FileReader는 blob의 type과 전달된 인코딩 이름에 따라 다른 인코딩을 사용할 수 있습니다.

3.3.4. arrayBuffer() 메서드

arrayBuffer() 메서드는 호출될 때 다음 단계를 실행해야 합니다:

1. stream을 get stream을 this에 대해 호출한 결과로 설정합니다.

2. reader를 stream에서 reader 얻기의 결과로 설정합니다. 예외가 발생하면, 해당 예외로 거부된 새로운 프라미스를 반환합니다.

3. promise를 reader와 함께 stream에서 모든 바이트 읽기의 결과로 설정합니다.

4. promise를 이행 핸들러로 변환한 결과를 반환하는데, 이 핸들러는 첫 번째 인자를 내용으로 하는 ArrayBuffer의 새 객체를 반환합니다.

3.3.5. bytes() 메서드

bytes() 메서드는 호출될 때 다음 단계를 실행해야 합니다:

1. stream을 get stream을 this에 대해 호출한 결과로 설정합니다.

2. reader를 stream에서 reader 얻기의 결과로 설정합니다. 예외가 발생하면, 해당 예외로 거부된 새로운 프라미스를 반환합니다.

3. promise를 reader와 함께 stream에서 모든 바이트 읽기의 결과로 설정합니다.

4. promise를 이행 핸들러로 변환한 결과를 반환하는데, 이 핸들러는 첫 번째 인자를 내용으로 하는 Uint8Array의 새 객체를 반환하고, 그 객체는 ArrayBuffer를 감쌉니다.

4. File 인터페이스

File 객체는 Blob 객체로, 문자열 타입의 name 속성을 가집니다. 이 객체는 웹 애플리케이션 내에서 생성자를 통해 만들 수도 있고, 또는 기본(운영체제) 파일 시스템의 파일에서 가져온 바이트 시퀀스의 참조일 수도 있습니다.

File 객체가 디스크의 파일에서 유래된 바이트 시퀀스를 참조하는 경우, 그 스냅샷 상태는 File 객체가 생성된 시점의 디스크 파일 상태로 설정되어야 합니다.

참고: 이는 사용자 에이전트에게 구현 난이도가 있으므로 must가 아닌 should 요구사항입니다 [RFC2119]. 사용자 에이전트는 File 객체의 스냅샷 상태를 참조가 생성된 시점의 디스크 저장소 상태로 맞추도록 노력해야 합니다. 만약 파일이 참조 후 디스크에서 수정되면, File의 스냅샷 상태는 실제 저장소 상태와 다를 수 있습니다. 사용자 에이전트는 수정 시간 정보 등 다양한 방법으로 스냅샷 상태를 관리할 수 있지만, 이것은 구현 세부 사항에 속합니다.

File 객체가 디스크의 파일을 참조할 때, 사용자 에이전트는 해당 파일의 type을 반환해야 하며, 아래 파일 타입 가이드라인을 따라야 합니다:

• 사용자 에이전트는 type을 소문자 ASCII 인코딩 문자열로 반환해야 하며, 해당 문자열을 바이트 시퀀스로 변환했을 때 파싱 가능한 MIME 타입이어야 합니다. 타입을 판단할 수 없는 경우에는 빈 문자열(0 바이트)을 반환합니다.

• 파일 타입이 text/plain인 경우, 사용자 에이전트는 미디어 타입의 parameters 딕셔너리 부분에 charset 파라미터를 추가하면 안 됩니다 [MIMESNIFF].

• 사용자 에이전트는 인코딩의 휴리스틱 결정(통계적 방법 포함)을 시도하면 안 됩니다.

[Exposed=(Window,Worker), Serializable]
interface File : Blob {
  constructor(sequence<BlobPart> fileBits,
              USVString fileName,
              optional FilePropertyBag options = {});
  readonly attribute DOMString name;
  readonly attribute long long lastModified;
};

dictionary FilePropertyBag : BlobPropertyBag {
  long long lastModified;
};

File 객체는 직렬화 가능한 객체입니다. 직렬화 단계는 value와 serialized가 주어졌을 때 다음과 같습니다:

1. serialized.[[SnapshotState]]를 value의 스냅샷 상태로 설정합니다.

2. serialized.[[ByteSequence]]를 value의 기저 바이트 시퀀스로 설정합니다.

3. serialized.[[Name]]을 value의 name 속성값으로 설정합니다.

4. serialized.[[LastModified]]를 value의 lastModified 속성값으로 설정합니다.

역직렬화 단계는 value와 serialized가 주어졌을 때 다음과 같습니다:

1. value의 스냅샷 상태를 serialized.[[SnapshotState]]로 설정합니다.

2. value의 기저 바이트 시퀀스를 serialized.[[ByteSequence]]로 설정합니다.

3. value의 name 속성값을 serialized.[[Name]]으로 초기화합니다.

4. value의 lastModified 속성값을 serialized.[[LastModified]]으로 초기화합니다.

4.1. 생성자

4.1.1. 생성자 매개변수

File() 생성자는 아래 매개변수로 호출할 수 있습니다:

fileBits sequence

다음 요소들을 아무 순서로든 여러 개 받을 수 있습니다:

• BufferSource 요소.

• Blob 요소(여기에는 File 요소도 포함).

• USVString 요소.

fileName 매개변수

USVString 타입의 파일 이름을 나타내는 매개변수입니다; 이 생성자 매개변수에 대한 규범 조건은 § 4.1 생성자에서 확인할 수 있습니다.

선택적 FilePropertyBag 딕셔너리

BlobPropertyBag의 멤버 외에 추가로 한 가지 멤버를 받을 수 있습니다:

• 선택적 lastModified 멤버, long long이어야 하며; 이 멤버에 대한 규범 조건은 § 4.1 생성자에서 제공됩니다.

4.2. 속성

name, 타입 DOMString, 읽기 전용

파일의 이름. 가져올 때, 문자열로 파일 이름을 반환해야 합니다. OS 파일 시스템마다 다양한 파일명 규칙이 있으나, 여기서는 경로 정보 없이 파일 이름만을 반환합니다. 정보가 제공되지 않으면 빈 문자열을 반환해야 합니다. File 객체가 생성자를 통해 만들어진 경우, 이 속성에 대한 추가 규범 조건은 § 4.1 생성자에서 확인할 수 있습니다.

lastModified, 타입 long long, 읽기 전용

파일의 마지막 수정 날짜. 정보가 제공될 경우, long long 타입으로 Unix Epoch 이후 경과한 밀리초 단위의 마지막 수정 시간을 반환해야 합니다. 날짜와 시간을 알 수 없다면, long long 타입의 현재 날짜와 시간을 반환해야 하며, 이는 Unix Epoch 이후 경과한 밀리초 단위입니다; 즉 Date.now()와 같습니다 [ECMA-262]. File 객체가 생성자를 통해 만들어진 경우, 이 속성에 대한 추가 규범 조건은 § 4.1 생성자에서 확인할 수 있습니다.

File 인터페이스는 FileList 타입의 속성을 제공하는 객체에서 사용할 수 있습니다; 이러한 객체는 HTML [HTML]에서 정의됩니다. File 인터페이스는 Blob을 상속하며, 불변(immutable)입니다. 따라서 파일 데이터를 읽기 작업이 시작된 시점에 메모리로 읽을 수 있습니다. 사용자 에이전트는 읽기 시점에 파일이 존재하지 않으면 오류로 처리해야 하며, Web Worker [Workers]에서 FileReaderSync를 사용할 경우 NotFoundError 예외를 발생시키고, error 이벤트를 발생시킬 때 error 속성은 NotFoundError를 반환해야 합니다.

var file = document.getElementById("filePicker").files[0];
var date = new Date(file.lastModified);
println("You selected the file " + file.name + " which was modified on " + date.toDateString() + ".");

...

// 특정 수정 날짜로 파일 생성

var d = new Date(2013, 12, 5, 16, 23, 45, 600);
var generatedFile = new File(["Rough Draft ...."], "Draft1.txt", {type: "text/plain", lastModified: d})

...

5. FileList 인터페이스

참고: FileList 인터페이스는 "위험" 상태로 간주해야 합니다. 웹 플랫폼의 일반적인 경향은 이러한 인터페이스를 ECMAScript [ECMA-262]의 Array 플랫폼 객체로 대체하는 방향입니다. 특히 filelist.item(0)와 같은 문법은 위험하며, FileList의 대부분의 다른 프로그래밍적 사용은 결국 Array 타입으로의 이전에 영향을 받지 않을 것으로 보입니다.

이 인터페이스는 File 객체들의 목록입니다.

[Exposed=(Window,Worker), Serializable]
interface FileList {
  getter File? item(unsigned long index);
  readonly attribute unsigned long length;
};

FileList 객체는 직렬화 가능한 객체입니다. 직렬화 단계는 value와 serialized가 주어졌을 때 다음과 같습니다:

1. serialized.[[Files]]를 빈 리스트로 설정합니다.

2. value의 각 file에 대해, file의 하위 직렬화를 serialized.[[Files]]에 추가합니다.

역직렬화 단계는 serialized, value가 주어졌을 때 다음과 같습니다:

1. 각 serialized.[[Files]]의 file에 대해, file의 하위 역직렬화를 value에 추가합니다.

// uploadData는 form 요소입니다
// fileChooser는 'file' 타입의 input 요소입니다
var file = document.forms['uploadData']['fileChooser'].files[0];

// 대안 문법은 다음과 같을 수 있습니다
// var file = document.forms['uploadData']['fileChooser'].files.item(0);

if(file)
{
  // 파일 작업 수행
}

5.1. 속성

length, 타입 unsigned long, 읽기 전용

FileList 객체의 파일 개수를 반환해야 합니다. 파일이 없으면 이 속성은 0을 반환해야 합니다.

5.2. 메서드 및 매개변수

item(index)

index번째 File 객체를 FileList에서 반환해야 합니다. index번째 File 객체가 없으면 FileList에서 null을 반환해야 합니다.

index는 사용자 에이전트가 File 객체의 위치 값으로 처리해야 하며, 0이 첫 번째 파일을 나타냅니다. 지원되는 속성 인덱스는 0에서 File 객체 수 - 1까지의 숫자입니다. 해당 File 객체가 없다면 지원되는 속성 인덱스는 없습니다.

참고: HTMLInputElement 인터페이스는 FileList 타입의 읽기 전용 속성을 가지며, 이는 위 예시에서 접근되는 것입니다. FileList 타입의 읽기 전용 속성을 가지는 다른 인터페이스로는 DataTransfer 인터페이스가 있습니다.

6. 데이터 읽기

6.1. 파일 읽기 태스크 소스

이 명세는 파일 읽기 태스크 소스라 불리는 새로운 일반 태스크 소스를 정의하며, 이는 이 명세에서 큐잉되는 모든 태스크 중 Blob 및 File 객체와 연관된 바이트 시퀀스 읽기에 사용됩니다. 이는 비동기적으로 바이너리 데이터를 읽는 기능을 트리거하는 상황에 사용됩니다.

6.2. FileReader API

[Exposed=(Window,Worker)]
interface FileReader: EventTarget {
  constructor();
  // 비동기 읽기 메서드
  undefined readAsArrayBuffer(Blob blob);
  undefined readAsBinaryString(Blob blob);
  undefined readAsText(Blob blob, optional DOMString encoding);
  undefined readAsDataURL(Blob blob);

  undefined abort();

  // 상태값
  const unsigned short EMPTY = 0;
  const unsigned short LOADING = 1;
  const unsigned short DONE = 2;

  readonly attribute unsigned short readyState;

  // File 또는 Blob 데이터
  readonly attribute (DOMString or ArrayBuffer)? result;

  readonly attribute DOMException? error;

  // 이벤트 핸들러 content attribute
  attribute EventHandler onloadstart;
  attribute EventHandler onprogress;
  attribute EventHandler onload;
  attribute EventHandler onabort;
  attribute EventHandler onerror;
  attribute EventHandler onloadend;
};

FileReader 객체는 state라는 값을 가지며, "empty", "loading", "done" 중 하나입니다. 초기값은 "empty"입니다.

FileReader 객체는 result(null, DOMString 또는 ArrayBuffer)를 가지며, 초기값은 null입니다.

FileReader 객체는 error(null 또는 DOMException) 값을 가지며, 초기값은 null입니다.

FileReader() 생성자가 호출될 때, 새로운 FileReader 객체를 반환해야 합니다.

readyState 속성의 getter는, 호출 시 this의 state에 따라 아래 단계로 분기합니다:

"empty"

EMPTY 반환

"loading"

LOADING 반환

"done"

DONE 반환

result 속성의 getter는, 호출 시 this의 result를 반환해야 합니다.

error 속성의 getter는, 호출 시 this의 error 값을 반환해야 합니다.

6.2.1. 이벤트 핸들러 콘텐츠 속성

다음은 이벤트 핸들러 콘텐츠 속성(및 해당 이벤트 핸들러 이벤트 타입)으로, 사용자 에이전트가 FileReader 에 대해 DOM 속성으로 지원해야 합니다:

6.2.2. FileReader 상태

6.2.3. 파일 또는 Blob 읽기

FileReader 인터페이스는 여러 비동기 읽기 메서드—​readAsArrayBuffer(), readAsBinaryString(), readAsText() 및 readAsDataURL()를 제공합니다. 이 메서드들은 파일을 메모리로 읽습니다.

참고: 동일한 FileReader 객체에서 여러 개의 읽기 메서드를 동시에 호출하면, 사용자 에이전트는 InvalidStateError를 throw합니다. readyState 가 LOADING일 때 추가적으로 호출되는 읽기 메서드에서 예외가 발생합니다.

(FileReaderSync 는 여러 동기 읽기 메서드를 제공합니다. FileReader 와 FileReaderSync의 동기 및 비동기 읽기 메서드를 통칭하여 읽기 메서드라고 부릅니다.)

6.2.3.1. readAsDataURL() 메서드

readAsDataURL(blob) 메서드는 호출 시 blob에 대해 DataURL을 사용하여 읽기 작업을 시작해야 합니다.

6.2.3.2. readAsText() 메서드

readAsText(blob, encoding) 메서드는 호출 시 blob에 대해 Text 및 encoding을 사용하여 읽기 작업을 시작해야 합니다.

6.2.3.3. readAsArrayBuffer()

readAsArrayBuffer(blob) 메서드는 호출 시 blob에 대해 ArrayBuffer를 사용하여 읽기 작업을 시작해야 합니다.

6.2.3.4. readAsBinaryString() 메서드

readAsBinaryString(blob) 메서드는 호출 시 blob에 대해 BinaryString을 사용하여 읽기 작업을 시작해야 합니다.

참고: readAsArrayBuffer() 사용을 readAsBinaryString()보다 우선적으로 권장합니다. readAsBinaryString()는 하위 호환성을 위해 제공됩니다.

6.2.3.5. abort() 메서드

abort() 메서드가 호출되면, 사용자 에이전트는 아래 단계를 실행해야 합니다:

1. this의 state가 "empty"이거나 this의 state가 "done"이면 this의 result를 null로 설정하고 이 알고리즘을 종료합니다.

2. this의 state가 "loading"이면 this의 state를 "done"으로, this의 result를 null로 설정합니다.

3. 태스크가 this에서 파일 읽기 태스크 소스의 관련 태스크 큐에 있다면, 해당 태스크를 태스크 큐에서 제거합니다.

4. 처리 중인 읽기 메서드 알고리즘을 종료합니다.

5. progress 이벤트 abort를 this에 발생시킵니다.

6. this의 state가 "loading"이 아니면, progress 이벤트 loadend를 this에 발생시킵니다.

6.3. 데이터 패키징

6.4. 이벤트

FileReader 객체는 이 명세의 모든 이벤트에 대해 이벤트 타겟이어야 합니다.

이 명세에서 진행 이벤트를 발생시키다 e(어떤 ProgressEvent e를 특정 FileReader reader에 발생시킨다는 의미임)라고 할 때, 다음 사항이 규범적입니다:

• 진행 이벤트 e는 버블링되지 않습니다. e.bubbles는 반드시 false이어야 합니다 [DOM]

• 진행 이벤트 e는 취소될 수 없습니다. e.cancelable는 반드시 false이어야 합니다 [DOM]

6.4.1. 이벤트 요약

다음은 발생되는 FileReader 객체의 이벤트입니다.

6.4.2. 이벤트 불변성 요약

이 섹션은 참고용입니다.

다음은 이 명세의 비동기 이벤트 발생에 대한 읽기 메서드에 적용되는 불변성입니다:

1. loadstart 가 발생한 후에는, 해당 읽기가 완료될 때 loadend 가 반드시 발생합니다. 단, 아래 조건 중 하나라도 참이면 예외입니다:

   • 읽기 메서드가 abort() 로 취소되고, 새로운 읽기 메서드가 호출된 경우

   • load 이벤트 핸들러 함수에서 새로운 읽기를 시작하는 경우

   • error 이벤트 핸들러 함수에서 새로운 읽기를 시작하는 경우

   참고: loadstart 와 loadend 는 1:1로 대응되지 않습니다.

   이 예시는 "읽기 체이닝"을 보여줍니다: 이벤트 핸들러 내에서 다른 읽기를 시작하는 경우, "첫 번째" 읽기가 계속 처리되는 동안입니다.

   // 이런 식의 코드에서...
   reader.readAsText(file);
   reader.onload = function(){reader.readAsText(alternateFile);}
   
   .....
   
   //... 첫 번째 읽기에 대해 loadend 이벤트는 발생하지 않아야 함
   
   reader.readAsText(file);
   reader.abort();
   reader.onabort = function(){reader.readAsText(updatedFile);}
   
   //... 첫 번째 읽기에 대해 loadend 이벤트는 발생하지 않아야 함
   

2. progress 이벤트는 blob이 완전히 메모리에 읽힐 때 한 번 발생합니다.

3. progress 이벤트는 loadstart 이전에는 발생하지 않습니다.

4. 다음 중 하나라도 (abort, load, 그리고 error)가 발생한 후에는 progress 이벤트가 발생하지 않습니다. 하나의 읽기에 대해 위 세 이벤트 중 최대 한 번만 발생합니다.

5. abort, load, 또는 error 이벤트는 loadend 이후에는 발생하지 않습니다.

6.5. 스레드에서 읽기

웹 워커(Web Workers)는 동기 File 또는 Blob 읽기 API 사용을 허용합니다. 스레드에서의 이러한 읽기는 메인 스레드를 차단하지 않기 때문입니다. 이 섹션에서는 워커 내에서 사용할 수 있는 동기 API를 정의합니다 [[Web Workers]]. 워커는 비동기 API(FileReader 객체) 와 동기 API(FileReaderSync 객체) 모두 사용할 수 있습니다.

6.5.1. FileReaderSync API

이 인터페이스는 동기적으로 읽기 위한 메서드를 제공하며, File 또는 Blob 객체를 메모리로 읽어들입니다.

[Exposed=(DedicatedWorker,SharedWorker)]
interface FileReaderSync {
  constructor();
  // 동기적으로 문자열 반환

  ArrayBuffer readAsArrayBuffer(Blob blob);
  DOMString readAsBinaryString(Blob blob);
  DOMString readAsText(Blob blob, optional DOMString encoding);
  DOMString readAsDataURL(Blob blob);
};

6.5.1.1. 생성자

FileReaderSync() 생성자가 호출될 때, 사용자 에이전트는 새로운 FileReaderSync 객체를 반환해야 합니다.

6.5.1.2. readAsText()

readAsText(blob, encoding) 메서드는 호출 시 다음 단계를 실행해야 합니다:

1. stream을 blob에 대해 get stream을 실행한 결과로 설정합니다.

2. reader를 stream에서 reader 얻기의 결과로 설정합니다.

3. promise를 reader와 함께 stream에서 모든 바이트 읽기의 결과로 설정합니다.

4. promise가 fulfilled 또는 rejected될 때까지 기다립니다.

5. promise가 바이트 시퀀스 bytes로 fulfilled된 경우:

   1. bytes, Text, blob의 type, encoding을 주어 패키지 데이터의 결과를 반환합니다.

6. promise의 rejection reason을 throw합니다.

6.5.1.3. readAsDataURL() 메서드

readAsDataURL(blob) 메서드는 호출 시 다음 단계를 실행해야 합니다:

1. stream을 blob에 대해 get stream을 실행한 결과로 설정합니다.

2. reader를 stream에서 reader 얻기의 결과로 설정합니다.

3. promise를 reader와 함께 stream에서 모든 바이트 읽기의 결과로 설정합니다.

4. promise가 fulfilled 또는 rejected될 때까지 기다립니다.

5. promise가 바이트 시퀀스 bytes로 fulfilled된 경우:

   1. bytes, DataURL, blob의 type을 주어 패키지 데이터의 결과를 반환합니다.

6. promise의 rejection reason을 throw합니다.

6.5.1.4. readAsArrayBuffer() 메서드

readAsArrayBuffer(blob) 메서드는 호출 시 다음 단계를 실행해야 합니다:

1. stream을 blob에 대해 get stream을 실행한 결과로 설정합니다.

2. reader를 stream에서 reader 얻기의 결과로 설정합니다.

3. promise를 reader와 함께 stream에서 모든 바이트 읽기의 결과로 설정합니다.

4. promise가 fulfilled 또는 rejected될 때까지 기다립니다.

5. promise가 바이트 시퀀스 bytes로 fulfilled된 경우:

   1. bytes, ArrayBuffer, blob의 type을 주어 패키지 데이터의 결과를 반환합니다.

6. promise의 rejection reason을 throw합니다.

6.5.1.5. readAsBinaryString() 메서드

readAsBinaryString(blob) 메서드는 호출 시 다음 단계를 실행해야 합니다:

1. stream을 blob에 대해 get stream을 실행한 결과로 설정합니다.

2. reader를 stream에서 reader 얻기의 결과로 설정합니다.

3. promise를 reader와 함께 stream에서 모든 바이트 읽기의 결과로 설정합니다.

4. promise가 fulfilled 또는 rejected될 때까지 기다립니다.

5. promise가 바이트 시퀀스 bytes로 fulfilled된 경우:

   1. bytes, BinaryString, blob의 type을 주어 패키지 데이터의 결과를 반환합니다.

6. promise의 rejection reason을 throw합니다.

참고: readAsArrayBuffer() 사용을 readAsBinaryString()보다 권장합니다. readAsBinaryString()는 하위 호환성을 위해 제공됩니다.

7. 오류 및 예외

파일 읽기 오류는 기본 파일 시스템에서 파일을 읽을 때 발생할 수 있습니다. 아래의 잠재적 오류 조건 목록은 참고용입니다.

• File 또는 Blob 에 접근 시, 비동기 읽기 메서드 또는 동기 읽기 메서드가 호출되는 시점에 해당 객체가 존재하지 않을 수 있습니다. 이는 참조를 얻은 뒤 파일이 이동 또는 삭제된 경우(예: 다른 애플리케이션에서 동시에 수정)일 수 있습니다. NotFoundError를 참고하세요.

• File 또는 Blob가 읽을 수 없는 경우가 있습니다. 이는 File 또는 Blob에 대한 참조를 얻은 후 권한 문제가 발생한 경우(예: 다른 애플리케이션에서 동시 잠금)일 수 있습니다. 또한 스냅샷 상태가 변경되었을 수 있습니다. NotReadableError를 참고하세요.

• 사용자 에이전트는 일부 파일이 웹 애플리케이션에서 사용하기에 안전하지 않다고 판단할 수 있습니다. 파일이 디스크에서 원래 선택 이후 변경될 경우, 읽기 오류가 발생할 수 있습니다. 또한 일부 파일 및 디렉터리 구조는 기본 파일 시스템에서 제한되어 있을 수 있으며, 이로 인해 읽기 시도가 보안 위반으로 간주될 수 있습니다. § 9 보안 및 프라이버시 고려사항과 SecurityError를 참고하세요.

7.1. 예외 발생 또는 오류 반환

이 섹션은 규범적입니다.

File 또는 Blob를 읽을 때 오류 조건이 발생할 수 있습니다.

읽기 작업은 File 또는 Blob를 읽는 중 오류 조건으로 종료될 수 있습니다; get stream 알고리즘이 실패하게 하는 특정 오류 조건을 실패 원인이라고 합니다. 실패 원인은 NotFound, UnsafeFile, TooManyReads, SnapshotState, 또는 FileLock 중 하나입니다.

동기 읽기 메서드는 아래 표의 타입에 따라 예외를 throw합니다. 해당 오류가 특정 실패 원인에 의해 발생한 경우입니다.

비동기 읽기 메서드는 error 속성을 사용하며, FileReader 객체의 이 속성은 아래 표에서 가장 적합한 타입의 DOMException 객체를 반환해야 하며, 오류가 특정 실패 원인에 의해 발생한 경우입니다. 그렇지 않으면 null을 반환해야 합니다.

8. Blob 및 MediaSource 참조를 위한 URL

이 섹션에서는 Blob 및 MediaSource 객체를 참조하기 위해 사용되는 URL 스킴에 대해 정의합니다.

8.1. 소개

이 섹션은 참고용입니다.

Blob(혹은 객체) URL은 blob:http://example.com/550e8400-e29b-41d4-a716-446655440000과 같은 형태의 URL입니다. 이를 통해 Blob 및 MediaSource 를 URL로만 설계된 다른 API와 연동할 수 있습니다. 예를 들어 img 요소 등에서 사용할 수 있습니다. Blob URL은 로컬에서 생성된 데이터를 탐색하거나 다운로드를 트리거하는 데에도 사용할 수 있습니다.

이 목적을 위해 URL 인터페이스에 두 가지 정적 메서드가 노출됩니다: createObjectURL(obj) 와 revokeObjectURL(url)입니다. 첫 번째 메서드는 URL에서 Blob로의 매핑을 생성하며, 두 번째 메서드는 해당 매핑을 해제합니다. 매핑이 존재하는 동안 Blob은 가비지 컬렉션되지 않으므로, 더 이상 필요하지 않을 경우 URL을 해제(revoke)해야 합니다. URL을 생성한 글로벌 객체가 사라질 때 모든 URL도 해제됩니다.

8.2. 모델

각 사용자 에이전트는 blob URL 저장소를 유지해야 합니다. blob URL 저장소는 맵(map)이며, 키는 유효한 URL 문자열이고, 값은 blob URL 엔트리입니다.

blob URL 엔트리는 객체(object)(타입은 Blob 또는 MediaSource)와, environment(환경 설정 객체)로 구성됩니다.

참고: 명세들은 blob 객체 획득 알고리즘을 사용해 blob URL 엔트리의 객체(object)에 접근해야 합니다.

blob URL 저장소의 키(blob URL이라고도 함)는 유효한 URL 문자열로, 파싱하면 URL이 되며, scheme이 "blob"이고, host가 비어 있으며, path는 하나의 요소로, 그 요소도 유효한 URL 문자열입니다.

8.3. blob URL의 역참조 모델

blob URL의 파싱 및 가져오기 모델에 대한 추가 요구사항은 [URL] 및 [Fetch] 명세에 정의되어 있습니다.

8.3.1. blob URL의 오리진

이 섹션은 참고용입니다.

blob URL의 오리진은 해당 URL을 생성한 환경의 오리진과 항상 동일합니다. 단, URL이 아직 해제되지 않은 경우에 한합니다. 이는 [URL] 명세가 URL 파싱 시 blob URL 저장소에서 조회해 해당 엔트리를 사용하여 올바른 오리진을 반환하도록 구현되기 때문입니다.

만약 URL이 해제된 경우에도 오리진의 직렬화 값은 blob URL을 생성한 환경의 오리진 직렬화와 동일하게 남아 있습니다. 다만, 불투명 오리진(opaque origin)의 경우 오리진 자체는 다를 수 있습니다. 하지만 해제된 blob URL은 더 이상 해석/가져올 수 없으므로 이 차이는 관찰할 수 없습니다.

8.3.2. blob URL의 접근 제한

blob URL은 해당 storage key가 blob URL을 생성한 환경의 storage key와 일치하는 환경에서만 가져올 수 있습니다. blob URL 탐색(navigation)은 이 제한을 받지 않습니다.

8.3.3. blob URL의 생명주기

이 명세는 문서 언로드 시 정리 단계를 다음 단계로 확장합니다:

1. environment를 해당 Document의 관련 설정 객체로 설정한다.

2. store를 사용자 에이전트의 blob URL 저장소로 설정한다;

3. store에서 값의 environment가 environment와 같은 모든 엔트리를 제거한다.

워커가 언로드될 때도 유사한 후크가 필요합니다.

8.4. blob URL 생성 및 해제

Blob URL은 URL 객체의 정적 메서드를 통해 생성 및 해제됩니다. blob URL을 해제(revoke)하면 blob URL과 그가 참조하는 리소스의 연결이 끊어지고, 해제 후 역참조 시도 시 사용자 에이전트는 네트워크 오류가 발생한 것처럼 동작해야 합니다. 이 섹션은 URL 명세 [URL]에 대한 보충 인터페이스를 설명하며, blob URL의 생성 및 해제 방법을 제시합니다.

[Exposed=(Window,DedicatedWorker,SharedWorker)]
partial interface URL {
  static DOMString createObjectURL((Blob or MediaSource) obj);
  static undefined revokeObjectURL(DOMString url);
};

myurl = window1.URL.createObjectURL(myblob);
window2.URL.revokeObjectURL(myurl);

8.4.1. blob URL 생성 및 해제 예시

Blob URL은 가져오기(fetch)에 사용되는 문자열이며, document에서 URL.createObjectURL()을 통해 생성된 이후 § 8.3.3 blob URL의 생명주기 참고.

이 섹션에서는 blob URL 생성 및 해제의 샘플 사용법을 설명합니다.

url = URL.createObjectURL(blob);
img1.src = url;
img2.src = url;

var blobURLref = URL.createObjectURL(file);
img1 = new Image();
img2 = new Image();

// 아래 두 할당 모두 정상적으로 동작함
img1.src = blobURLref;
img2.src = blobURLref;

// ... body 로드 이후
// 두 이미지가 모두 로드됐는지 확인
if(img1.complete && img2.complete) {
  // 이후 참조는 예외를 발생시켜야 함
  URL.revokeObjectURL(blobURLref);
} else {
  msg("이미지를 미리 볼 수 없습니다!");
  // 문자열 기반 참조 해제
  URL.revokeObjectURL(blobURLref);
}

위 예시에서는 하나의 blob URL에 여러 참조가 가능하며, 웹 개발자는 두 이미지 객체가 모두 로드된 후 blob URL 문자열을 해제합니다. blob URL의 사용 횟수를 제한하지 않는 것은 더 유연하지만, 누수 가능성을 높이므로, 개발자는 반드시 URL.revokeObjectURL() 호출을 짝지어 사용해야 합니다.

9. 보안 및 개인정보 보호 고려사항

이 섹션은 참고용입니다.

이 명세는 웹 콘텐츠가 기본 파일 시스템에서 파일을 읽을 수 있도록 허용하며, 파일을 고유 식별자를 통해 접근할 수 있게 하고 있기 때문에 특정 보안 고려사항의 대상이 됩니다. 이 명세는 주로 사용자가 HTML 폼의 <input type="file"/> 요소와 상호작용한다고 가정하며 [HTML], FileReader 객체로 읽는 모든 파일은 반드시 사용자가 먼저 선택했어야 합니다. 중요한 보안 고려사항에는 악의적인 파일 선택 공격(선택 루프) 방지, 시스템 민감 파일 접근 방지, 선택 이후 디스크 상의 파일 변경 방지 등이 포함됩니다.

선택 루프 방지

파일 선택 과정에서 사용자는 <input type="file"/>가 연결된 파일 선택기가 반복적으로 나타나며("반드시 선택해야 하는" 루프에서 파일 선택이 이뤄지기 전까지 닫을 수 없는 상황) 사용자 에이전트는 FileList 객체의 크기를 0으로 만들어 파일 접근을 차단할 수 있습니다.

시스템 민감 파일

(예: /usr/bin의 파일, 비밀번호 파일, 기타 운영체제 실행 파일) 보통 웹 콘텐츠에 노출되어서는 안 되며, blob URL을 통해 접근해서도 안 됩니다. 사용자 에이전트는 동기 읽기 메서드에서는 throw로 SecurityError 예외를 발생시키거나, 비동기 읽기의 경우 SecurityError 예외를 반환할 수 있습니다.

이 섹션은 임시이며, 이후 드래프트에서 더 많은 보안 데이터가 추가될 수 있습니다.

10. 요구사항 및 활용 사례

이 섹션에서는 이 API의 요구사항과 활용 사례를 다룹니다. 이 버전의 API가 모든 활용 사례를 만족시키는 것은 아니며, 이후 버전에서 추가적으로 다룰 수 있습니다.

• 사용자가 권한을 부여한 경우, 사용자 에이전트는 로컬 파일에서 데이터를 직접 읽고 파싱하는 기능을 프로그래밍적으로 제공해야 합니다.

  가사 뷰어. 사용자는 자신의 노래 가사를 plist 파일에서 읽고 싶어함. 사용자는 plist 파일을 찾아 선택. 파일이 열리고 읽혀지고 파싱되어, 웹 애플리케이션 내에서 정렬 가능한 목록으로 사용자에게 보여짐. 사용자는 노래를 선택해 가사를 가져올 수 있음. 사용자는 "파일 찾아보기" 다이얼로그를 이용함.

• 데이터는 나중에 사용할 수 있도록 로컬에 저장할 수 있어야 하며, 이는 웹 애플리케이션의 오프라인 데이터 접근에 유용합니다.

  캘린더 앱. 사용자의 회사에 캘린더가 있음. 사용자는 자신의 로컬 이벤트를 회사 캘린더에 "바쁨" 슬롯으로 동기화하고 싶지만, 개인 정보는 노출되지 않기를 원함. 사용자는 파일을 찾아 선택. text/calendar 파일이 브라우저 내에서 파싱되어, 사용자가 두 파일을 하나의 캘린더 뷰로 병합 가능. 이후 "다른 이름으로 저장" 등을 통해 통합된 캘린더 파일을 로컬에 저장할 수 있음. 통합된 캘린더 파일을 서버의 캘린더 저장소에 비동기로 보낼 수도 있음.

• 사용자 에이전트는 특정 데이터와 파일 이름이 주어졌을 때, 로컬 파일을 프로그래밍적으로 저장할 수 있는 기능을 제공해야 합니다.

  참고: 이 명세는 다운로드를 트리거하는 명시적 API 호출은 제공하지 않지만, HTML5 명세에서 이를 다루고 있습니다. download 속성이 a 요소에 부여되면 다운로드가 시작되고, 지정된 이름으로 File 을 저장할 수 있습니다. 이 API와 download 속성을 함께 사용하면 웹 애플리케이션에서 파일을 생성하고 로컬에 저장할 수 있습니다.

  스프레드시트 앱. 사용자가 폼에 입력하여 데이터를 생성. 폼이 CSV(Comma Separated Variables) 출력을 생성해 사용자가 스프레드시트로 가져올 수 있음. "저장..." 기능 사용. 생성된 출력은 웹 기반 스프레드시트에 직접 통합할 수도 있고, 비동기로 업로드할 수도 있음.

• 사용자 에이전트는 파일로부터 데이터를 원격 서버로 효율적으로 전송할 수 있는 프로그래밍적 기능을 제공해야 하며, 이는 기존의 폼 기반 업로드보다 더 효율적이어야 합니다.

  비디오/사진 업로드 앱. 사용자는 대용량 파일을 선택해 업로드할 수 있으며, 서버로 "청크 전송" 방식으로 보낼 수 있음.

• 사용자 에이전트는 위 기능들을 노출하는 API를 스크립트에 제공해야 합니다. 파일 시스템과 상호작용이 발생할 때마다 UI로 사용자가 알림을 받아, 트랜잭션을 언제든 취소하거나 중단할 수 있어야 합니다. 파일 선택이 있을 때마다 사용자에게 알림이 제공되며, 사용자는 이를 취소할 수 있습니다. 이러한 API의 호출은 사용자의 개입 없이 자동 실행되지 않습니다.

감사의 글

이 명세는 SVG 워킹 그룹에서 처음 개발되었습니다. Mark Baker와 Anne van Kesteren에게 피드백에 감사드립니다.

Robin Berjon, Jonas Sicking, Vsevolod Shmyroff에게 원본 명세 편집에 감사드립니다.

Olli Pettay, Nikunj Mehta, Garrett Smith, Aaron Boodman, Michael Nordman, Jian Li, Dmitry Titov, Ian Hickson, Darin Fisher, Sam Weinig, Adrian Bateman, Julian Reschke에게 특별히 감사드립니다.

W3C WebApps WG와 public-webapps@w3.org 리스트의 참가자들에게도 감사드립니다.