FileReader

  • Revision slug: DOM/FileReader
  • Revision title: FileReader
  • Revision id: 3685
  • Created:
  • Creator: GijsKruitbosch
  • Is current revision? No
  • Comment one or more formatting changes

Revision Content

{{ gecko_minversion_header("1.9.2") }}

The FileReader object lets web applications asynchronously read the contents of files stored on the user's computer, using File objects to specify the file to read. File objects may be obtained in one of two ways: from a FileList object returned as a result of a user selecting files using the input element, or from a drag and drop operation's DataTransfer object.

To create a FileReader, simply do the following:

reader = new FileReader();

See Using files from web applications for details.

Important note about input parameters

Note that the current implementation of this interface uses File objects to specify files; the specification uses Blob objects, which are not yet supported by Gecko. This will change in the future. To ensure that your code is compatible with future versions of Gecko, avoid using the non-standard methods offered by the File object.

Method overview

abort();
readAsBinaryString(file);
readAsDataURL(file);
readAsText(file, [encoding]);

State constants

Constant Value Description
EMPTY 0 No data has been loaded yet.
LOADING 1 Data is currently being loaded.
DONE 2 The entire read request has been completed.

Properties

Property Type Description
error FileError The error that occurred while reading the file. Read only.
readyState integer
Indicates the state of the FileReader. This will be one of the {{ anch("State constants") }}. Read only.
result string The file's contents. This property is only valid after the read operation is complete, and the format of the data depends on which of the methods was used to initiate the read operation. Read only.

Methods

abort()

Aborts the read operation. Upon return, the readyState will be DONE.

abort();
Parameters

None.

readAsBinaryString()

Starts reading the specified File's contents. When the read operation is finished, the readyState will become DONE, and the onloadend callback, if any, will be called. At that time, the result attribute contains the raw binary data from the file.

readAsBinaryString(
  filedata
);
Parameters
filedata
The DOM File from which to read.

readAsDataURL()

Starts reading the specified {{ interface("nsIDOMFile") }}'s contents. When the read operation is finished, the readyState will become DONE, and the onloadend callback, if any, will be called. At that time, the result attribute contains a data URL representing the file's data.

readAsDataURL(
  file
);
Parameters
file
The DOM file from which to read.

readAsText()

Starts reading the specified file's contents. When the read operation is finished, the readyState will become DONE, and the onloadend callback, if any, will be called. At that time, the result attribute contains the contents of the file as a text string.

readAsText(
  filedata,
  [encoding]
);
Parameters
filedata
The DOM file from which to read.
encoding
A string indicating the encoding to use for the returned data. By default, UTF-8 is assumed if this parameter isn't specified.

Event handlers

onabort
Called when the read operation is aborted.
onerror
Called when an error occurs.
onload
Called when the read operation is successfully completed.
onloadend
Called when the file read is completed, whether successful or not. This is called after either onload or onerror.
onloadstart
Called when reading the file's contents is about to begin.
onprogress
Called periodically while the file is being read.

See also

Revision Source

