diff options
Diffstat (limited to 'files/zh-cn/mozilla/javascript_code_modules/downloads.jsm/download/index.html')
| -rw-r--r-- | files/zh-cn/mozilla/javascript_code_modules/downloads.jsm/download/index.html | 335 |
1 files changed, 0 insertions, 335 deletions
diff --git a/files/zh-cn/mozilla/javascript_code_modules/downloads.jsm/download/index.html b/files/zh-cn/mozilla/javascript_code_modules/downloads.jsm/download/index.html deleted file mode 100644 index 41230df3c4..0000000000 --- a/files/zh-cn/mozilla/javascript_code_modules/downloads.jsm/download/index.html +++ /dev/null @@ -1,335 +0,0 @@ ---- -title: Download -slug: Mozilla/JavaScript_code_modules/Downloads.jsm/Download -translation_of: Mozilla/JavaScript_code_modules/Downloads.jsm/Download ---- -<p> <code>Download</code> 对象仅仅表示下载，同时包含相关的状态和行为。这个对象是短时存在的，但是它可被包含在<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> 对象，因此它能够通过用户接口调用和跨sessions.</p> - -<p>调用<a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm#createDownload()" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm#createDownload()"><code>Downloads.createDownload()</code></a> 方法可以创建一个新的<code>Download</code> 对象。</p> - -<h2 id="方法概览">方法概览</h2> - -<table class="standard-table"> - <tbody> - <tr> - <td><code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a> <a href="#start()">start</a>();</code></td> - </tr> - <tr> - <td><code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a> <a href="#launch()">launch</a>();</code></td> - </tr> - <tr> - <td><code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a> <a href="#showContainingDirectory()">showContainingDirectory</a>();</code></td> - </tr> - <tr> - <td><code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a> <a href="#cancel()">cancel</a>();</code></td> - </tr> - <tr> - <td><code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a> <a href="#removePartialData()">removePartialData</a>();</code></td> - </tr> - <tr> - <td><code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a> <a href="#whenSucceeded()">whenSucceeded</a>();</code></td> - </tr> - <tr> - <td><code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise">Promise</a> <a href="#finalize()">finalize</a>([optional] boolean aRemovePartialData);</code></td> - </tr> - </tbody> -</table> - -<h2 id="属性">属性</h2> - -<table class="standard-table" style="width: auto;"> - <tbody> - <tr> - <td class="header">属性</td> - <td class="header">类型</td> - <td class="header">描述</td> - </tr> - <tr> - <td><code>canceled</code> {{ReadOnlyInline()}}</td> - <td><code>boolean</code></td> - <td> - <p>表示下载被取消。这个属性可设置为true，当被取消下载重新下载时被设置为false。</p> - - <p>This property becomes true as soon as the <a href="#cancel()" title="#cancel()"><code>cancel()</code></a> method is called, though the <code>stopped</code> property might remain false until the cancellation request has been processed. Temporary files or part files may still exist even if they are expected to be deleted, until the <code>stopped</code> property becomes true.</p> - </td> - </tr> - <tr> - <td><code>contentType</code></td> - <td><code>string</code></td> - <td> - <p>The MIME type of the download, for example "<code>text/plain</code>", or <code>null</code> if the MIME type is not available.</p> - - <p>This property may be populated or changed while the download is in progress, using the MIME type provided by the server.</p> - </td> - </tr> - <tr> - <td><code>currentBytes</code> {{ReadOnlyInline()}}</td> - <td><code>number</code></td> - <td> - <p>Number of bytes currently transferred. This value starts at zero, and may be updated regardless of the value of <code>hasProgress</code>.</p> - - <div class="note"><strong>Note:</strong> You shouldn't rely on this property being equal to <code>totalBytes</code> to determine whether the download is completed. You should use the individual state properties instead, since this value may not be updated after the last piece of data is transferred.</div> - </td> - </tr> - <tr> - <td><code>error</code> {{ReadOnlyInline()}}</td> - <td><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></td> - <td>When the download fails, this is set to a <code>DownloadError</code> instance indicating the cause of the failure. If the download has been completed successfully or has been canceled, this property is <code>null</code>. This property is reset to <code>null</code> when a failed download is restarted.</td> - </tr> - <tr> - <td><code>hasPartialData</code> {{ReadOnlyInline()}}</td> - <td><code>boolean</code></td> - <td> - <p>Indicates whether, at this time, there is any partially downloaded data that can be used when restarting a failed or canceled download.</p> - - <p>This property is relevant while the download is in progress, and also if it failed or has been canceled. If the download has been completed successfully, this property is not relevant anymore.</p> - - <p>Whether partial data can actually be retained depends on the saver and the download source, and may not be known before the download is started.</p> - </td> - </tr> - <tr> - <td><code>hasProgress</code> {{ReadOnlyInline()}}</td> - <td><code>boolean</code></td> - <td>Indicates whether this download's <code>progress</code> property is able to report partial progress while the download proceeds, and whether the value in <code>totalBytes</code> is relevant. This depends on the saver and the download source.</td> - </tr> - <tr> - <td><code>launchWhenSucceeded</code></td> - <td><code>boolean</code></td> - <td>If this property is <code>true</code> when the download finishes successfully, the target file will be opened or executed automatically.</td> - </tr> - <tr> - <td><code>launcherPath</code></td> - <td><code>string</code></td> - <td>Local file path of the application to be used to launch the target file, or <code>null</code> if the file should be launched with the default application associated with the <code>contentType</code> property or the extension of the target file.</td> - </tr> - <tr> - <td><code>onchange</code></td> - <td><code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Function" title="/en-US/docs/JavaScript/Reference/Global_Objects/Function">Function</a></code></td> - <td> - <p>This can be set to a function that is called after other properties change.</p> - - <div class="warning"> - <p><strong>Warning:</strong> This property cannot be used if the download is part of a <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>.</p> - </div> - </td> - </tr> - <tr> - <td><code>progress</code> {{ReadOnlyInline()}}</td> - <td><code>number</code></td> - <td> - <p>Progress percent, from 0 to 100. Intermediate values are reported only if <code>hasProgress</code> is true.</p> - - <div class="note"><strong>Note:</strong> You shouldn't rely on this property being equal to 100 to determine whether the download is completed. You should use the individual state properties (for example, the <code>succeeded</code> property) instead.</div> - </td> - </tr> - <tr> - <td><code>saver</code> {{ReadOnlyInline()}}</td> - <td><code>DownloadSaver</code></td> - <td>Saver object associated with this download.</td> - </tr> - <tr> - <td><code>source</code> {{ReadOnlyInline()}}</td> - <td><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></td> - <td>Source of this download.</td> - </tr> - <tr> - <td><code>startTime</code> {{ReadOnlyInline()}}</td> - <td><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date" title="/en-US/docs/JavaScript/Reference/Global_Objects/Date"><code>Date</code></a></td> - <td>Indicates the start time of the download. When the download starts, this property is set to a valid <code>Date</code> object. The default value is <code>null</code> before the download starts.</td> - </tr> - <tr> - <td><code>stopped</code> {{ReadOnlyInline()}}</td> - <td><code>boolean</code></td> - <td>Indicates that the download never started, has been completed successfully, failed, or has been canceled. This property becomes <code>false</code> when a download is started for the first time, or when a failed or canceled download is restarted.</td> - </tr> - <tr> - <td><code>succeeded</code> {{ReadOnlyInline()}}</td> - <td><code>boolean</code></td> - <td>This propery is <code>true</code> if the download has been completed successfully.</td> - </tr> - <tr> - <td><code>target</code> {{ReadOnlyInline()}}</td> - <td><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></td> - <td>Target of this download.</td> - </tr> - <tr> - <td><code>totalBytes</code> {{ReadOnlyInline()}}</td> - <td><code>number</code></td> - <td> - <p>When <code>hasProgress</code> is <code>true</code>, this indicates the total number of bytes to be transferred before the download finishes; this value can be zero if the file is empty.</p> - - <p><strong>Note:</strong> This property's value may not match the actual final size of the downloaded file if the download is encoded during the network transfer. You can use the <code>DownloadTarget.size</code> property to get the actual size of the completely-downloaded file once the download has succeeded.</p> - - <p>When <code>hasProgress</code> is <code>false</code>, this property is always zero.</p> - </td> - </tr> - <tr> - <td><code>tryToKeepPartialData</code></td> - <td><code>boolean</code></td> - <td> - <p>Indicates whether any partially downloaded data should be retained, to use when restarting a failed or canceled download. The default is <code>false</code>.</p> - - <p>Whether partial data can actually be retained depends on the saver and the download source, and may not be known before the download is started.</p> - - <p>To have any effect, this property must be set before starting the download. Resetting this property to <code>false</code> after the download has already started will not remove any partial data.</p> - - <div class="note"><strong>Note:</strong> If this property is set to <code>true</code>, care should be taken that partial data is removed before the reference to the download is discarded. This can be done using the <a href="#removePartialData()" title="#removePartialData()"><code>removePartialData()</code></a> or the <a href="#finalize()" title="#finalize()"><code>finalize()</code></a> methods.</div> - </td> - </tr> - </tbody> -</table> - -<h2 id="方法">方法</h2> - -<h3 id="start()">start()</h3> - -<p>Starts the download for the first time, or restarts a download that failed or has been canceled.</p> - -<p>Calling this method when the download has been completed successfully has no effect, and the method returns a resolved promise. If the download is in progress, the method returns the same promise as the previous call.</p> - -<p>If the <code><a href="#cancel()" title="#cancel()">cancel()</a></code> method was called but the cancellation process has not finished yet, this method waits for the cancellation to finish, then restarts the download immediately.</p> - -<div class="note"><strong>Note:</strong> If you need to start a new download from the same source, rather than restarting a failed or canceled one, you should create a separate <code>Download</code> object with the same source as the current one.</div> - -<pre>Promise start(); -</pre> - -<h6 id="Parameters">Parameters</h6> - -<p>None.</p> - -<h6 id="Promise_resolves_to">Promise resolves to</h6> - -<p><code>undefined</code> when the download has finished successfully and you can access the target file.</p> - -<h6 id="Promise_can_be_rejected_with">Promise can be rejected with</h6> - -<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="launch()">launch()</h3> - -<p>Opens or executes the target file after download has completed.</p> - -<p>If the <code>launcherPath</code> property is <code>null</code>, the file will be opened with the default application for the MIME type specified in the <code>contentType</code> property. If the content type is not available, an attempt will be made to obtain it from the extension of the target file.</p> - -<p>If the <code>launcherPath</code> property is set, the file will be opened with the specified custom application.</p> - -<pre>Promise launch(); -</pre> - -<h6 id="Parameters_2">Parameters</h6> - -<p>None.</p> - -<h6 id="Promise_resolves_to_2">Promise resolves to</h6> - -<p><code>undefined</code> when the instruction to launch the file has been successfully given to the operating system. Note that the OS might still take a while until the file is actually launched.</p> - -<h3 id="showContainingDirectory()">showContainingDirectory()</h3> - -<p>Shows the folder containing the target file, or where the target file will be saved. This may be called at any time, even if the download failed or is currently in progress.</p> - -<pre>Promise showContainingDirectory(); -</pre> - -<h6 id="Parameters_3">Parameters</h6> - -<p>None.</p> - -<h6 id="Promise_resolves_to_3">Promise resolves to</h6> - -<p><code>undefined</code> when the instruction to open the containing folder has been successfully given to the operating system. Note that the OS might still take a while until the folder is actually opened.</p> - -<h3 id="cancel()">cancel()</h3> - -<p>Cancels the download.</p> - -<p>The cancellation request is asynchronous. Until the cancellation process finishes, temporary files or part files may still exist even if they are expected to be deleted.</p> - -<p>In case the download completes successfully before the cancellation request could be processed, this method has no effect, and it returns a resolved promise. You should check the properties of the download at the time the returned promise is resolved to determine if the download was canceled.</p> - -<p>Calling this method when the download has been completed successfully, failed, or has been canceled has no effect, and the method returns a resolved promise. This behavior is designed for the case where the call to <code>cancel</code> happens asynchronously, and is consistent with the case where the cancellation request could not be processed in time.</p> - -<pre>Promise cancel(); -</pre> - -<h6 id="Parameters_4">Parameters</h6> - -<p>None.</p> - -<h6 id="Promise_resolves_to_4">Promise resolves to</h6> - -<p><code>undefined</code> when the cancellation process has finished.</p> - -<h6 id="Promise_can_be_rejected_with_2">Promise can be rejected with</h6> - -<p>Never rejected.</p> - -<h3 id="removePartialData()">removePartialData()</h3> - -<p>Removes any partial data kept as part of a canceled or failed download.</p> - -<p>If the download is not canceled or failed, this method has no effect, and it returns a resolved promise. If the <code><a href="#cancel()" title="#cancel()">cancel()</a></code> method was called but the cancellation process has not finished yet, this method waits for the cancellation to finish, then removes the partial data.</p> - -<p>After this method has been called, if the <code>tryToKeepPartialData</code> property is still <code>true</code> when the download is restarted, partial data will be retained during the new download attempt.</p> - -<pre>Promise removePartialData(); -</pre> - -<h5 id="Parameters_5">Parameters</h5> - -<p>None.</p> - -<h5 id="Promise_resolves_to_5">Promise resolves to</h5> - -<p><code>undefined</code> when the partial data has been successfully removed.</p> - -<h3 id="whenSucceeded()">whenSucceeded()</h3> - -<p>Returns a promise that is resolved as soon as this download finishes successfully, even if the download was stopped and restarted meanwhile.</p> - -<p>You can use this property for scheduling download completion actions in the current session, for downloads that are controlled interactively. If the download is not controlled interactively, you should use the promise returned by the <a href="#start()" title="#start()"><code>start()</code></a> method instead, to check for success or failure.</p> - -<pre>Promise whenSucceeded(); -</pre> - -<h5 id="Parameters_6">Parameters</h5> - -<p>None.</p> - -<h5 id="Promise_resolves_to_6">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_3">Promise can be rejected with</h5> - -<p>Never rejected.</p> - -<h3 id="finalize()">finalize()</h3> - -<p>Ensures that the download is stopped, and optionally removes any partial data kept as part of a canceled or failed download. After this method has been called, the download cannot be started again.</p> - -<div class="note"><strong>Note:</strong> This method should be used in place of the <code><a href="#cancel()" title="#cancel()">cancel()</a></code> and <a href="#removePartialData()" title="#removePartialData()"><code>removePartialData()</code></a> methods while shutting down or disposing of the download object, to prevent other callers from interfering with the operation. This is required because cancellation and other operations are asynchronous.</div> - -<pre>Promise finalize( - boolean aRemovePartialData -); -</pre> - -<h5 id="Parameters_7">Parameters</h5> - -<dl> - <dt><code>aRemovePartialData</code> {{optional_inline()}}</dt> - <dd>Whether any partially downloaded data should be removed after the download has been stopped. The default is <code>false</code>.</dd> -</dl> - -<h5 id="Promise_resolves_to_7">Promise resolves to</h5> - -<p><code>undefined</code> when the operation has finished successfully.</p> - -<h2 id="查看其他">查看其他</h2> - -<ul> - <li><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm" title="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm">Downloads.jsm</a></li> - <li><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm/DownloadTarget">DownloadTarget</a></li> -</ul> |