diff options
Diffstat (limited to 'files/ja/mozilla/javascript_code_modules/downloads.jsm/index.html')
| -rw-r--r-- | files/ja/mozilla/javascript_code_modules/downloads.jsm/index.html | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/files/ja/mozilla/javascript_code_modules/downloads.jsm/index.html b/files/ja/mozilla/javascript_code_modules/downloads.jsm/index.html new file mode 100644 index 0000000000..f01fc476ac --- /dev/null +++ b/files/ja/mozilla/javascript_code_modules/downloads.jsm/index.html @@ -0,0 +1,297 @@ +--- +title: Downloads.jsm +slug: Mozilla/JavaScript_code_modules/Downloads.jsm +translation_of: Mozilla/JavaScript_code_modules/Downloads.jsm +--- +<p>{{ gecko_minversion_header("26") }}</p> + +<p>Downloads.jsmはダウンロードに関する機能を提供するJavaScriptモジュールです。新規にダウンロードを開始したり、ダウンロード中に制御を行ったり、ダウンロードに関連する設定を呼び出したりできます。これを使用するにはまずモジュールをインポートする必要があります。</p> + +<pre>Components.utils.import("resource://gre/modules/Downloads.jsm"); +</pre> + +<h2 id="メソッドの概要">メソッドの概要</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><<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>> <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><void> <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><<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>> <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><<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>> <a href="#getSummary()">getSummary</a>(aType);</code></td> + </tr> + </tbody> +</table> + +<h2 id="定数">定数</h2> + +<table class="standard-table"> + <tbody> + <tr> + <td class="header">定数</td> + <td class="header">説明</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="プロパティ">プロパティ</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>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 && ex.becauseTargetFailed) { + console.log("Unable to write to the target file, ignoring the error."); +}</pre> + </td> + </tr> + </tbody> +</table> + +<h2 id="メソッド">メソッド</h2> + +<h3 id="createDownload()">createDownload()</h3> + +<p>新しく<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>オブジェクトを生成します。</p> + +<pre>Promise<Download> createDownload( + Object aProperties +); +</pre> + +<h5 id="パラメーター">パラメーター</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>新しく生成された<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>オブジェクト.</p> + +<h3 id="fetch()">fetch()</h3> + +<p>ネットワーク上のデータをローカルにダウンロードします。</p> + +<p>この関数はダウンロードをキャンセルしたり再開するインターフェイスを提供していません。その場合は<a href="#createDownload()" title="#createDownload()"><code>createDownload()</code></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>オブジェクトを参照してください。</p> + +<p>ダウンロードは再開されないため、たとえダウンロードが失敗しても部分的にダウンロードデータが保存されることはありません。</p> + +<pre>Promise fetch( + aSource, + aTarget, + Object aOptions +); +</pre> + +<h5 id="パラメーター_2">パラメーター</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>この関数を呼び出すと、ダウンロードリストが(すでにロードされている場合をのぞいて)リロードされます。</p> + +<pre>Promise<DownloadList> getList(aType); +</pre> + +<h5 id="パラメーター_3">パラメーター</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<DownloadSummary> getSummary(aType); +</pre> + +<h5 id="パラメーター_4">パラメーター</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="例">例</h2> + +<h3 id="ローカルにダウンロードする">ローカルにダウンロードする</h3> + +<p>この例では、HTMLファイルをダウンロードしています。ダウンロードの進捗状況を表示したり、エラー処理は行っていません。</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="ダウンロードの監視">ダウンロードの監視</h3> + +<p>この例では、グローバルなダウンロードリストに変化が発生するたびに、メッセージを記録しています。</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 => console.log("Added", download), + onDownloadChanged: download => console.log("Changed", download), + onDownloadRemoved: download => 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> |