<p>{{ gecko_minversion_header("1.9.2") }}</p>
<p>The <code>FileReader</code> object lets web applications asynchronously read the contents of files stored on the user's computer, using File objects to specify the file to read. File objects may be obtained in one of two ways: from a <a class="internal" href="/en/DOM/FileList" title="En/DOM/FileList"><code>FileList</code></a> object returned as a result of a user selecting files using the <code>input</code> element, or from a drag and drop operation's <a href="/En/DragDrop/DataTransfer" title="En/DragDrop/DataTransfer"><code>DataTransfer</code></a> object.</p>
<p>To create a <code>FileReader</code>, simply do the following:</p>
<pre>reader = new FileReader();
</pre>
<p>See <a href="/en/Using_files_from_web_applications" title="en/Using files from web applications">Using files from web applications</a> for details.</p>
<h2>Important note about input parameters</h2>
<p>Note that the current implementation of this interface uses <a href="/en/DOM/File" title="en/DOM/File"><code>File</code></a> objects to specify files; the specification uses <code>Blob</code> objects, which are not yet supported by Gecko. This will change in the future. To ensure that your code is compatible with future versions of Gecko, avoid using the non-standard methods offered by the <a href="/en/DOM/File" title="en/DOM/File"><code>File</code></a> object.</p>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code><a href="/en/DOM/FileReader#abort()" title="en/DOM/FileReader#abort()">abort</a>();</code></td> </tr> <tr> <td><code><a href="/en/DOM/FileReader#readAsBinaryString()" title="en/DOM/FileReader#readAsBinaryString()">readAsBinaryString</a>(file);<br> </code></td> </tr> <tr> <td><code><a href="/en/DOM/FileReader#readAsDataURL()" title="en/DOM/FileReader#readAsDataURL()">readAsDataURL</a>(file);<br> </code></td> </tr> <tr> <td><code><a href="/en/DOM/FileReader#readAsText()" title="en/DOM/FileReader#readAsText()">readAsText</a>(file</code><code>, [encoding]</code><code>);<br> </code></td> </tr> </tbody>
</table><h2 name="Attributes">State constants</h2>
<table class="standard-table"> <tbody> <tr> <td class="header">Constant</td> <td class="header">Value</td> <td class="header">Description</td> </tr> <tr> <td><code>EMPTY</code></td> <td>0</td> <td>No data has been loaded yet.</td> </tr> <tr> <td><code>LOADING</code></td> <td>1</td> <td>Data is currently being loaded.</td> </tr> <tr> <td><code>DONE</code></td> <td>2</td> <td>The entire read request has been completed.</td> </tr> </tbody>
</table>
<h2 name="Attributes">Properties</h2>
<table class="standard-table"> <tbody> <tr> <td class="header">Property</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>error</code></td> <td><a href="/en/DOM/FileError" title="en/DOM/FileError"><code>FileError</code></a></td> <td>The error that occurred while reading the file. <strong>Read only</strong>.</td> </tr> <tr> <td><code>readyState</code></td> <td><code>integer<br> </code></td> <td>Indicates the state of the <code>FileReader</code>. This will be one of the {{ anch("State constants") }}. <strong>Read only</strong>.</td> </tr> <tr> <td><code>result</code></td> <td><code>string</code></td> <td>The file's contents. This property is only valid after the read operation is complete, and the format of the data depends on which of the methods was used to initiate the read operation. <strong>Read only</strong>.</td> </tr> </tbody>
</table>
<h2 name="Methods">Methods</h2>
<h3 name="getAsBinary.28.29">abort()</h3>
<p>Aborts the read operation. Upon return, the <code>readyState</code> will be <code>DONE</code>.</p>
<pre>abort();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h3 name="getAsBinary.28.29">readAsBinaryString()</h3>
<p>Starts reading the specified <a href="/en/DOM/File" title="en/DOM/File"><code>File</code></a>'s contents. When the read operation is finished, the <code>readyState</code> will become <code>DONE</code>, and the <code>onloadend</code> callback, if any, will be called. At that time, the <code>result</code> attribute contains the raw binary data from the file.</p>
<pre class="eval">readAsBinaryString(
  filedata
);
</pre>
<h6 name="Parameters">Parameters</h6>
<dl> <dt><code>filedata</code></dt> <dd>The DOM <a href="/en/DOM/File" title="en/DOM/File"><code>File</code></a> from which to read.</dd>
</dl>
<h3 name="getAsDataURL.28.29">readAsDataURL()</h3>
<p>Starts reading the specified {{ interface("nsIDOMFile") }}'s contents. When the read operation is finished, the <code>readyState</code> will become <code>DONE</code>, and the <code>onloadend</code> callback, if any, will be called. At that time, the <code>result</code> attribute contains a data URL representing the file's data.</p>
<pre class="eval">readAsDataURL(
  file
);</pre>
<h6 name="Parameters_2">Parameters</h6>
<dl> <dt><code>file<br> </code></dt> <dd>The DOM file from which to read.</dd>
</dl>
<h3 name="getAsText.28.29">readAsText()</h3>
<p>Starts reading the specified file's contents. When the read operation is finished, the <code>readyState</code> will become <code>DONE</code>, and the <code>onloadend</code> callback, if any, will be called. At that time, the <code>result</code> attribute contains the contents of the file as a text string.</p>
<pre class="eval">readAsText(
  filedata,
  [encoding]
);
</pre>
<h6 name="Parameters_3">Parameters</h6>
<dl> <dt> </dt><dt><code>filedata<br> </code></dt> <dd>The DOM file from which to read.</dd> <dt><code>encoding</code></dt> <dd>A string indicating the encoding to use for the returned data. By default, UTF-8 is assumed if this parameter isn't specified.</dd>
</dl>
<h2>Event handlers</h2>
<dl> <dt><code>onabort</code></dt> <dd>Called when the read operation is aborted.</dd> <dt><code>onerror</code></dt> <dd>Called when an error occurs.</dd> <dt><code>onload</code></dt> <dd>Called when the read operation is successfully completed.</dd> <dt><code>onloadend</code></dt> <dd>Called when the file read is completed, whether successful or not. This is called after either <code>onload</code> or <code>onerror</code>.</dd> <dt><code>onloadstart</code></dt> <dd>Called when reading the file's contents is about to begin.</dd> <dt><code>onprogress</code></dt> <dd>Called periodically while the file is being read.</dd>
</dl>
<h2>See also</h2>
<ul> <li><a href="/en/Using_files_from_web_applications" title="en/Using files from web applications">Using files from web applications</a></li> <li><a href="/en/DOM/File" title="en/DOM/File"><code>File</code></a></li> <li><a class=" external" href="http://dev.w3.org/2006/webapi/FileAPI/#filereader-interface" title="http://dev.w3.org/2006/webapi/FileAPI/#filereader-interface">The FileReader interface</a>  </li>
</ul>
Revert to this revision