diff options
Diffstat (limited to 'files/zh-tw/mozilla/javascript_code_modules')
3 files changed, 0 insertions, 461 deletions
diff --git a/files/zh-tw/mozilla/javascript_code_modules/index.html b/files/zh-tw/mozilla/javascript_code_modules/index.html deleted file mode 100644 index 72f737df9e..0000000000 --- a/files/zh-tw/mozilla/javascript_code_modules/index.html +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: JavaScript code modules -slug: Mozilla/JavaScript_code_modules -tags: - - Add-ons - - Extensions - - JavaScript - - Landing - - Modules - - NeedsTranslation - - TopicStub - - XPCOM -translation_of: Mozilla/JavaScript_code_modules ---- -<div>{{gecko_minversion_header("1.9")}}</div> - -<p>JavaScript code modules let multiple privileged JavaScript scopes share code. For example, a module could be used by Firefox itself as well as by extensions, in order to avoid code duplication.</p> - -<h2 id="General_topics">General topics</h2> - -<dl style="-moz-columns: 2; columns: 2;"> - <dt><a href="/en-US/docs/JavaScript_code_modules/Using" title="./Using">Using JavaScript code modules</a></dt> - <dd>An introduction to how to use JavaScript code modules.</dd> - <dt><a href="/en-US/docs/Components.utils.import" title="Components.utils.import">Components.utils.import</a></dt> - <dd>How to import a JavaScript code module.</dd> - <dt><a href="/en-US/docs/Components.utils.unload" title="Components.utils.unload">Components.utils.unload</a> {{gecko_minversion_inline("7.0")}}</dt> - <dd>How to unload a JavaScript code module.</dd> - <dt><a href="/en-US/docs/Code_snippets/Modules" title="Code_snippets/Modules">Code snippets: Modules</a></dt> - <dd>Examples of how to use code modules.</dd> - <dt><a class="external" href="http://wiki.mozilla.org/Labs/JS_Modules">Mozilla Labs JS Modules</a></dt> - <dd>This page features a list of JS modules, along with download links and documentation, that extension developers can use in their code.</dd> -</dl> - -<dl> -</dl> - -<h2 id="Standard_code_modules">Standard code modules</h2> - -<dl style="-moz-columns: 2; columns: 2;"> - <dt><a href="/en-US/docs/Addons/Add-on_Manager" title="Addons/Add-on_Manager">AddonManager.jsm</a> {{gecko_minversion_inline("2.0")}}</dt> - <dd>Interface to install, manage, and uninstall add-ons.</dd> - <dt><a href="/en-US/docs/Addons/Add-on_Repository" title="Addons/Add-on Repository">AddonRepository.jsm</a> {{gecko_minversion_inline("2.0")}}</dt> - <dd>Allows searching of the add-ons repository.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Assert.jsm" title="./Assert.jsm">Assert.jsm</a> {{gecko_minversion_inline("28.0")}}</dt> - <dd>Implements the <a href="http://wiki.commonjs.org/wiki/Unit_Testing/1.1" title="http://wiki.commonjs.org/wiki/Unit_Testing/1.1">CommonJS Unit Testing specification version 1.1</a>, which provides a basic, standardized interface for performing in-code logical assertions with optional, customizable error reporting.</dd> - <dt><a href="/en-US/docs/Mozilla/js-ctypes" title="./ctypes.jsm">ctypes.jsm</a> {{fx_minversion_inline("3.6")}}</dt> - <dd>Provides an interface that allows JavaScript code to call native libraries without requiring the development of an XPCOM component.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/CustomizableUI.jsm" title="./ctypes.jsm">CustomizableUI.jsm</a> {{fx_minversion_inline("29")}}</dt> - <dd>Allows you to interact with customizable buttons and items in Firefox's main window UI.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/DeferredTask.jsm" title="./DeferredTask.jsm">DeferredTask.jsm</a> {{gecko_minversion_inline("18.0")}}</dt> - <dd>Run a task after a delay.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Dict.jsm" title="./Dict.jsm">Dict.jsm</a> {{gecko_minversion_inline("5.0")}}</dt> - <dd>Provides an API for key/value pair dictionaries.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/DownloadLastDir.jsm" title="./DownloadLastDir.jsm">DownloadLastDir.jsm</a> {{gecko_minversion_inline("2.0")}}</dt> - <dd>Provides the path to the directory into which the last download occurred.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Downloads.jsm" title="./Downloads.jsm">Downloads.jsm</a> {{gecko_minversion_inline("23.0")}}</dt> - <dd>Provides a single entry point to interact with the downloading capabilities of the platform.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/FileUtils.jsm" title="./FileUtils.jsm"><strong style="font-weight: bold;">FileUtils.jsm</strong></a> {{gecko_minversion_inline("1.9.2")}}</dt> - <dd>Provides helpers for dealing with files.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Geometry.jsm" title="./Geometry.jsm">Geometry.jsm</a> {{gecko_minversion_inline("2.0")}}</dt> - <dd>Provides routines for performing basic geometric operations on points and rectangles.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Geometry.jsm" title="./Geometry.jsm">HTTP.jsm</a> {{gecko_minversion_inline("25.0")}}</dt> - <dd>A wrapper for XMLHttpRequest that provides convenient and simplified API for dealing with HTTP requests.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/JNI.jsm">JNI.jsm</a> {{fx_minversion_inline("17.0")}}</dt> - <dd>Abstracts the js-ctypes to provide an interface that allows JavaScript code to call code running in native JVMs.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/ISO8601DateUtils.jsm" title="./ISO8601DateUtils.jsm">ISO8601DateUtils.jsm</a></dt> - <dd>Provides routines to convert between JavaScript <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Date" title="JavaScript/ Reference/Global Objects/Date"><code>Date</code></a> objects and ISO 8601 date strings.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Log.jsm">Log.jsm</a> (formerly log4moz) {{gecko_minversion_inline("27.0")}}</dt> - <dd>Provides a <a href="https://en.wikipedia.org/wiki/Log4j">log4j</a> style API for logging log messages to various endpoints, such as the <a href="/en-US/docs/Tools/Browser_Console">Browser Console</a> or a file on disk. This module was formerly</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/NetUtil.jsm" title="./NetUtil.jsm"><strong style="font-weight: bold;">NetUtil.jsm</strong></a></dt> - <dd>Provides helpful networking utility functions, including the ability to easily copy data from an input stream to an output stream asynchronously.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/openLocationLastURL.jsm" title="./openLocationLastURL.jsm">openLocationLastURL.jsm</a> {{gecko_minversion_inline("1.9.1.4")}}</dt> - <dd>Provides access to the last URL opened using the "Open Location" option in the File menu.</dd> - <dt><a href="/Mozilla/JavaScript_code_modules/OSFile.jsm" title="/en-US/docs/JavaScript_OS.File">OSFile.jsm</a> {{gecko_minversion_inline("16.0")}}</dt> - <dd>Provides routines to access files. Read, write, rename, create directories, ...</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/PerfMeasurement.jsm" title="./PerfMeasurement.jsm">PerfMeasurement.jsm</a> {{fx_minversion_inline("4.0")}}</dt> - <dd>Provides access to low-level hardware and OS performance measurement tools.</dd> - <dt><a href="/en-US/docs/Localization_and_Plurals" title="Localization and Plurals">PluralForm.jsm</a></dt> - <dd>Provides an easy way to get the correct plural forms for the current locale, as well as ways to localize to a specific plural rule.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/PopupNotifications.jsm" title="./PopupNotifications.jsm">PopupNotifications.jsm</a> {{gecko_minversion_inline("2.0")}}</dt> - <dd>Provides an easy way to present non-modal notifications to users.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm" title="./Promise.jsm">Promise.jsm</a> {{gecko_minversion_inline("25.0")}}</dt> - <dd>Implements the <a class="external" href="https://github.com/promises-aplus/promises-spec/blob/1.0.0/README.md" title="https://github.com/promises-aplus/promises-spec/blob/1.0.0/README.md">Promises/A+</a> proposal as known in April 2013.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/PromiseWorker.jsm">PromiseWorker.jsm</a> {{gecko_minversion_inline("20.0")}}</dt> - <dd>A version of {{domxref("ChromeWorker")}} which uses promises to return the worker's result instead of using an event to do so.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm" title="./Services.jsm">Services.jsm</a> {{gecko_minversion_inline("2.0")}}</dt> - <dd>Provides getters for conveniently obtaining access to commonly-used services.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/source-editor.jsm" title="./source-editor.jsm">source-editor.jsm</a> {{fx_minversion_inline("11.0")}}</dt> - <dd>The Source Editor is used by developer tools such as the Style Editor; this interface implements the editor and lets you interact with it.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Sqlite.jsm" title="./Sqlite.jsm">Sqlite.jsm</a> {{gecko_minversion_inline("20.0")}}</dt> - <dd>A Promise-based API to {{ interface("mozIStorage") }}/SQLite.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Task.jsm" title="./Task.jsm">Task.jsm</a> {{gecko_minversion_inline("17.0")}}</dt> - <dd>Implements a subset of <a class="external" href="http://taskjs.org/" title="http://taskjs.org/">Task.js</a> to make sequential, asynchronous operations simple, using the power of JavaScript's <code>yield</code> operator.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Timer.jsm" title="/en-US/docs/Mozilla/JavaScript_code_modules/Timer.jsm">Timer.jsm </a>{{gecko_minversion_inline("22.0")}}</dt> - <dd>A pure JS implementation of <code>window.setTimeout</code>.</dd> - <dt><a href="/en-US/Add-ons/Webapps.jsm" title="/en-US/docs/Mozilla/JavaScript_code_modules/Timer.jsm">Webapps.jsm </a>{{gecko_minversion_inline("??.0")}}</dt> - <dd>Provides an interface to manager Open Web Apps.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/WebRequest.jsm">WebRequest.jsm</a> {{gecko_minversion_inline("41.0")}}</dt> - <dd>Provides an API to add event listeners for the various stages of making an HTTP request. The event listener receives detailed information about the request, and can modify or cancel the request.</dd> - <dt><a href="/en-US/docs/Mozilla/JavaScript_code_modules/XPCOMUtils.jsm" title="./XPCOMUtils.jsm">XPCOMUtils.jsm</a></dt> - <dd>Contains utilities for JavaScript components loaded by the JS component loader.</dd> -</dl> diff --git a/files/zh-tw/mozilla/javascript_code_modules/promise.jsm/index.html b/files/zh-tw/mozilla/javascript_code_modules/promise.jsm/index.html deleted file mode 100644 index fc54b6e846..0000000000 --- a/files/zh-tw/mozilla/javascript_code_modules/promise.jsm/index.html +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: Promise.jsm -slug: Mozilla/JavaScript_code_modules/Promise.jsm -tags: - - NeedsTranslation - - TopicStub -translation_of: Mozilla/JavaScript_code_modules/Promise.jsm ---- -<p>{{ gecko_minversion_header("25") }}</p> - -<p>The <code>Promise.jsm</code> JavaScript code module implements the <a href="https://github.com/promises-aplus/promises-spec/blob/1.0.0/README.md" title="https://github.com/promises-aplus/promises-spec/blob/1.0.0/README.md">Promises/A+</a> proposal as known in April 2013.</p> - -<div class="warning"> -<p>This module was used before <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">DOM Promises</a> were made globally available in Gecko 29. Its usage is not suggested for new code.</p> - -<p>If you just need a Promise, consider using a <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">DOM Promise</a> instead.</p> - -<p>If you need a <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Deferred">Deferred</a>, because you want to create a Promise and manually resolve or reject it, consider using <a href="/en-US/docs/Mozilla/JavaScript_code_modules/PromiseUtils.jsm">PromiseUtils.jsm</a> instead.</p> -</div> - -<p>To use it, you first need to import the code module into your JavaScript scope:</p> - -<pre>Components.utils.import("resource://gre/modules/Promise.jsm"); -</pre> - -<div class="note"> -<p><strong>Note:</strong> A preliminary promise module is also available starting from Gecko 17, though it didn't conform to the Promises/A+ proposal until Gecko 25:</p> - -<pre>Components.utils.import("<s>resource://gre/modules/commonjs/promise/core.js</s>"); // Gecko 17 to 20 -Components.utils.import("<s>resource://gre/modules/commonjs/sdk/core/promise.js</s>"); // Gecko 21 to 24 -</pre> - -<p>This implementation also includes helper functions that are specific to the Add-on SDK. While you may still import this module from the above paths, the recommended way for loading it is through the <a href="https://addons.mozilla.org/en-US/developers/docs/sdk/latest/modules/toolkit/loader.html" title="https://addons.mozilla.org/en-US/developers/docs/sdk/latest/modules/toolkit/loader.html">Add-on SDK loader</a>.</p> -</div> - -<h2 id="Introduction">Introduction</h2> - -<p>For an introduction to promises, you may start from the <a href="/en-US/Add-ons/SDK/Low-Level_APIs/core_promise">Add-on SDK documentation</a>, keeping in mind that only the core subset is implemented in this module.</p> - -<p><u>A promise is an object representing a value that may not be available yet</u>. Internally, a promise can be in one of three states:</p> - -<ul> - <li><strong>Pending</strong>, when the final value is not available yet. This is the only state that may transition to one of the other two states.</li> - <li><strong>Fulfilled</strong>, when and if the final value becomes available. A <em>fulfillment value</em> becomes permanently associated with the promise. This may be any value, including <code>undefined</code>.</li> - <li><strong>Rejected</strong>, if an error prevented the final value from being determined. A <em>rejection reason</em> becomes permanently associated with the promise. This may be any value, including <code>undefined</code>, though it is generally an <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Error" title="/en-US/docs/JavaScript/Reference/Global_Objects/Error"><code>Error</code></a> object, like in exception handling.</li> -</ul> - -<p>A reference to an existing promise may be received by different means, for example as the return value of a call into an asynchronous API. In this case, the state of the promise can be observed but not directly controlled.</p> - -<p>To observe the state of a promise, its <code>then</code> method must be used. This method registers callback functions that are called as soon as the promise is either fulfilled or rejected. The method returns a new promise, that in turn is fulfilled or rejected depending on the state of the original promise and on the behavior of the callbacks. For example, unhandled exceptions in the callbacks cause the new promise to be rejected, even if the original promise is fulfilled. See the documentation of the <code>then</code> method for details.</p> - -<p>Promises may also be created using the <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Promise#Constructor" title="/Mozilla/JavaScript_code_modules/Promise.jsm/Promise#Constructor"><code>new Promise()</code></a> constructor.</p> - -<h2 id="Method_overview">Method overview</h2> - -<table class="standard-table"> - <tbody> - <tr> - <td><code><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Deferred" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Deferred">Deferred</a> <a href="#defer()">defer</a>();</code> {{ obsolete_inline("30") }}</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="#resolve()">resolve</a>([optional] aValue);</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="#reject()">reject</a>([optional] aReason);</code></td> - </tr> - </tbody> -</table> - -<h2 id="Methods">Methods</h2> - -<h3 id="defer()">defer()</h3> - -<p>Creates a new pending promise and provides methods to resolve or reject it.</p> - -<pre>Deferred defer(); {{ obsolete_inline("30") }} -</pre> - -<h6 id="Parameters">Parameters</h6> - -<p>None.</p> - -<h6 id="Return_value">Return value</h6> - -<p>A new object, containing the new promise in the <code>promise</code> property, and the methods to change its state in the <code>resolve</code> and <code>reject</code> properties. See the <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Deferred" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Deferred"><code>Deferred</code></a> documentation for details.</p> - -<h3 id="resolve()">resolve()</h3> - -<p>Creates a new promise fulfilled with the specified value, or propagates the state of an existing promise.</p> - -<pre>Promise resolve( - aValue -); -</pre> - -<h6 id="Parameters_2">Parameters</h6> - -<dl> - <dt><code>aValue</code> {{ optional_inline() }}</dt> - <dd>If this value is not a promise, including <code>undefined</code>, it becomes the fulfillment value of the returned promise. If this value is a promise, then the returned promise will be resolved with the value, i.e. it will eventually assume the same state as the provided promise.</dd> -</dl> - -<h6 id="Return_value_2">Return value</h6> - -<p>A promise that can be pending, fulfilled, or rejected.</p> - -<h3 id="reject()">reject()</h3> - -<p>Creates a new promise rejected with the specified reason.</p> - -<pre>Promise reject( - aReason -); -</pre> - -<h6 id="Parameters_3">Parameters</h6> - -<dl> - <dt><code>aReason</code> {{ optional_inline() }}</dt> - <dd> - <p>The rejection reason for the returned promise. Although the reason can be <code>undefined</code>, it is generally an <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Error" title="/en-US/docs/JavaScript/Reference/Global_Objects/Error"><code>Error</code></a> object, like in exception handling.</p> - - <div class="note"><strong>Note:</strong> This argument should not be a promise. Specifying a rejected promise would make the rejection reason equal to the rejected promise itself, and not its rejection reason.</div> - </dd> -</dl> - -<h6 id="Return_value_3">Return value</h6> - -<p>A rejected promise.</p> - -<h2 id="Examples">Examples</h2> - -<p>See the <a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Examples">examples</a> page.</p> - -<h2 id="See_also">See also</h2> - -<ul> - <li><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></li> - <li><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Deferred" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Deferred">Deferred</a></li> - <li><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Examples">Examples</a></li> - <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> diff --git a/files/zh-tw/mozilla/javascript_code_modules/promise.jsm/promise/index.html b/files/zh-tw/mozilla/javascript_code_modules/promise.jsm/promise/index.html deleted file mode 100644 index 44c0b22181..0000000000 --- a/files/zh-tw/mozilla/javascript_code_modules/promise.jsm/promise/index.html +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Promise -slug: Mozilla/JavaScript_code_modules/Promise.jsm/Promise -tags: - - JavaScript - - Promise.jsm -translation_of: Mozilla/JavaScript_code_modules/Promise.jsm/Promise ---- -<p><strong>一個 <code>Promise</code> 物件代表一個可能還不能使用的值。</strong></p> - -<p>可以用不同的方式接收一個 promise 的參照，比如作為一個異步 API 的回傳值。一但你有了 promise 的參照，你就可以呼叫它的 <a href="#then()" title="#then()"><code>then()</code></a> 方法來在它的值準備好後，或是，當錯誤發生時執行一些動作。</p> - -<p>Promises 物件也可以透過 <a href="#Constructor" title="#Constructor"><code>new Promise()</code></a> 建構子來創建。當你使用一個 <code>Promise</code> 物件的參照時，並不需要額外引入 <code>Promise.jsm</code> 模組 。</p> - -<p>一個 promise 可以處於三種內部狀態：</p> - -<ul> - <li><strong>Pending</strong>, 當最終的值尚未準備好被使用時。這是唯一一個可以轉移到其他兩個狀態的狀態。</li> - <li><strong>Fulfilled</strong>, 當最終的值準備好被使用時。一個完成值將和 promise 建立永久關聯。它可能是任意的值，包和 <code>undefined</code>。</li> - <li><strong>Rejected</strong>, 當計算最終的值時有錯誤發生。一個拒絕原因將和 promise 建立永久關聯。它可以是任意的值，包含 <code>undefined</code>，儘管它通常是一個 <a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error" title="/en-US/docs/JavaScript/Reference/Global_Objects/Error"><code>Error</code></a> 物件對象，就像例外處理時一樣。</li> -</ul> - -<div class="note"> -<p><strong>註:</strong> 你永遠應該處理、轉送或是回報錯誤（或是拒絕的原因）。如果你看到 "<strong>A promise chain failed to handle a rejection</strong>"，那很有可能是程式碼中有東西需要修正。請參考 <a href="#Handling_errors_and_common_pitfalls" title="#Handling_errors_and_common_pitfalls">handling errors and common pitfalls</a> 。</p> -</div> - -<h2 id="文件規範">文件規範</h2> - -<p>在說明文件中，完成值的型別通常被定義在角括號中。舉例來說，<code><a href="/en-US/docs/JavaScript_OS.File/OS.File_for_the_main_thread#OS.File.exists()" title="/en-US/docs/JavaScript_OS.File/OS.File_for_the_main_thread#OS.File.exists()">OS.File.exists</a></code> 方法回傳的 promise 最終將會履行一個 boolean。</p> - -<pre>Promise<boolean> exists(string path); -</pre> - -<p>拒絕原因通常可以分別在方法的文件中定義，而且當沒有特別說明時它將被當作是一個 <a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error" title="/en-US/docs/JavaScript/Reference/Global_Objects/Error"><code>Error</code></a> 物件。</p> - -<h2 id="方法總覽">方法總覽</h2> - -<table class="standard-table"> - <tbody> - <tr> - <td><code>Promise <a href="#then()">then</a>([optional] <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Function" title="/en-US/docs/JavaScript/Reference/Global_Objects/Function">Function</a> onFulfill, </code><code>[optional] </code><code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Function" title="/en-US/docs/JavaScript/Reference/Global_Objects/Function">Function</a> onReject</code><code>);</code></td> - </tr> - <tr> - <td><code>Promise <a href="#catch">catch</a>([optional] <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Function">Function</a> onReject);</code></td> - </tr> - </tbody> -</table> - -<h2 id="建構子">建構子</h2> - -<p>創建一個新的 promise ，初始化等待狀態，並提供一些 resolving 方法的參照，這些方法將可以用來改變它的狀態。</p> - -<pre>new Promise(executor); -</pre> - -<h3 id="參數">參數</h3> - -<dl> - <dt><code>executor</code></dt> - <dd> - <p>這個方法將立刻被呼叫，伴隨著兩個 resolving 方法作為其參數：</p> - - <pre>executor(resolve, reject); -</pre> - - <p>建構子在 executor 結束之前不會結束。那些 resolving 方法可以在任何時候被使用，包含 executor 完成前和完成後，用來控制 promise 的最終狀態。如果 executor 拋出了例外，例外的值將被當作參數傳入 <code>reject</code> 方法。</p> - </dd> -</dl> - -<h3 id="Resolving_方法">Resolving 方法</h3> - -<h4 id="resolve()">resolve()</h4> - -<p>執行將特定值連結到 promise 的工作，或是傳遞狀態到一個已存在的 promise。如果被連結的 promise 已經處於被解決的狀態，無論是被連結到值、拒絕原因、或另外一個 promise，這個方法將不會做任何事。</p> - -<div class="note"><strong>註:</strong> 用一個等待中的 promise 當作此方法的 <code>aValue</code> 參數，並在這個 promise 被解決或被拒絕前再次呼叫此方法，第二次的呼叫並不會有任何效果，因為原本的 promise 已經被連結到這個等待中的 promise。</div> - -<pre>void resolve( - aValue -); -</pre> - -<h6 id="參數_2">參數</h6> - -<dl> - <dt><code>aValue</code> <span class="inlineIndicator optional optionalInline">Optional</span></dt> - <dd>如果這個值不是一個 promise，包含 <code>undefined</code>，它將成為被連結 promise 的完成值。如果這個值是一個 promise，則被連結的 promise 將會連結到這個傳入的 promise，並和它保持一樣的狀態（包含任何未來的轉變）。</dd> -</dl> - -<h4 id="reject()">reject()</h4> - -<p>用指定的原因拒絕被連結的 promise。如果該 promise 已經被解決，無論是連結到值、拒絕原因、或另外一個 promise，這個方法將不會做任何事。</p> - -<pre>void reject( - aReason -); -</pre> - -<h6 id="參數_3">參數</h6> - -<dl> - <dt><code>aReason</code> <span class="inlineIndicator optional optionalInline">Optional</span></dt> - <dd> - <p>被連結 promise 的拒絕原因。雖然原因可以是 <code>undefined</code>，它通常會是一個 <a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error" title="/en-US/docs/JavaScript/Reference/Global_Objects/Error"><code>Error</code></a> 物件對象，就像例外處理那樣。</p> - - <div class="note"><strong>註:</strong> 這個參數不應該是一個 promise。指定一個拒絕 promise 作為拒絕原因會讓拒絕原因等於這個拒絕 promise 物件本身，而不是該 promise 的拒絕原因。</div> - </dd> -</dl> - -<h2 id="方法">方法</h2> - -<h3 id="then()">then()</h3> - -<p>在 promise 被完成或是被拒絕後立刻呼叫提供的方法。一個新的 promise 將被回傳，新 promise 的狀態改變將基於此 promise 和提供的 callback 方法。</p> - -<p>一個適當的 callback 總是在這個方法回傳後調用，無論此 promise 是否已經被完成或是被拒絕。你也可以在同一個 promise 上多次呼叫 <code>then</code> 方法，callback 們將被依照它們的註冊順序依序被調用。</p> - -<div class="warning"> -<p><strong>警告: </strong>如果 <code>onFulfill</code> callback 拋出例外， <code>onReject</code> callback 並不會被調用，錯誤也不會顯示在 console（你將會看到 promise 鍊失敗錯誤）。作為替代方法，你可以在你準備回傳的 promise 上註冊一個拒絕 callback 方法（使用 catch() 或是 then()），用於處理任何此 promise 上註冊的 callback 中拋出的例外。</p> -</div> - -<div class="note"><strong>註:</strong> 當你在同一個 promise 上呼叫多次 <code>then</code> 方法時，註冊的 callback 們將被獨立的調用。舉例來說，如果任何例外發生在其中一個 callback 中，它將不會影響其餘 callback 的執行。callback 的行為只會影響它註冊的 <code>then</code> 方法回傳的 promise。實際上，每次調用 <code>then</code> 方法將回傳完全不同的 promise。</div> - -<pre>Promise then( - Function onFulfill, - Function onReject -); -</pre> - -<h6 id="參數_4">參數</h6> - -<dl> - <dt><code>onFulfill</code> <span class="inlineIndicator optional optionalInline">Optional</span></dt> - <dd>如果 promise 被完成，這個方法將被調用，完成值將作為它的唯一參數，此方法的回傳值將決定 <code>then</code> 方法回傳的新 promise 的狀態。若此參數不是一個方法（通常為<code>null</code>），<code>then</code> 方法回傳的新 promise 將被用和原本 promise 相同的完成值完成。</dd> - <dt><code>onReject</code> <span class="inlineIndicator optional optionalInline">Optional</span></dt> - <dd> - <p>如果 promise 被拒絕，這個方法將被調用，拒絕原因將作為它的唯一參數，此方法的回傳值將決定 <code>then</code> 方法回傳的新 promise 的狀態。若此參數不是一個方法（通常為<code>null</code>），<code>then</code> 方法回傳的新 promise 將被用和原本 promise 相同的拒絕原因拒絕。</p> - </dd> -</dl> - -<h6 id="回傳值">回傳值</h6> - -<p>一個預設等待的 promise ，接著可以假設其狀態基於 callback 方法的結果：</p> - -<ul> - <li>如果 callback 回傳一個不是 primise 的值，包含 <code>undefined</code>，新的 promise 將被用這個值完成，就算原本的 primise 是被拒絕的。</li> - <li>如果 callback 拋出例外，新的 promise 將被用這個例外當作拒絕原因拒絕，就算原本的 promise 是被完成的。</li> - <li>如果 callback 回傳一個 promise ，則可以假設新的 promise 最終將會和該 promise 擁有相同的狀態。</li> -</ul> - -<h3 id="catch()"><a name="catch">catch()</a></h3> - -<p>相當於呼叫 <code>then()</code> ，並使用 <code>undefined</code> 作為 <code>onFulfill</code> 參數的值。如果你串接 <code>then(onFulfile).catch(onReject)</code>，<code>onFulfill</code> 拋出的例外將會被攔截並傳入 <code>onReject</code> ，這和直接將 <code>onReject</code> 傳入 <code>then()</code> 中不同。</p> - -<pre>Promise catch( - Function onReject -); -</pre> - -<p>因此以下的呼叫是等價的：</p> - -<pre>p.then(undefined, logError); -p.catch(logError); -</pre> - -<h2 id="除錯">除錯</h2> - -<p>基於 promise 的設計， promise 對象的狀態和值無法在不調用 <code><a href="#then()" title="#then()">then()</a></code> 的前提下同步地檢視。</p> - -<p>為了幫助除錯，只有在手動檢視 promise 對象時，才能看到更多資訊，這些資訊是代碼無法訪問的特殊屬性（目前，這是透過隨機化屬性名稱來實現的，因為缺少更複雜的語言或調適器的支持）。</p> - -<p>這些代碼無法訪問，可檢視的屬性為：</p> - -<ul> - <li><code><strong><span>{</span>{private:status}}</strong></code>: <strong>0</strong> 為等待， <strong>1</strong> 為完成， <strong>2</strong> 為拒絕。</li> - <li><code><strong><span>{</span>{private:value}}</strong></code>: 完成值或是拒絕原因，只對已完成或是已拒絕的 promise 有效。</li> - <li><code><strong><span>{</span>{private:handlers}}</strong></code>: 一個持有通過 <code><a href="#then()" title="#then()">then()</a></code> 方法註冊之方法的參照的物件陣列，只對等待中的 promise 有效。</li> -</ul> - -<p style="text-align: center;"><img alt="Promise properties are visible in the debugger." src="https://mdn.mozillademos.org/files/6471/Promise-Debug-1.png" style="border-style: solid; border-width: 2px; height: 482px; margin-bottom: 15px; margin-top: 15px; width: 403px;"><img alt="Promise handlers can be watched from the Console." src="https://mdn.mozillademos.org/files/6473/Promise-Debug-2.png" style="border-style: solid; border-width: 2px; height: 161px; width: 977px;"></p> - -<h2 id="範例">範例</h2> - -<p>參見 <a href="/Mozilla/JavaScript_code_modules/Promise.jsm/Examples">examples</a>.</p> - -<h2 id="錯誤處理和常見的陷阱">錯誤處理和常見的陷阱</h2> - -<p>你應該回報沒有被處理的錯誤，除非你將 promise 移交給調用者或是交給其他的代碼來處理這些錯誤。</p> - -<pre class="brush: js">// ###### WRONG: Silently drops any rejection notified by "OS.File.Exists". -OS.File.exists(path).then(exists => { if (exists) myRead(path); }); - -// ###### WRONG: Silently drops any exception raised by "myRead". -OS.File.exists(path).then(exists => { if (exists) myRead(path); }, Components.utils.reportError); - -// CORRECT (for example, might report the exception "myRead is not defined") -OS.File.exists(path).then(exists => { if (exists) myRead(path); }) - .catch(Components.utils.reportError); - -// CORRECT (the function returns a promise, and the caller will handle the rejection) -function myReadIfExists(path) -{ - return OS.File.exists(path).then(exists => { if (exists) myRead(path); }); -}</pre> - -<h2 id="參見">參見</h2> - -<ul> - <li><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm">Promise.jsm</a></li> - <li><a href="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Deferred" title="/en-US/docs/Mozilla/JavaScript_code_modules/Promise.jsm/Deferred">Deferred</a></li> - <li><a href="/Mozilla/JavaScript_code_modules/Promise.jsm/Examples">Examples</a></li> - <li><a href="/en-US/docs/JavaScript_OS.File" title="/en-US/docs/JavaScript_OS.File">JavaScript OS.File</a></li> - <li><a href="http://kryogenix.org/days/2013/12/12/promises-promises">Promises, Promises</a>: a useful simple explanation by Stuart Langridge</li> - <li><a href="http://dom.spec.whatwg.org/#promises">WHATWG Living Standard</a></li> -</ul> |