path: root/files/zh-cn/mozilla/javascript_code_modules/downloads.jsm/index.html

---
title: Downloads.jsm
slug: Mozilla/JavaScript_code_modules/Downloads.jsm
tags:
  - Add-ons
  - Download Manager
  - Extensions
  - Files
  - JavaScript
  - Modules
  - NeedsTranslation
  - TopicStub
translation_of: Mozilla/JavaScript_code_modules/Downloads.jsm
---
<p>{{ gecko_minversion_header("26") }}</p>

<p>The <code>Downloads.jsm</code> JavaScript code module provides a single entry point to interact with the downloading capabilities of the platform, including starting new downloads, controlling ongoing downloads, and retrieving download-related configuration. To use it, you first need to import the code module into your JavaScript scope:</p>

<pre>Components.utils.import("resource://gre/modules/Downloads.jsm");
</pre>

<h2 id="Method_overview">Method overview</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <td><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a>&lt;<a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download">Download</a>&gt; <a href="#createDownload()">createDownload</a>(<a href="/en-US/docs/JavaScript/Reference/Global_Objects/Object" title="/en-US/docs/JavaScript/Reference/Global_Objects/Object">Object</a> aProperties);</code></td>
  </tr>
  <tr>
   <td><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a>&lt;void&gt; <a href="#fetch()">fetch</a>(aSource, aTarget, [optional] <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Object" title="/en-US/docs/JavaScript/Reference/Global_Objects/Object">Object</a> </code><code>aOptions);</code></td>
  </tr>
  <tr>
   <td><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a>&lt;<a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadList" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadList">DownloadList</a>&gt; <a href="#getList()">getList</a>(aType);</code></td>
  </tr>
  <tr>
   <td><code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a>&lt;<a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSummary" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSummary">DownloadSummary</a>&gt; <a href="#getSummary()">getSummary</a>(aType);</code></td>
  </tr>
 </tbody>
</table>

<h2 id="Constants">Constants</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <td class="header">Constant</td>
   <td class="header">Description</td>
  </tr>
  <tr>
   <td><code>PUBLIC</code></td>
   <td>Work on downloads that were not started from a private browsing window.</td>
  </tr>
  <tr>
   <td><code>PRIVATE</code></td>
   <td>Work on downloads that were started from a private browsing window.</td>
  </tr>
  <tr>
   <td><code>ALL</code></td>
   <td>Work on both <code>Downloads.PRIVATE</code> and <code>Downloads.PUBLIC</code> downloads.</td>
  </tr>
 </tbody>
</table>

<h2 id="Properties">Properties</h2>

<table class="standard-table" style="width: auto;">
 <tbody>
  <tr>
   <td class="header">Attribute</td>
   <td class="header">Type</td>
   <td class="header">Description</td>
  </tr>
  <tr>
   <td><code>Error</code> <span class="inlineIndicator readOnly readOnlyInline" title="This value may not be changed.">Read only </span></td>
   <td><a href="/en-US/docs/JavaScript/Guide/Working_with_Objects#Using_a_constructor_function" title="/en-US/docs/JavaScript/Guide/Working_with_Objects#Using_a_constructor_function"><code>Constructor</code></a></td>
   <td>Constructor for a <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadError" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadError"><code>DownloadError</code></a> object. When you catch an exception during a download, you can use this to verify if <code>ex instanceof Downloads.Error</code>, before reading the exception properties with the error details. Example (using <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Task.jsm" title="/en-US/docs/Mozilla/JavaScript_code_modules/Task.jsm"><code>Task.jsm</code></a>):
    <pre class="brush: js">
try {
  yield Downloads.fetch(sourceUri, targetFile);
} catch (ex if ex instanceof Downloads.Error &amp;&amp; ex.becauseTargetFailed) {
  console.log("Unable to write to the target file, ignoring the error.");
}</pre>
   </td>
  </tr>
 </tbody>
</table>

<h2 id="Methods">Methods</h2>

<h3 id="createDownload()">createDownload()</h3>

<p>Creates a new <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download"><code>Download</code></a> object.</p>

<pre>Promise&lt;Download&gt; createDownload(
  Object aProperties
);
</pre>

<h5 id="Parameters">Parameters</h5>

<dl>
 <dt><code>aProperties</code></dt>
 <dd>Provides the initial properties for the newly created download. This matches the serializable representation of a <code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download">Download</a></code> object. Some of the most common properties in this object include:
 <ul>
  <li><code>source</code>: String containing the URI for the download source. Alternatively, may be an {{Interface("nsIURI")}}, a <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSource" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSource"><code>DownloadSource</code></a> object, or an object with the following properties:
   <ul>
    <li><code>url</code>: String containing the URI for the download source.</li>
    <li><code>isPrivate</code>: {{optional_inline()}} Indicates whether the download originated from a private window. If omitted, the download is public.</li>
    <li><code>referrer</code>: {{optional_inline()}} String containing the referrer URI of the download source. Can be omitted or <code>null</code> if no referrer should be sent or the download source is not HTTP.</li>
   </ul>
  </li>
  <li><code>target</code>: String containing the path of the target file. Alternatively, may be an {{Interface("nsIFile")}}, a <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadTarget" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadTarget"><code>DownloadTarget</code></a> object, or an object with the following properties:
   <ul>
    <li><code>path</code>: String containing the path of the target file.</li>
   </ul>
  </li>
  <li><code>saver</code>: {{optional_inline()}} String representing the class of the download operation. If omitted, defaults to "copy". Alternatively, may be the serializable representation of a <code>DownloadSaver</code> object.</li>
 </ul>
 </dd>
</dl>

<h5 id="Promise_resolves_to">Promise resolves to</h5>

<p>The newly created <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download"><code>Download</code></a> object.</p>

<h3 id="fetch()">fetch()</h3>

<p>Downloads data from a remote network location to a local file.</p>

<p>This download method does not provide user interface or the ability to cancel or restart the download programmatically. For that, you should obtain a reference to a <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download"><code>Download</code></a> object using the <a href="#createDownload()" title="#createDownload()"><code>createDownload()</code></a> function.</p>

<p>Since the download cannot be restarted, any partially downloaded data will not be kept in case the download fails.</p>

<pre>Promise fetch(
  aSource,
  aTarget,
  Object aOptions
);
</pre>

<h5 id="Parameters_2">Parameters</h5>

<dl>
 <dt><code>aSource</code></dt>
 <dd>String containing the URI for the download source. Alternatively, may be an {{Interface("nsIURI")}} or a <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSource" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSource"><code>DownloadSource</code></a> object.</dd>
 <dt><code>aTarget</code></dt>
 <dd>String containing the path of the target file. Alternatively, may be an {{Interface("nsIFile")}} or a <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadTarget" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadTarget"><code>DownloadTarget</code></a> object.</dd>
 <dt><code>aOptions</code> {{optional_inline()}}</dt>
 <dd>An optional object used to control the behavior of this function. You may pass an object with a subset of the following fields:
 <ul>
  <li><code>isPrivate</code>: {{optional_inline()}} Indicates whether the download originated from a private window. If omitted, the download is public.</li>
 </ul>
 </dd>
</dl>

<h5 id="Promise_resolves_to_2">Promise resolves to</h5>

<p><code>undefined</code> when the download has finished successfully and you can access the target file.</p>

<h5 id="Promise_can_be_rejected_with">Promise can be rejected with</h5>

<p><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadError" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadError"><code>DownloadError</code></a> if the download failed.</p>

<h3 id="getList()">getList()</h3>

<p>Retrieves the specified type of <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadList" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadList"><code>DownloadList</code></a> object. There is one download list for each type, and this method always retrieves a reference to the same download list when called with the same argument.</p>

<p>Calling this function may cause the download list to be reloaded from the previous session, if it wasn't loaded already.</p>

<pre>Promise&lt;DownloadList&gt; getList(aType);
</pre>

<h5 id="Parameters_3">Parameters</h5>

<dl>
 <dt><code>aType</code></dt>
 <dd>This can be <code>Downloads.PUBLIC</code>, <code>Downloads.PRIVATE</code>, or <code>Downloads.ALL</code>. Downloads added to the <code>Downloads.PUBLIC</code> and <code>Downloads.PRIVATE</code> lists are reflected in the <code>Downloads.ALL</code> list, and downloads added to the <code>Downloads.ALL</code> list are also added to either the <code>Downloads.PUBLIC</code> or the <code>Downloads.PRIVATE</code> list based on their properties.</dd>
</dl>

<h5 id="Promise_resolves_to_3">Promise resolves to</h5>

<p>The requested <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadList" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadList"><code>DownloadList</code></a> object.</p>

<h3 id="getSummary()">getSummary()</h3>

<p>Retrieves the specified type of <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSummary" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSummary"><code>DownloadSummary</code></a> object. There is one download summary for each type, and this method always retrieves a reference to the same download summary when called with the same argument.</p>

<p>Calling this function does not cause the list of public downloads to be reloaded from the previous session. The summary will behave as if no downloads are present until the <a href="#getList()" title="#getList()"><code>getList()</code></a> method is called.</p>

<pre>Promise&lt;DownloadSummary&gt; getSummary(aType);
</pre>

<h5 id="Parameters_4">Parameters</h5>

<dl>
 <dt><code>aType</code></dt>
 <dd>This can be <code>Downloads.PUBLIC</code>, <code>Downloads.PRIVATE</code>, or <code>Downloads.ALL</code>.</dd>
</dl>

<h5 id="Promise_resolves_to_4">Promise resolves to</h5>

<p>The requested <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSummary" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadSummary"><code>DownloadSummary</code></a> object.</p>

<h2 id="Examples">Examples</h2>

<h3 id="Downloading_to_a_local_file">Downloading to a local file</h3>

<p>This example downloads an HTML file without showing progress, handling errors programmatically.</p>

<pre class="brush: js">Components.utils.import("resource://gre/modules/Downloads.jsm");
Components.utils.import("resource://gre/modules/osfile.jsm")
Components.utils.import("resource://gre/modules/Task.jsm");

Task.spawn(function () {

  yield Downloads.fetch("http://www.mozilla.org/",
                        OS.Path.join(OS.Constants.Path.tmpDir,
                                     "example-download.html"));

  console.log("example-download.html has been downloaded.");

}).then(null, Components.utils.reportError);
</pre>

<h3 id="Observing_downloads">Observing downloads</h3>

<p>This example logs a message every time a change occurs in one of the global download lists.</p>

<p>To demonstrate the logging, a new download is started while a message box is being shown. The download is stopped and removed from the list when the message box is closed, regardless of whether it has been completed or not.</p>

<pre class="brush: js">Components.utils.import("resource://gre/modules/Downloads.jsm");
Components.utils.import("resource://gre/modules/osfile.jsm")
Components.utils.import("resource://gre/modules/Task.jsm");

Task.spawn(function () {

  let list = yield Downloads.getList(Downloads.ALL);

  let view = {
    onDownloadAdded: download =&gt; console.log("Added", download),
    onDownloadChanged: download =&gt; console.log("Changed", download),
    onDownloadRemoved: download =&gt; console.log("Removed", download)
  };

  yield list.addView(view);
  try {
    let download = yield Downloads.createDownload({
      source: "http://www.mozilla.org/",
      target: OS.Path.join(OS.Constants.Path.tmpDir, "example-download.html"),
    });
    list.add(download);
    try {
      download.start();
      alert("Now monitoring all downloads. Close the message to stop.");
    } finally {
      yield list.remove(download);
      yield download.finalize(true);
    }
  } finally {
    yield list.removeView(view);
  }

}).then(null, Components.utils.reportError);
</pre>

<h2 id="Conversion_from_nsIDownloadManager">Conversion from nsIDownloadManager</h2>

<p>Starting in Firefox for Desktop version 26, the {{interface("nsIDownloadManager")}} and {{interface("nsIDownload")}} interfaces are not available anymore.</p>

<p>The new module works differently from the old component. In general, you should be aware of the following highlights:</p>

<ul>
 <li>There is no difference between active downloads and finished downloads. The <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download"><code>Download</code></a> object can be used without requiring direct database access.</li>
 <li>Observer notifications (for example, <code>"dl-done"</code>) and download listeners are replaced by views on the <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadList" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadList"><code>DownloadList</code></a> object returned by the <a href="#getList()" title="#getList()"><code>getList()</code></a> method.</li>
 <li>Object identity replaces the use of numeric identifiers. You can use <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download"><code>Download</code></a> objects as keys in a <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set"><code>Set</code></a> or <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map"><code>Map</code></a> to associate your own state to them for the session.</li>
 <li>There is no separate count of active downloads. If a count is needed, it should be maintained using a view on a <code>DownloadList</code>.</li>
 <li>The <code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download#start()" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/Download#start()">start()</a></code> method can be used to restart a failed download. Handling of downloads that have been paused is also different.</li>
</ul>

<p>While some of the legacy methods and properties have an equivalent in <code>Downloads.jsm</code>, there might be subtle differences in behavior. For example, the properties that handle progress are now more detailed and don't use the special value <code>-1</code> anymore. You may see the documentation of the new methods and properties for details.</p>

<h2 id="Using_it_in_a_XUL_app">Using it in a XUL app</h2>

<p>In a XUL standalone application (running with XULRunner or <code>firefox --app</code>), you have to do additionnal things in order to use the new download manager. By default it is not enabled. It will be enabled when the <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=851471">bug 851471</a> will be closed. If you don't activate it, you could use Downloads.jsm, but your view will not be called by the external helper app service (when a user click on a file to download, in a web page). To enable the new download manager :</p>

<ul>
 <li>First you have to set the pref {{pref("browser.download.useJSTransfer")}} to <code>true</code>.</li>
 <li>Then you should declare the new {{interface("nsITransfer")}} object during the startup of your app.</li>
</ul>

<pre> Components.manager.QueryInterface(Components.interfaces.nsIComponentRegistrar)
                   .registerFactory(Components.ID("{1b4c85df-cbdd-4bb6-b04e-613caece083c}"), "", "@mozilla.org/transfer;1", null);

</pre>

<p> </p>

<h2 id="See_also">See also</h2>

<ul>
 <li><a class="internal" href="/en-US/docs/JavaScript_code_modules/Using" title="en-US/docs/JavaScript code modules/Using JavaScript code modules">Using JavaScript code modules</a></li>
 <li><a class="internal" href="/en-US/docs/Mozilla/JavaScript_code_modules" title="en-US/docs/Mozilla/JavaScript code modules">JavaScript code modules</a></li>
 <li><a class="internal" href="/en-US/docs/Components.utils.import" title="en-US/docs/Components.utils.import"><code>Components.utils.import</code></a></li>
</ul>

<div id="xunlei_com_thunder_helper_plugin_d462f475-c18e-46be-bd10-327458d045bd"> </div>