From 218934fa2ed1c702a6d3923d2aa2cc6b43c48684 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:43:23 -0500 Subject: initial commit --- .../mozilla/javascript_code_modules/index.html | 102 ++++++++++ .../javascript_code_modules/promise.jsm/index.html | 144 ++++++++++++++ .../promise.jsm/promise/index.html | 215 +++++++++++++++++++++ 3 files changed, 461 insertions(+) create mode 100644 files/zh-tw/mozilla/javascript_code_modules/index.html create mode 100644 files/zh-tw/mozilla/javascript_code_modules/promise.jsm/index.html create mode 100644 files/zh-tw/mozilla/javascript_code_modules/promise.jsm/promise/index.html (limited to 'files/zh-tw/mozilla/javascript_code_modules') diff --git a/files/zh-tw/mozilla/javascript_code_modules/index.html b/files/zh-tw/mozilla/javascript_code_modules/index.html new file mode 100644 index 0000000000..72f737df9e --- /dev/null +++ b/files/zh-tw/mozilla/javascript_code_modules/index.html @@ -0,0 +1,102 @@ +--- +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 +--- +
{{gecko_minversion_header("1.9")}}
+ +

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.

+ +

General topics

+ +
+
Using JavaScript code modules
+
An introduction to how to use JavaScript code modules.
+
Components.utils.import
+
How to import a JavaScript code module.
+
Components.utils.unload {{gecko_minversion_inline("7.0")}}
+
How to unload a JavaScript code module.
+
Code snippets: Modules
+
Examples of how to use code modules.
+
Mozilla Labs JS Modules
+
This page features a list of JS modules, along with download links and documentation, that extension developers can use in their code.
+
+ +
+
+ +

Standard code modules

+ +
+
AddonManager.jsm {{gecko_minversion_inline("2.0")}}
+
Interface to install, manage, and uninstall add-ons.
+
AddonRepository.jsm {{gecko_minversion_inline("2.0")}}
+
Allows searching of the add-ons repository.
+
Assert.jsm {{gecko_minversion_inline("28.0")}}
+
Implements the CommonJS Unit Testing specification version 1.1, which provides a basic, standardized interface for performing in-code logical assertions with optional, customizable error reporting.
+
ctypes.jsm {{fx_minversion_inline("3.6")}}
+
Provides an interface that allows JavaScript code to call native libraries without requiring the development of an XPCOM component.
+
CustomizableUI.jsm {{fx_minversion_inline("29")}}
+
Allows you to interact with customizable buttons and items in Firefox's main window UI.
+
DeferredTask.jsm {{gecko_minversion_inline("18.0")}}
+
Run a task after a delay.
+
Dict.jsm {{gecko_minversion_inline("5.0")}}
+
Provides an API for key/value pair dictionaries.
+
DownloadLastDir.jsm {{gecko_minversion_inline("2.0")}}
+
Provides the path to the directory into which the last download occurred.
+
Downloads.jsm {{gecko_minversion_inline("23.0")}}
+
Provides a single entry point to interact with the downloading capabilities of the platform.
+
FileUtils.jsm {{gecko_minversion_inline("1.9.2")}}
+
Provides helpers for dealing with files.
+
Geometry.jsm {{gecko_minversion_inline("2.0")}}
+
Provides routines for performing basic geometric operations on points and rectangles.
+
HTTP.jsm {{gecko_minversion_inline("25.0")}}
+
A wrapper for XMLHttpRequest that provides convenient and simplified API for dealing with HTTP requests.
+
JNI.jsm {{fx_minversion_inline("17.0")}}
+
Abstracts the js-ctypes to provide an interface that allows JavaScript code to call code running in native JVMs.
+
ISO8601DateUtils.jsm
+
Provides routines to convert between JavaScript Date objects and ISO 8601 date strings.
+
Log.jsm (formerly log4moz) {{gecko_minversion_inline("27.0")}}
+
Provides a log4j style API for logging log messages to various endpoints, such as the Browser Console or a file on disk. This module was formerly
+
NetUtil.jsm
+
Provides helpful networking utility functions, including the ability to easily copy data from an input stream to an output stream asynchronously.
+
openLocationLastURL.jsm {{gecko_minversion_inline("1.9.1.4")}}
+
Provides access to the last URL opened using the "Open Location" option in the File menu.
+
OSFile.jsm {{gecko_minversion_inline("16.0")}}
+
Provides routines to access files. Read, write, rename, create directories, ...
+
PerfMeasurement.jsm {{fx_minversion_inline("4.0")}}
+
Provides access to low-level hardware and OS performance measurement tools.
+
PluralForm.jsm
+
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.
+
PopupNotifications.jsm {{gecko_minversion_inline("2.0")}}
+
Provides an easy way to present non-modal notifications to users.
+
Promise.jsm {{gecko_minversion_inline("25.0")}}
+
Implements the Promises/A+ proposal as known in April 2013.
+
PromiseWorker.jsm {{gecko_minversion_inline("20.0")}}
+
A version of {{domxref("ChromeWorker")}} which uses promises to return the worker's result instead of using an event to do so.
+
Services.jsm {{gecko_minversion_inline("2.0")}}
+
Provides getters for conveniently obtaining access to commonly-used services.
+
source-editor.jsm {{fx_minversion_inline("11.0")}}
+
The Source Editor is used by developer tools such as the Style Editor; this interface implements the editor and lets you interact with it.
+
Sqlite.jsm {{gecko_minversion_inline("20.0")}}
+
A Promise-based API to {{ interface("mozIStorage") }}/SQLite.
+
Task.jsm {{gecko_minversion_inline("17.0")}}
+
Implements a subset of Task.js to make sequential, asynchronous operations simple, using the power of JavaScript's yield operator.
+
Timer.jsm {{gecko_minversion_inline("22.0")}}
+
A pure JS implementation of window.setTimeout.
+
Webapps.jsm {{gecko_minversion_inline("??.0")}}
+
Provides an interface to manager Open Web Apps.
+
WebRequest.jsm {{gecko_minversion_inline("41.0")}}
+
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.
+
XPCOMUtils.jsm
+
Contains utilities for JavaScript components loaded by the JS component loader.
+
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 new file mode 100644 index 0000000000..fc54b6e846 --- /dev/null +++ b/files/zh-tw/mozilla/javascript_code_modules/promise.jsm/index.html @@ -0,0 +1,144 @@ +--- +title: Promise.jsm +slug: Mozilla/JavaScript_code_modules/Promise.jsm +tags: + - NeedsTranslation + - TopicStub +translation_of: Mozilla/JavaScript_code_modules/Promise.jsm +--- +

