异步模块定义(Asynchronous Module Definition,简称 AMD)API 描述了一种定义模块的机制,模块及其依赖模块可以通过这种机制进行加载。该机制特别适用于浏览器。

本规范曾被称为 Modules Transport/C,但本规范主要不是用来传输已有的 CommonJS 模块,而是用来定义模块。

define 函数

本规范只定义了一个函数 define,该函数是一个自由变量,或者说是一个全局变量。函数签名如下:

define(id?, dependencies?, factory);

第一个参数 id 指定了即将定义的模块的 id。该参数是可选的,如果未指定该参数,则模块的 id 默认为模块加载器请求该脚本时使用的模块 id。如果指定该参数,参数值必须是一个绝对 id(不允许使用相对 id)。

第二个参数 dependencies 是一个数组,包含即将定义的模块所有依赖模块名称。依赖模块必须在执行工厂函数之前完成解析,解析结果作为参数传递给工厂函数,工厂函数的参数顺序与 dependencies 参数所包含依赖模块顺序保持一致。依赖模块 id 可以为相对 id,所谓相对是指相对于即将定义的模块而言。如果 dependencies 中出现 require, exportsmodule 字样,则对应的参数应被解析为 CommonJS 模块规范中所定义的自由变量 require, exports 或 module。dependencies 参数是可选的,该参数缺省值为 ["require", "exports", "module"]。如果工厂函数的参数列表长度小于 3,那么加载器可以选择使用工厂函数参数列表长度所对应的 dependencies 参数来调用工厂函数。

第三个参数 factory 是一个函数,它用来初始化一个模块或对象。如果 factory 是一个函数,那它应该只被执行一次。如果 factory 是一个对象,那么它应该作为模块的输出物进行赋值。

如果 id 和 dependencies 全部缺省,则模块加载器应扫描工厂函数体中包含的 require 语句来确定依赖模块。为此,工厂函数的第一个参数应命名为 "require"。某些情况下加载器可以选择不去扫描依赖模块,例如代码大小限制,或者函数对象缺少 toString 方法。只要 id 或 dependencies 有一个被指定实参,则加载器就不应再扫描工厂函数来确定依赖模块。

define.amd 属性

为了能够清楚表明当前全局函数 define 是否符合 AMD API,任何一个全局函数 define 都应拥有一个 amd 属性,该属性值为一个对象。这样可以避免现有的 Javascript 代码中存在的全局函数 define 不符合 AMD API 的冲突。

define.amd 对象应拥有的属性不在本规范中给出说明。实现了 AMD API 的作者可以利用 amd 属性来通知别人,他的实现中除了基本的 AMD API,还额外提供了什么支持。

define.amd 属性表明当前 AMD 实现符合本规范所定义的 API。如果还有另一个版本的 API,那么将在 define 函数上添加另一个属性,例如 define.amd2 来表示该实现符合另一个版本的 API。

以下示例想要说明某个实现支持加载多个版本的模块:

define.amd = {
    multiversion: true

最简单的定义:

define.amd = {};

一次传输多个模块

一个脚本中可以多次调用 define 函数,define 函数的调用顺序不影响大局。先定义的模块可以指定后定义的模块作为依赖模块。模块加载器负责延迟加载未解析的依赖模块直到整个脚本都加载完毕,以此来阻止非必要的请求

使用 require 和 exports

定义一个 id 为 "alpha" 的模块,它有一个依赖模块 beta。

define("alpha", ["require", "exports", "beta"], function (require, exports, beta) {
    exports.verb = function () {
        return beta.verb();

定义一个匿名模块,模块的 id 来自于源文件名。

define(['alpha'], function (alpha) {
    return {
        verb: function () {
            return alpha.verb() + 2;

定义一个自由模块(没有依赖其他模块)。

define({
    add: function (x, y) {
        return x + y;

本规范保留了全局变量 define,*包的元数据异步定义 API and 作为保留关键字以备未来其他 CommonJS API 使用。模块加载器不应该在此函数上添加额外的方法或属性。

本规范保留了全局变量 require 提供给模块加载器使用。模块加载可以自由使用该全局变量,它们可以使用该变量,并向该变量添加属性或函数,甚至可以选择不使用 require。

define 函数的调用推荐使用 define(...) 的形式,以便静态分析工具可以顺利工作。

本规范曾使用 require.def() 作为入口方法。模块加载器可以将 define() 设置为 require.def() 的别名以向后兼容。

PS:本规范从 CommonJS 官方英文版本转译而来,斜体部分表示译文存在商榷。

CommonJS Asynchronous Module Definition