CMD规范(通用模块定义规范)(翻译)
最近在使用sea.js。大家知道sea.js遵循CMD规范。该规范的英文说明很简洁,我试着翻译了一下,旨在交流。
Common Module Definition
通用模块定义规范
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.
本规范规定如何定义和书写执行在浏览器环境中的js模块,这就是说,本规范定义了一个模块的最小API,这些API提供与该模块系统的交互。
- 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”定义的一个函数。
define(factory);
- The define function accepts a single argument, the module
factory.define函数接受一个参数,模块工厂
- The factory may be a function or other valid values.
Factory可能是一个函数,或是一个可验证值
- If factory is a function, the first three parameters of the function, if specified, must be "require", "exports", and "module", in that order.
如果factory是一个函数,如果参数指定了,这个函数的前三个参数,按照顺序这三个参数是“require”,“exports”,“module”
- If factory is not a function, then the module's exports are set to that object.
如果factory不是一个函数,模块的exports必须设置成一个对象。
Module Context
In a module, there are three free variables: require, exports and module.
模块中三个变量:require,exports和module
define(function(require, exports, module) {
// The module code goes here
});
The require Function
- require is a function
require是一个函数
- require accepts a module identifier.
require接受一个模块标识
- require returns the exported API of the foreign module.
require返回一个外部模块对外公开的API
- If requested module cannot be returned, require should return null.
如果请求的模块没有返回API,require必须返回null
- require.async is a function require.async是一个函数
- require.async accepts a list of module identifiers and a optional callback function.
require.async接受一个模块标识列表和一个回调函数
- The callback function receives module exports as function arguments, listed in the same order as the order in the first argument.
回调函数接收第i中指定的作为参数的模块列表中的所有模块的的export作为函数参数,并且顺序和该列表中的模块顺序一致。
- If requested module cannot be returned, the callback should receive null correspondingly.
如果请求的模块没有任何返回,回调函数也必须相应的按照顺序接收null。
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.
在模块中,还有一个参数“exports”,exports是一个对象,包含这个模块的所有API。
The module Object
- module.uri
The full resolved uri to the module.
模块的完整可解析的uri
- module.dependencies
A list of module identifiers that required by the module.
模块依赖的其他模块标识列表
- module.exports
The exported API of the module. It is the same as exports object.
模块公开的export对象。
Module Identifier
- A module identifier is and must be a literal string.
模块标识必须是合法的字符串
- Module identifiers may not have a filename extensions like .js.
模块标识不能包含文件扩展名,如.js
- Module identifiers should be dash-joined string, such as foo-bar.
模块标识可以使用“-”连接,如foo-bar
- Module identifiers can be a relative path, like ./foo and ../bar.
模块标识可以使用相对路径,如 ./foo、../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');
------------------------------------------------
来源:
https://github.com/cmdjs/specification/blob/master/draft/module.md
扩展:
https://github.com/seajs/seajs/issues/242