{{ gecko_minversion_header("25") }}

+ +

The Promise.jsm JavaScript code module implements the Promises/A+ proposal as known in April 2013.

+ +
+

This module was used before DOM Promises were made globally available in Gecko 29. Its usage is not suggested for new code.

+ +

If you just need a Promise, consider using a DOM Promise instead.

+ +

If you need a Deferred, because you want to create a Promise and manually resolve or reject it, consider using PromiseUtils.jsm instead.

+
+ +

To use it, you first need to import the code module into your JavaScript scope:

+ +
Components.utils.import("resource://gre/modules/Promise.jsm");
+
+ +
+

Note: A preliminary promise module is also available starting from Gecko 17, though it didn't conform to the Promises/A+ proposal until Gecko 25:

+ +
Components.utils.import("resource://gre/modules/commonjs/promise/core.js");     // Gecko 17 to 20
+Components.utils.import("resource://gre/modules/commonjs/sdk/core/promise.js"); // Gecko 21 to 24
+
+ +

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 Add-on SDK loader.

+
+ +

Introduction

+ +

For an introduction to promises, you may start from the Add-on SDK documentation, keeping in mind that only the core subset is implemented in this module.

+ +

A promise is an object representing a value that may not be available yet. Internally, a promise can be in one of three states:

+ + + +

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.

+ +

To observe the state of a promise, its then 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 then method for details.

+ +

Promises may also be created using the new Promise() constructor.

+ +

Method overview

+ + + + + + + + + + + + + +
Deferred defer(); {{ obsolete_inline("30") }}
Promise resolve([optional] aValue);
Promise reject([optional] aReason);
+ +

Methods

+ +

defer()

+ +

Creates a new pending promise and provides methods to resolve or reject it.

+ +
Deferred defer(); {{ obsolete_inline("30") }}
+
+ +
Parameters
+ +

None.

+ +
Return value
+ +

