公共模塊定義/草案(Common Module Definition / draft - CMD草案)

This specification addresses how modules should be written in order to be interoperable in browser-based environment. By implication, this specification defines the minimum features that a module system must provide in order to support interoperable modules.

• Modules are singletons.
• New free variables within the module scope should not be introduced.
• Execution must be lazy.

Module Definition

A module is defined with define keyword, which is a function.

define(factory);

1. The define function accepts a single argument, the module factory.
2. The factory may be a function or other valid values.
3. If factory is a function, the first three parameters of the function, if specified, must be "require", "exports", and "module", in that order.
4. If factory is not a function, then the module's exports are set to that object.

Module Context

In a module, there are three free variables: require, exports and module.

define(function(require, exports, module) {

  // The module code goes here

});

The require Function

1. require is a function

   1. require accepts a module identifier.
   2. require returns the exported API of the foreign module.
   3. If requested module cannot be returned, require should return null.

2. require.async is a function

   1. require.async accepts a list of module identifiers and a optional callback function.
   2. The callback function receives module exports as function arguments, listed in the same order as the order in the first argument.
   3. If requested module cannot be returned, the callback should receive null correspondingly.

The exports Object

In a module, there is a free variable called "exports", that is an object that the module may add its API to as it executes.

The module Object

1. module.uri

   The full resolved uri to the module.

2. module.dependencies

   A list of module identifiers that required by the module.

3. module.exports

   The exported API of the module. It is the same as exports object. 

Module Identifier

1. A module identifier is and must be a literal string.
2. Module identifiers may not have a filename extensions like .js.
3. Module identifiers should be dash-joined string, such as foo-bar.
4. Module identifiers can be a relative path, like ./foo and ../bar.

Sample Code

A typical sample

math.js

define(function(require, exports, module) {
  exports.add = function() { var sum = 0, i = 0, args = arguments, l = args.length; while (i < l) { sum += args[i++]; } return sum; }; });

 

increment.js

define(function(require, exports, module) {
  var add = require('math').add; exports.increment = function(val) { return add(val, 1); }; });

 

program.js

define(function(require, exports, module) {
  var inc = require('increment').increment; var a = 1; inc(a); // 2  module.id == "program"; });

 

Wrapped modules with non-function factory

object-data.js

define({
    foo: "bar" });

 

array-data.js

define([
    'foo', 'bar' ]);

 

string-data.js

define('foo bar');

 

 

 

譯文：

本規範闡述瞭如何編寫模塊，以便在基於瀏覽器的環境中進行互操做。本規範定義了模塊系統必須提供的最小功能，以支持互操做模塊。

• 模塊應該是單例。
• 不該引入模塊做用域範圍內的新的自由變量。（模塊做用域範圍內不該引入新的自由變量）（其餘模塊不該引入模塊做用域範圍內的新的自由變量）
• 執行必須是懶惰的。

模塊定義

一個模塊就是一個函數，使用「define」關鍵字定義。

例如：

define(factory);

define函數接受單個參數，即模塊工廠。

工廠多是一個函數或其餘有效值。
若是factory是一個函數，函數的前三個參數（若是指定的話）必須是「require」，「exports」和「module」。
若是工廠不是一個函數（不是函數那必然就是對象或者基本類型了），那麼模塊的export屬性應該設置爲該對象（這裏這個「對象」兩個字，意思是「那個傳入模塊的單個參數，即模塊工程，由於它不是函數，那麼多是js對象或者js基本類型）。

模塊上下文 

一個模塊中有三個自由變量：require，exports 和 module。

例如：

define(function(require, exports, module) {

  // The module code goes here
 });

require函數

1. 」require「是一個這樣的函數：

1. require 函數接收一個模塊標識符（模塊標識符也叫模塊id）。
2. require 函數返回外部模塊的導出API（」導出API「是用來導出內容給外部模塊使用的）。
3. 若是沒法返回請求的模塊, require 函數將返回null。

2. 」require.async「 是一個這樣的函數：

1. require.async 接收一個模塊Id列表和一個可選的回調函數。
2. 回調函數接收模塊導出做爲函數參數，按照與第一個參數中的順序相同的順序列出。
3. 若是不能返回請求的模塊，則回調應該相應地收到null。

exports對象

每一個模塊中都有個名叫"exports"的自由變量，這是一個模塊能夠在模塊執行時添加模塊API的對象。

module對象

1. module.uri：完整解析的模塊URI（模塊URI的全路徑）。

2. module.dependencies：模塊請求的標識符（模塊id）列表。

3. module.exports：模塊的導出API（」導出API「是」用來導出什麼東西的API「）。 它與export對象相同。

模塊標識符（模塊id）

1. 模塊的標識符（模塊id）必須是字面量字符串。
2. 模塊標識符（模塊id）不能有相似  .js 的文件名擴展。
3. 模塊標識符（模塊id）應該是加前/後綴的字符串，好比：foo-bar。
4. 模塊標識符（模塊id）能夠是相對路徑，例如：  ./foo 和 ../bar.。

 

示例代碼

一個典型的例子：

math.js

define(function(require, exports, module) {
  exports.add = function() {
    var sum = 0, i = 0, args = arguments, l = args.length;
    while (i < l) {
      sum += args[i++];
    }
    return sum;
  };
});

 

increment.js

define(function(require, exports, module) {
  var add = require('math').add;
  exports.increment = function(val) {
    return add(val, 1);
  };
});

 

program.js

define(function(require, exports, module) {
  var inc = require('increment').increment;
  var a = 1;
  inc(a); // 2

  module.id == "program";
});

 

使用非函數的工廠包裝模塊

object-data.js

define({
    foo: "bar"
});

 

array-data.js

define([
    'foo',
    'bar'
]);

 

string-data.js

define('foo bar');