mozilla

Revision 474363 of File

  • Revision slug: Web/API/File
  • Revision title: File
  • Revision id: 474363
  • Created:
  • Creator: Jeremie
  • Is current revision? No
  • Comment

Revision Content

{{gecko_minversion_header("1.9")}}

Summary

The File interface provides information about -- and access to the contents of -- files. These are generally retrieved from a {{domxref("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.

The file reference can be saved when the form is submitted while the user is offline, so that the data can be retrieved and uploaded when the Internet connection is restored.

Properties

{{domxref("File.fileName")}} {{readonlyinline}} {{non-standard_inline}} {{obsolete_inline("7.0")}}
The name of the file referenced by the File object.
{{domxref("File.fileSize")}} {{readonlyinline}} {{non-standard_inline}} {{obsolete_inline("7.0")}}
The size of the referenced file in bytes.
{{domxref("File.lastModifiedDate")}} {{readonlyinline}} {{gecko_minversion_inline("15.0")}}
The last modified Date of the file referenced by the File object.
{{domxref("File.name")}} {{readonlyinline}} {{gecko_minversion_inline("1.9.2")}}
The name of the file referenced by the File object.

The File interface also inherite properties from the {{domxref("Blob")}} interface.

{{page("/en-US/docs/Web/API/Blob","Properties")}}

Methods

{{domxref("File.getAsBinary()")}} {{non-standard_inline}} {{obsolete_inline("7.0")}}
Returns a string containing the file's data in raw binary format.
{{domxref("File.getAsDataURL()")}} {{non-standard_inline}} {{obsolete_inline("7.0")}}
A string containing the file's data encoded as a data: URL.
{{domxref("File.getAsText()","File.getAsText(string encoding)")}} {{non-standard_inline}} {{obsolete_inline("7.0")}}
Returns the file's contents as a string in which the file's data is interpreted as text using a given encoding.

These methods are all non-standard. To read the contents of a file, you should use the {{domxref("FileReader")}} object. See Using files from web applications for examples.

{{method_obsolete_gecko("getAsBinary","7.0")}}

Returns a string containing the file's data in raw binary format.

Note: This method is obsolete; you should use the {{domxref("FileReader")}} method readAsBinaryString() or readAsArrayBuffer() instead.
DOMString getAsBinary();

Parameters

None.

Return value

A string containing the raw binary contents of the file.

{{method_obsolete_gecko("getAsDataURL","7.0")}}

Returns a string containing a data: URL that encodes the entire contents of the referenced file.

Note: This method is obsolete; you should use the {{domxref("FileReader")}} method readAsDataURL() instead.
DOMString getAsDataURL();

Parameters

None.

Return value

A string containing the file's data encoded as a data: URL.

{{method_obsolete_gecko("getAsText","7.0")}}

Returns the file's contents as a string in which the file's data is interpreted as text using a given encoding.

Note: This method is obsolete; you should use the {{domxref("FileReader")}} method readAsText() instead.
DOMString getAsText(
  in DOMString encoding
 );

Parameters

encoding
A string indicating the encoding to use for the returned data. If this string is empty, UTF-8 is assumed.

Return value

A string containing the file's data interpreted as text in the specified encoding.

Notes

Gecko notes

{{gecko_callout_heading("6.0")}}

Starting in Gecko 6.0 {{geckoRelease("6.0")}}, privileged code (such as extensions) can pass an {{interface("nsIFile")}} object to the DOM File constructor to specify the file to reference.

{{gecko_callout_heading("8.0")}}

Starting in Gecko 8.0 {{geckoRelease("8.0")}}, you can use new File to create File objects from XPCOM component code instead of having to instantiate the {{interface("nsIDOMFile")}} object directly.

Browser compatibility

For deeper details on compatibility that goes down to the method level, go to the articles for each interface.

{{CompatibilityTable}}
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
File 13 {{property_prefix("webkit")}} {{CompatNo}} {{CompatNo}} {{CompatNo}} {{CompatNo}}
{{domxref("FileReader")}} 6 {{property_prefix("webkit")}} 4.0 {{property_prefix("moz")}} 10 12 {{CompatNo}}
FileWriter 13 {{property_prefix("webkit")}} {{CompatNo}} {{CompatNo}} {{CompatNo}} {{CompatNo}}
FileSystem 13 {{property_prefix("webkit")}} {{CompatNo}} {{CompatNo}} {{CompatNo}} {{CompatNo}}
{{domxref("BlobBuilder")}} 8 {{property_prefix("webkit")}} {{CompatGeckoDesktop("6.0")}} 4.0 {{property_prefix("moz")}} 10 {{CompatNo}} {{CompatNo}}
BlobURL 8 {{property_prefix("webkit")}} 4.0 4.0{{property_prefix("moz")}} 10 {{CompatNo}} {{CompatNo}}
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
File {{CompatNo}} {{CompatNo}} {{CompatNo}} {{CompatNo}} {{CompatNo}}
{{domxref("FileReader")}} 3 {{CompatUnknown}} {{CompatNo}} 11.1 {{CompatNo}}
FileWriter {{CompatNo}} {{CompatNo}} {{CompatNo}} {{CompatNo}} {{CompatNo}}
FileSystem {{CompatNo}} {{CompatNo}} {{CompatNo}} {{CompatNo}} {{CompatNo}}
{{domxref("BlobBuilder")}} 3 {{CompatUnknown}} {{CompatNo}} {{CompatNo}} {{CompatNo}}
BlobURL 4 {{CompatUnknown}} {{CompatNo}} {{CompatNo}} {{CompatNo}}

Implementation notes

Gecko notes

Specifications

See also

{{ListSubpages}}

Revision Source

<div>
  {{gecko_minversion_header("1.9")}}</div>
<h2>Summary</h2>
<p>The <code>File</code> interface provides information about -- and access to the contents of -- files. These are generally retrieved from a {{domxref("FileList")}} 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-US/docs/DragDrop/DataTransfer" title="DragDrop/DataTransfer"><code>DataTransfer</code></a> object.</p>
<p>The file reference can be saved when the form is submitted while the user is offline, so that the data can be retrieved and uploaded when the Internet connection is restored.</p>
<h2 id="Properties" name="Properties">Properties</h2>
<dl>
  <dt>
    {{domxref("File.fileName")}} {{readonlyinline}} {{non-standard_inline}} {{obsolete_inline("7.0")}}</dt>
  <dd>
    The name of the file referenced by the <code>File</code> object.</dd>
  <dt>
    {{domxref("File.fileSize")}} {{readonlyinline}} {{non-standard_inline}} {{obsolete_inline("7.0")}}</dt>
  <dd>
    The size of the referenced file in bytes.</dd>
  <dt>
    {{domxref("File.lastModifiedDate")}} {{readonlyinline}} {{gecko_minversion_inline("15.0")}}</dt>
  <dd>
    The last modified <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date">Date</a></code> of the file referenced by the <code>File</code> object.</dd>
  <dt>
    {{domxref("File.name")}} {{readonlyinline}} {{gecko_minversion_inline("1.9.2")}}</dt>
  <dd>
    The name of the file referenced by the <code>File</code> object.</dd>
</dl>
<p>The <code>File</code> interface also inherite properties from the {{domxref("Blob")}} interface.</p>
<p>{{page("/en-US/docs/Web/API/Blob","Properties")}}</p>
<h2 id="Method_overview" name="Method_overview">Methods</h2>
<dl>
  <dt>
    {{domxref("File.getAsBinary()")}} {{non-standard_inline}} {{obsolete_inline("7.0")}}</dt>
  <dd>
    Returns a string containing the file's data in raw binary format.</dd>
  <dt>
    {{domxref("File.getAsDataURL()")}} {{non-standard_inline}} {{obsolete_inline("7.0")}}</dt>
  <dd>
    A string containing the file's data encoded as a <code>data:</code> URL.</dd>
  <dt>
    {{domxref("File.getAsText()","File.getAsText(string encoding)")}} {{non-standard_inline}} {{obsolete_inline("7.0")}}</dt>
  <dd>
    Returns the file's contents as a string in which the file's data is interpreted as text using a given encoding.</dd>
</dl>
<p>These methods are all non-standard. To read the contents of a file, you should use the {{domxref("FileReader")}} object. See <a href="/en-US/docs/Using_files_from_web_applications" title="Using files from web applications">Using files from web applications</a> for examples.</p>
<div>
  {{method_obsolete_gecko("getAsBinary","7.0")}}</div>
<p>Returns a string containing the file's data in raw binary format.</p>
<div class="note">
  <strong>Note:</strong> This method is obsolete; you should use the {{domxref("FileReader")}} method <a href="/en-US/docs/DOM/FileReader#readAsBinaryString()" title="DOM/FileReader#readAsBinaryString()"><code>readAsBinaryString()</code></a> or <a href="/en-US/docs/DOM/FileReader#readAsArrayBuffer()" title="DOM/FileReader#readAsArrayBuffer()"><code>readAsArrayBuffer()</code></a> instead.</div>
<pre>
DOMString getAsBinary();
</pre>
<h4 id="getAsBinary-Parameters" name="getAsBinary-Parameters">Parameters</h4>
<p>None.</p>
<h4 id="getAsBinary-Return_value" name="getAsBinary-Return_value">Return value</h4>
<p>A string containing the raw binary contents of the file.</p>
<div>
  {{method_obsolete_gecko("getAsDataURL","7.0")}}</div>
<p>Returns a string containing a <code>data:</code> URL that encodes the entire contents of the referenced file.</p>
<div class="note">
  <strong>Note:</strong> This method is obsolete; you should use the {{domxref("FileReader")}} method <a href="/en-US/docs/DOM/FileReader#readAsDataURL()" title="DOM/FileReader#readAsDataURL()"><code>readAsDataURL()</code> </a>instead.</div>
<pre>
DOMString getAsDataURL();
</pre>
<h4 id="getAsDataURL-Parameters" name="getAsDataURL-Parameters">Parameters</h4>
<p>None.</p>
<h4 id="getAsDataURL-Return_value" name="getAsDataURL-Return_value">Return value</h4>
<p>A string containing the file's data encoded as a <code>data:</code> URL.</p>
<div>
  {{method_obsolete_gecko("getAsText","7.0")}}</div>
<p>Returns the file's contents as a string in which the file's data is interpreted as text using a given encoding.</p>
<div class="note">
  <strong>Note:</strong> This method is obsolete; you should use the {{domxref("FileReader")}} method <a href="/en-US/docs/DOM/FileReader#readAsText()" title="DOM/FileReader#readAsText()"><code>readAsText()</code> </a>instead.</div>
<pre>
DOMString getAsText(
  in DOMString encoding
 );
</pre>
<h4 id="getAsText-Parameters" name="getAsText-Parameters">Parameters</h4>
<dl>
  <dt>
    <code>encoding</code></dt>
  <dd>
    A string indicating the encoding to use for the returned data. If this string is empty, UTF-8 is assumed.</dd>
</dl>
<h4 id="getAsText-Return_value" name="getAsText-Return_value">Return value</h4>
<p>A string containing the file's data interpreted as text in the specified <code>encoding</code>.</p>
<h2 id="Notes" name="Notes">Notes</h2>
<h3 id="Gecko_notes" name="Gecko_notes">Gecko notes</h3>
<div class="geckoVersionNote">
  <div>
    {{gecko_callout_heading("6.0")}}</div>
  <p>Starting in Gecko 6.0 {{geckoRelease("6.0")}}, privileged code (such as extensions) can pass an {{interface("nsIFile")}} object to the DOM <code>File</code> constructor to specify the file to reference.</p>
</div>
<div class="geckoVersionNote">
  <div>
    {{gecko_callout_heading("8.0")}}</div>
  <p>Starting in Gecko 8.0 {{geckoRelease("8.0")}}, you can use <code>new File</code> to create <code>File</code> objects from XPCOM component code instead of having to instantiate the {{interface("nsIDOMFile")}} object directly.</p>
</div>
<h2 id="Browser_compatibility" name="Browser_compatibility">Browser compatibility</h2>
<p>For deeper details on compatibility that goes down to the method level, go to the articles for each interface.</p>
<div>
  {{CompatibilityTable}}</div>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari (WebKit)</th>
      </tr>
      <tr>
        <td>File</td>
        <td>13 {{property_prefix("webkit")}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>{{domxref("FileReader")}}</td>
        <td>6 {{property_prefix("webkit")}}</td>
        <td>4.0 {{property_prefix("moz")}}</td>
        <td>10</td>
        <td>12</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>FileWriter</td>
        <td>13 {{property_prefix("webkit")}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>FileSystem</td>
        <td>13 {{property_prefix("webkit")}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>{{domxref("BlobBuilder")}}</td>
        <td>8 {{property_prefix("webkit")}}</td>
        <td>{{CompatGeckoDesktop("6.0")}} 4.0 {{property_prefix("moz")}}</td>
        <td>10</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>BlobURL</td>
        <td>8 {{property_prefix("webkit")}}</td>
        <td>4.0 4.0{{property_prefix("moz")}}</td>
        <td>10</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>File</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>{{domxref("FileReader")}}</td>
        <td>3</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatNo}}</td>
        <td>11.1</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>FileWriter</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>FileSystem</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>{{domxref("BlobBuilder")}}</td>
        <td>3</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
      <tr>
        <td>BlobURL</td>
        <td>4</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
        <td>{{CompatNo}}</td>
      </tr>
    </tbody>
  </table>
</div>
<h3 name="Specification">Implementation notes</h3>
<h4>Gecko notes</h4>
<ul>
  <li>In Gecko, you can use this API from chrome code. See <a href="/en-US/docs/Extensions/Using_the_DOM_File_API_in_chrome_code" title="Using the DOM File API in chrome code">Using the DOM File API in chrome code</a> for details.</li>
</ul>
<h2 id="Specification" name="Specification">Specifications</h2>
<ul>
  <li><a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#file-upload-state-%28type=file%29" title="http://www.whatwg.org/specs/web-apps/current-work/multipage/number-state.html#concept-input-type-file-selected">File upload state</a> (HTML 5 working draft)</li>
  <li><a href="http://www.w3.org/TR/FileAPI/" title="http://www.w3.org/TR/FileAPI/">File API</a></li>
</ul>
<h2 id="See_also" name="See_also">See also</h2>
<ul>
  <li><a href="/en-US/docs/Using_files_from_web_applications" title="Using files from web applications">Using files from web applications</a></li>
  <li><a href="/en-US/docs/Extensions/Using_the_DOM_File_API_in_chrome_code" title="Extensions/Using the DOM File API in chrome code">Using the DOM File API in chrome code</a></li>
  <li>{{domxref("FileReader")}}</li>
</ul>
<div>
  {{ListSubpages}}</div>
Revert to this revision