A new object, containing the new promise in the promise property, and the methods to change its state in the resolve and reject properties. See the Deferred documentation for details.

+ +

resolve()

+ +

Creates a new promise fulfilled with the specified value, or propagates the state of an existing promise.

+ +
Promise resolve(
+  aValue
+);
+
+ +
Parameters
+ +
+
aValue {{ optional_inline() }}
+
If this value is not a promise, including undefined, 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.
+
+ +
Return value
+ +

A promise that can be pending, fulfilled, or rejected.

+ +

reject()

+ +

Creates a new promise rejected with the specified reason.

+ +
Promise reject(
+  aReason
+);
+
+ +
Parameters
+ +
+
aReason {{ optional_inline() }}
+
+

The rejection reason for the returned promise. Although the reason can be undefined, it is generally an Error object, like in exception handling.

+ +
Note: 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.
+
+
+ +
Return value
+ +

A rejected promise.

+ +

Examples

+ +

See the examples page.

+ +

See also

+ + 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 new file mode 100644 index 0000000000..44c0b22181 --- /dev/null +++ b/files/zh-tw/mozilla/javascript_code_modules/promise.jsm/promise/index.html @@ -0,0 +1,215 @@ +--- +title: Promise +slug: Mozilla/JavaScript_code_modules/Promise.jsm/Promise +tags: + - JavaScript + - Promise.jsm +translation_of: Mozilla/JavaScript_code_modules/Promise.jsm/Promise +--- +

一個 Promise 物件代表一個可能還不能使用的值。

+ +

可以用不同的方式接收一個 promise 的參照，比如作為一個異步 API 的回傳值。一但你有了 promise 的參照，你就可以呼叫它的 then() 方法來在它的值準備好後，或是，當錯誤發生時執行一些動作。

+ +

Promises 物件也可以透過 new Promise() 建構子來創建。當你使用一個 Promise 物件的參照時，並不需要額外引入 Promise.jsm 模組 。

+ +

一個 promise 可以處於三種內部狀態：

+ + + +
+

註: 你永遠應該處理、轉送或是回報錯誤（或是拒絕的原因）。如果你看到 "A promise chain failed to handle a rejection"，那很有可能是程式碼中有東西需要修正。請參考 handling errors and common pitfalls 。

+
+ +

文件規範

+ +

在說明文件中，完成值的型別通常被定義在角括號中。舉例來說，OS.File.exists 方法回傳的 promise 最終將會履行一個 boolean。

+ +
Promise<boolean> exists(string path);
+
+ +

拒絕原因通常可以分別在方法的文件中定義，而且當沒有特別說明時它將被當作是一個 Error 物件。

+ +

方法總覽

+ + + + + + + + + + +
Promise then([optional] Function onFulfill, [optional] Function onReject);
Promise catch([optional] Function onReject);
+ +

建構子

+ +

創建一個新的 promise ，初始化等待狀態，並提供一些 resolving 方法的參照，這些方法將可以用來改變它的狀態。

+ +
new Promise(executor);
+
+ +

參數

+ +
+
executor
+
+

這個方法將立刻被呼叫，伴隨著兩個 resolving 方法作為其參數：

+ + 
executor(resolve, reject);
+
+ +

建構子在 executor 結束之前不會結束。那些 resolving 方法可以在任何時候被使用，包含 executor 完成前和完成後，用來控制 promise 的最終狀態。如果 executor 拋出了例外，例外的值將被當作參數傳入 reject 方法。

+
+
+ +

Resolving 方法

+ +

resolve()

+ +

執行將特定值連結到 promise 的工作，或是傳遞狀態到一個已存在的 promise。如果被連結的 promise 已經處於被解決的狀態，無論是被連結到值、拒絕原因、或另外一個 promise，這個方法將不會做任何事。

+ +
註: 用一個等待中的 promise 當作此方法的 aValue 參數，並在這個 promise 被解決或被拒絕前再次呼叫此方法，第二次的呼叫並不會有任何效果，因為原本的 promise 已經被連結到這個等待中的 promise。
+ +
void resolve(
+  aValue
+);
+
+ +
參數
+ +
+
aValue Optional
+
如果這個值不是一個 promise，包含 undefined，它將成為被連結 promise 的完成值。如果這個值是一個 promise，則被連結的 promise 將會連結到這個傳入的 promise，並和它保持一樣的狀態（包含任何未來的轉變）。
+
+ +

reject()

+ +

用指定的原因拒絕被連結的 promise。如果該 promise 已經被解決，無論是連結到值、拒絕原因、或另外一個 promise，這個方法將不會做任何事。

+ +
void reject(
+  aReason
+);
+
+ +
參數
+ +
+
aReason Optional
+
+

被連結 promise 的拒絕原因。雖然原因可以是 undefined，它通常會是一個 Error 物件對象，就像例外處理那樣。

+ +
註: 這個參數不應該是一個 promise。指定一個拒絕 promise 作為拒絕原因會讓拒絕原因等於這個拒絕 promise 物件本身，而不是該 promise 的拒絕原因。
+
+
+ +

方法

+ +

then()

+ +

在 promise 被完成或是被拒絕後立刻呼叫提供的方法。一個新的 promise 將被回傳，新 promise 的狀態改變將基於此 promise 和提供的 callback 方法。

+ +

一個適當的 callback 總是在這個方法回傳後調用，無論此 promise 是否已經被完成或是被拒絕。你也可以在同一個 promise 上多次呼叫 then 方法，callback 們將被依照它們的註冊順序依序被調用。

+ +
+

警告: 如果 onFulfill callback 拋出例外， onReject callback 並不會被調用，錯誤也不會顯示在 console（你將會看到 promise 鍊失敗錯誤）。作為替代方法，你可以在你準備回傳的 promise 上註冊一個拒絕 callback 方法（使用 catch() 或是 then()），用於處理任何此 promise 上註冊的 callback 中拋出的例外。

+
+ +
註: 當你在同一個 promise 上呼叫多次 then 方法時，註冊的 callback 們將被獨立的調用。舉例來說，如果任何例外發生在其中一個 callback 中，它將不會影響其餘 callback 的執行。callback 的行為只會影響它註冊的 then 方法回傳的 promise。實際上，每次調用 then 方法將回傳完全不同的 promise。
+ +
Promise then(
+  Function onFulfill,
+  Function onReject
+);
+
+ +
參數
+ +
+
onFulfill Optional
+
如果 promise 被完成，這個方法將被調用，完成值將作為它的唯一參數，此方法的回傳值將決定 then 方法回傳的新 promise 的狀態。若此參數不是一個方法（通常為null），then 方法回傳的新 promise 將被用和原本 promise 相同的完成值完成。
+
onReject Optional
+
+

如果 promise 被拒絕，這個方法將被調用，拒絕原因將作為它的唯一參數，此方法的回傳值將決定 then 方法回傳的新 promise 的狀態。若此參數不是一個方法（通常為null），then 方法回傳的新 promise 將被用和原本 promise 相同的拒絕原因拒絕。

+
+
+ +
回傳值
+ +

一個預設等待的 promise ，接著可以假設其狀態基於 callback 方法的結果：

+ + + +

catch()

+ +

相當於呼叫 then() ，並使用 undefined 作為 onFulfill 參數的值。如果你串接 then(onFulfile).catch(onReject)，onFulfill 拋出的例外將會被攔截並傳入 onReject ，這和直接將 onReject 傳入 then() 中不同。

+ +
Promise catch(
+  Function onReject
+);
+
+ +

因此以下的呼叫是等價的：

+ +
p.then(undefined, logError);
+p.catch(logError);
+
+ +

除錯

+ +

基於 promise 的設計， promise 對象的狀態和值無法在不調用 then() 的前提下同步地檢視。

+ +

為了幫助除錯，只有在手動檢視 promise 對象時，才能看到更多資訊，這些資訊是代碼無法訪問的特殊屬性（目前，這是透過隨機化屬性名稱來實現的，因為缺少更複雜的語言或調適器的支持）。

+ +

這些代碼無法訪問，可檢視的屬性為：

+ + + +

Promise properties are visible in the debugger.Promise handlers can be watched from the Console.

+ +

範例

+ +

參見 examples.

+ +

錯誤處理和常見的陷阱

+ +

你應該回報沒有被處理的錯誤，除非你將 promise 移交給調用者或是交給其他的代碼來處理這些錯誤。

+ +
// ###### 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); });
+}
+ +

參見

+ + -- cgit v1.2.3-54-g00ecf