§ 1.使用

§ 1.1 加載 JavaScript 文件

RequireJS的目標是鼓勵代碼的模塊化，它使用了不同于傳統(tǒng)<script>標簽的腳本加載步驟。可以用它來加速、優(yōu)化代碼，但其主要目的還是為了代碼的模塊化。

RequireJS以一個相對于baseUrl的地址來加載所有的代碼。 頁面頂層<script>標簽含有一個特殊的屬性data-main，require.js使用它來啟動腳本加載過程，而baseUrl一般設置到與該屬性相一致的目錄。

baseUrl亦可通過RequireJS config手動設置。如果沒有顯式指定config及data-main，則默認的baseUrl為包含RequireJS的那個HTML頁面的所屬目錄。

RequireJS默認假定所有的依賴資源都是js腳本，因此無需在module ID上再加".js"后綴，RequireJS在進行module ID到path的解析時會自動補上后綴。你可以通過paths config設置一組腳本，這些有助于我們在使用腳本時碼更少的字。

有時候你想避開"baseUrl + paths"的解析過程，而是直接指定加載某一個目錄下的腳本。此時可以這樣做：如果一個module ID符合下述規(guī)則之一，其ID解析會避開常規(guī)的"baseUrl + paths"配置，而是直接將其加載為一個相對于當前HTML文檔的腳本：

以 ".js" 結(jié)束.
以 "/" 開始.
包含 URL 協(xié)議, 如 "http:" or "https:".

一般來說，最好還是使用baseUrl及"paths" config去設置module ID。它會給你帶來額外的靈活性，如便于腳本的重命名、重定位等。 同時，為了避免凌亂的配置，最好不要使用多級嵌套的目錄層次來組織代碼，而是要么將所有的腳本都放置到baseUrl中，要么分置為項目庫/第三方庫的一個扁平結(jié)構，如下：

www/
index.html
js/
app/
sub.js
lib/
jquery.js
canvas.js
app.js

index.html:

<script data-main="js/app.js" src="js/require.js"></script>

app.js:

requirejs.config({
  //By default load any module IDs from js/lib
  baseUrl: 'js/lib',
  //except, if the module ID starts with "app",
  //load it from the js/app directory. paths
  //config is relative to the baseUrl, and
  //never includes a ".js" extension since
  //the paths config could be for a directory.
  paths: {
    app: '../app'
  }
});
//Start the main app logic.
requirejs(['jquery', 'canvas', 'app/sub'],
function  ($, canvas, sub) {
  //jQuery, canvas and the app/sub module are all
  //loaded and can be used here now.
});

注意在示例中，三方庫如jQuery沒有將版本號包含在他們的文件名中。我們建議將版本信息放置在單獨的文件中來進行跟蹤。使用諸如volo這類的工具，可以將package.json打上版本信息，并在磁盤上保持文件名為"jquery.js"。這有助于你保持配置的最小化，避免為每個庫版本設置一條path。例如，將"jquery"配置為"jquery-1.7.2"。

理想狀況下，每個加載的腳本都是通過define()來定義的一個模塊；但有些"瀏覽器全局變量注入"型的傳統(tǒng)/遺留庫并沒有使用define()來定義它們的依賴關系，你必須為此使用shim config來指明它們的依賴關系。 如果你沒有指明依賴關系，加載可能報錯。這是因為基于速度的原因，RequireJS會異步地以無序的形式加載這些庫。

§ 1.2 data-main 入口點

require.js 在加載的時候會檢察data-main 屬性:

<script data-main="scripts/main" src="scripts/require.js"></script>

你可以在data-main指向的腳本中設置模板加載 選項，然后加載第一個應用模塊。.注意：你在main.js中所設置的腳本是異步加載的。所以如果你在頁面中配置了其它JS加載，則不能保證它們所依賴的JS已經(jīng)加載成功。例如：

<script data-main="scripts/main" src="scripts/require.js"></script>
<script src="scripts/other.js"></script>
// contents of main.js:
require.config({
  paths: {
    foo: 'libs/foo-1.1.3'
  }
});
// contents of other.js:
// This code might be called before the require.config() in main.js has executed. 
// When that happens, require.js will attempt to load 'scripts/foo.js' instead of 'scripts/libs/foo-1.1.3.js'
require( ['foo'], function( foo ) {
});

§ 1.3 定義模塊

模塊不同于傳統(tǒng)的腳本文件，它良好地定義了一個作用域來避免全局名稱空間污染。它可以顯式地列出其依賴關系，并以函數(shù)(定義此模塊的那個函數(shù))參數(shù)的形式將這些依賴進行注入，而無需引用全局變量。RequireJS的模塊是模塊模式的一個擴展，其好處是無需全局地引用其他模塊。

RequireJS的模塊語法允許它盡快地加載多個模塊，雖然加載的順序不定，但依賴的順序最終是正確的。同時因為無需創(chuàng)建全局變量，甚至可以做到在同一個頁面上同時加載同一模塊的不同版本。

一個磁盤文件應該只定義 1 個模塊。多個模塊可以使用內(nèi)置優(yōu)化工具將其組織打包。

§ 1.3.1 簡單的值對

如果一個模塊僅含值對，沒有任何依賴，則在define()中定義這些值對就好了：

//Inside file my/shirt.js:
define({
  color: "black",
  size: "unisize"
});

§ 1.3.2 函數(shù)式定義

如果一個模塊沒有任何依賴，但需要一個做setup工作的函數(shù)，則在define()中定義該函數(shù)，并將其傳給define()：

//my/shirt.js now does setup work
//before returning its module definition.
define(function () {
  //Do setup work here
  return {
    color: "black",
    size: "unisize"
  }
});

§ 1.3.3 存在依賴的函數(shù)式定義

如果模塊存在依賴：則第一個參數(shù)是依賴的名稱數(shù)組；第二個參數(shù)是函數(shù)，在模塊的所有依賴加載完畢后，該函數(shù)會被調(diào)用來定義該模塊，因此該模塊應該返回一個定義了本模塊的object。依賴關系會以參數(shù)的形式注入到該函數(shù)上，參數(shù)列表與依賴名稱列表一一對應。

//my/shirt.js now has some dependencies, a cart and inventory module in the same directory as shirt.js
define(["./cart", "./inventory"], function(cart, inventory) {
    //return an object to define the "my/shirt" module.
    return {
      color: "blue",
      size: "large",
      addToCart: function() {
        inventory.decrement(this);
        cart.add(this);
      }
    }
  }
);

本示例創(chuàng)建了一個my/shirt模塊，它依賴于my/cart及my/inventory。磁盤上各文件分布如下：

my/cart.js
my/inventory.js
my/shirt.js

模塊函數(shù)以參數(shù)"cart"及"inventory"使用這兩個以"./cart"及"./inventory"名稱指定的模塊。在這兩個模塊加載完畢之前，模塊函數(shù)不會被調(diào)用。

嚴重不鼓勵模塊定義全局變量。遵循此處的定義模式，可以使得同一模塊的不同版本并存于同一個頁面上(參見 高級用法 )。另外，函參的順序應與依賴順序保存一致。

返回的object定義了"my/shirt"模塊。這種定義模式下，"my/shirt"不作為一個全局變量而存在。

§ 1.3.4 將模塊定義為一個函數(shù)

對模塊的返回值類型并沒有強制為一定是個object，任何函數(shù)的返回值都是允許的。此處是一個返回了函數(shù)的模塊定義：

//A module definition inside foo/title.js. It uses my/cart and my/inventory modules from before,
//but since foo/title.js is in a different directory than the "my" modules, it uses the "my" in the module dependency name to find them. 
//The "my" part of the name can be mapped to any directory, but by default, it is assumed to be a sibling to the "foo" directory.
define(["my/cart", "my/inventory"],function(cart, inventory) {
  //return a function to define "foo/title".
  //It gets or sets the window title.
  return function(title) {
    return title ? (window.title = title) :
        inventory.storeName + ' ' + cart.name;
  }
});

§ 1.3.5 簡單包裝CommonJS來定義模塊

如果你現(xiàn)有一些以CommonJS模塊格式編寫的代碼，而這些代碼難于使用上述依賴名稱數(shù)組參數(shù)的形式來重構，你可以考慮直接將這些依賴對應到一些本地變量中進行使用。你可以使用一個CommonJS的簡單包裝來實現(xiàn)：

define(function(require, exports, module) {
    var a = require('a'),
      b = require('b');
    //Return the module value
    return function () {};
  }
);

該包裝方法依靠Function.prototype.toString()將函數(shù)內(nèi)容賦予一個有意義的字串值，但在一些設備如PS3及一些老的Opera手機瀏覽器中不起作用。考慮在這些設備上使用優(yōu)化器將依賴導出為數(shù)組形式。

§ 1.3.6 定義一個命名模塊

你可能會看到一些define()中包含了一個模塊名稱作為首個參數(shù)：

//Explicitly defines the "foo/title" module:
define("foo/title",["my/cart", "my/inventory"],function(cart, inventory) {
    //Define foo/title object in here.
  }
);

這些常由優(yōu)化工具生成。你也可以自己顯式指定模塊名稱，但這使模塊更不具備移植性——就是說若你將文件移動到其他目錄下，你就得重命名。一般最好避免對模塊硬編碼，而是交給優(yōu)化工具去生成。優(yōu)化工具需要生成模塊名以將多個模塊打成一個包，加快到瀏覽器的載人速度。

§ 1.3.7 其他注意事項

一個文件一個模塊: 每個Javascript文件應該只定義一個模塊，這是模塊名-至-文件名查找機制的自然要求。多個模塊會被優(yōu)化工具組織優(yōu)化，但你在使用優(yōu)化工具時應將多個模塊放置到一個文件中。

define()中的相對模塊名: 為了可以在define()內(nèi)部使用諸如require("./relative/name")的調(diào)用以正確解析相對名稱，記得將"require"本身作為一個依賴注入到模塊中：

define(["require", "./relative/name"], function(require) {
  var mod = require("./relative/name");
});

或者更好地，使用下述為轉(zhuǎn)換CommonJS模塊所設的更短的語法：

define(function(require) {
  var mod = require("./relative/name");
});

相對路徑在一些場景下格外有用，例如：為了以便于將代碼共享給其他人或項目，你在某個目錄下創(chuàng)建了一些模塊。你可以訪問模塊的相鄰模塊，無需知道該目錄的名稱。

生成相對于模塊的URL地址: 你可能需要生成一個相對于模塊的URL地址。你可以將"require"作為一個依賴注入進來，然后調(diào)用require.toUrl()以生成該URL:

define(["require"], function(require) {
  var cssUrl = require.toUrl("./style.css");
});

控制臺調(diào)試:如果你需要處理一個已通過require(["module/name"], function(){})調(diào)用加載了的模塊，可以使用模塊名作為字符串參數(shù)的require()調(diào)用來獲取它:

require("module/name").callSomeFunction()

注意這種形式僅在"module/name"已經(jīng)由其異步形式的require(["module/name"])加載了后才有效。只能在define內(nèi)部使用形如"./module/name"的相對路徑。

§ 1.3.8 循環(huán)依賴

如果你定義了一個循環(huán)依賴(a依賴b，b同時依賴a)，則在這種情形下當b的模塊函數(shù)被調(diào)用的時候，它會得到一個undefined的a。b可以在模塊已經(jīng)定義好后用require()方法再獲取(記得將require作為依賴注入進來)：

//Inside b.js:
define(["require", "a"],
  function(require, a) {
    //"a" in this case will be null if a also asked for b,
    //a circular dependency.
    return function(title) {
      return require("a").doSomething();
    }
  }
);

一般說來你無需使用require()去獲取一個模塊，而是應當使用注入到模塊函數(shù)參數(shù)中的依賴。循環(huán)依賴比較罕見，它也是一個重構代碼重新設計的警示燈。但不管怎樣，有時候還是要用到循環(huán)依賴，這種情形下就使用上述的require()方式來解決。

如果你熟悉CommonJS，你可以考慮使用exports為模塊建立一個空object，該object可以立即被其他模塊引用。在循環(huán)依賴的兩頭都如此操作之后，你就可以安全地持有其他模塊了。這種方法僅在每個模塊都是輸出object作為模塊值的時候有效，換成函數(shù)無效。

//Inside b.js:
define(function(require, exports, module) {
  //If "a" has used exports, then we have a real object reference here.
  //However, we cannot useany of a's properties until after b returns a value.
  var a = require("a");
  exports.foo = function () {
    return a.bar();
  };
});

或者，如果你使用依賴注入數(shù)組的步驟，則可用注入特殊的"exports"來解決：

//Inside b.js:
define(['a', 'exports'], function(a, exports) {
  //If "a" has used exports, then we have a real object reference here.
  //However, we cannot useany of a's properties until after b returns a value.
  exports.foo = function () {
    return a.bar();
  };
});

§ 1.3.9 JSONP服務依賴

JSONP是在javascript中服務調(diào)用的一種方式。它僅需簡單地通過一個script標簽發(fā)起HTTP GET請求，是實現(xiàn)跨域服務調(diào)用一種公認手段。

為了在RequireJS中使用JSON服務，須要將callback參數(shù)的值指定為"define"。這意味著你可將獲取到的JSONP URL的值看成是一個模塊定義。

下面是一個調(diào)用JSONP API端點的示例。該示例中，JSONP的callback參數(shù)為"callback"，因此"callback=define"告訴API將JSON響應包裹到一個"define()"中：

require(["http://example.com/api/data.json?callback=define"],  
  function (data) {
    //The data object will be the API response for theJSONP data call.
    console.log(data);
  }
); 

僅支持返回值類型為JSON object的JSONP服務，其他返回類型如數(shù)組、字串、數(shù)字等都不能支持。

§ 2.機制

RequireJS使用head.appendChild()將每一個依賴加載為一個script標簽。

RequireJS等待所有的依賴加載完畢，計算出模塊定義函數(shù)正確調(diào)用順序，然后依次調(diào)用它們。

在同步加載的服務端JavaScript環(huán)境中，可簡單地重定義require.load()來使用RequireJS。build系統(tǒng)就是這么做的。該環(huán)境中的require.load實現(xiàn)可在build/jslib/requirePatch.js中找到。

未來可能將該部分代碼置入require/目錄下作為一個可選模塊，這樣你可以在你的宿主環(huán)境中使用它來獲得正確的加載順序。

§ 3.配置選配

當在頂層HTML頁面(或不作為一個模塊定義的頂層腳本文件)中，可將配置作為首項放入：

<script src="scripts/require.js"></script>
<script>
 require.config({
  baseUrl: "/another/path",
  paths: {
    "some": "some/v1.0"
  },
  waitSeconds: 15
 });
 require( ["some/module", "my/module", "a.js", "b.js"],
  function(someModule,  myModule) {
    //This function will be called when all the dependencies
    //listed above are loaded. Note that this function could
    //be called before the page is loaded.
    //This callback is optional.
  }
 );
</script>
<script>
  var require = {
    deps: ["some/module1", "my/module2", "a.js", "b.js"],
    callback: function(module1, module2) {
      //This function will be called when all the dependencies
      //listed above in deps are loaded. Note that this
      //function could be called before the page is loaded.
      //This callback is optional.
    }
  };
</script>
<script src="scripts/require.js"></script>

或者，你將配置作為全局變量"require"在require.js加載之前進行定義，它會被自動應用。下面的示例定義的依賴會在require.js一旦定義了require()之后即被加載：

requirejs.config({
  bundles: {
    'primary': ['main', 'util', 'text', 'text!template.html'],
    'secondary': ['text!secondary.html']
  }
});
require(['util', 'text'], function(util, text) {
  //The script for module ID 'primary' was loaded,
  //and that script included the define()'d
  //modules for 'util' and 'text'
});

注意: 最好使用 var require = {} 的形式而不是 window.require = {}的形式。后者在IE中運行不正常。

支持的配置項：

baseUrl ：所有模塊的查找根路徑。所以上面的示例中，"my/module"的標簽src值是"/another/path/my/module.js"。當加載純.js文件(依賴字串以/開頭，或者以.js結(jié)尾，或者含有協(xié)議)，不會使用baseUrl。因此a.js及b.js都在包含上述代碼段的HTML頁面的同目錄下加載。

如未顯式設置baseUrl，則默認值是加載require.js的HTML所處的位置。如果用了data-main屬性，則該路徑就變成baseUrl。

paths ：path映射那些不直接放置于baseUrl下的模塊名。設置path時起始位置是相對于baseUrl的，除非該path設置以"/"開頭或含有URL協(xié)議（如http:）。在上述的配置下，"some/module"的script標簽src值是"/another/path/some/v1.0/module.js"。

用于模塊名的path不應含有.js后綴，因為一個path有可能映射到一個目錄。路徑解析機制會自動在映射模塊名到path時添加上.js后綴。在文本模版之類的場景中使用require.toUrl()時它也會添加合適的后綴。

在瀏覽器中運行時，可指定路徑的備選(fallbacks)，以實現(xiàn)諸如首先指定了從CDN中加載，一旦CDN加載失敗則從本地位置中加載這類的機制。

shim: 為那些沒有使用define()來聲明依賴關系、設置模塊的"瀏覽器全局變量注入"型腳本做依賴和導出配置。

下面有個示例，它需要 RequireJS 2.1.0+，并且假定backbone.js、underscore.js 、jquery.js都裝于baseUrl目錄下。如果沒有，則你可能需要為它們設置paths config：

requirejs.config({
  //Remember: only use shim config for non-AMD scripts,scripts that do not already call define().
  //The shimconfig will not work correctly if used on AMD scripts,
  //in particular, the exports and init config will notbe triggered, and the deps config will be confusingfor those cases.
  shim: {
    'backbone': {
      //These script dependencies should be loaded before loadingbackbone.js|譯|在加載backbone.js之前應先加載它的依賴函數(shù)underscore.js和jquery.js
      deps: ['underscore', 'jquery'],
      //Once loaded, use the global 'Backbone' as themodule value.|譯|加載完畢后該模塊使用的引用名
      exports: 'Backbone'
    },
    'underscore': {
      exports: '_'
    },
    'foo': {
      deps: ['bar'],
      exports: 'Foo',
      init: function (bar) {
        //Using a function allows you to call noConflict forlibraries that support it, and do other cleanup.
        //However, plugins for those libraries may still want a global.
        //"this" for the function will be the global object.
        //The dependencies will be passed in as function arguments.
        //If this function returns a value,then that value is used as the module export valueinstead of the object found via the 'exports' string.
        //Note: jQuery registers as an AMD module via define(),so this will not work for jQuery.
        //See notes sectionbelow for an approach for jQuery.
        return this.Foo.noConflict();
      }
    }
  }
});
//Then, later in a separate file, call it 'MyModel.js', a module is defined,specifting 'backbone' as a dependency.
//RequireJS will use the shim config to properly load 'backbone' and give a local reference to this module.
//The global Backbone will still exist on the page too.
define(['backbone'], function (Backbone) {
 return Backbone.Model.extend({});
});

 RequireJS 2.0.*中，shim配置中的"exports"屬性可以是一個函數(shù)而不是字串。這種情況下它就起到上述示例中的"init"屬性的功能。 RequireJS 2.1.0+中加入了"init"承接庫加載后的初始工作，以使exports作為字串值被enforceDefine所使用。

那些僅作為jQuery或Backbone的插件存在而不導出任何模塊變量的"模塊"們，shim配置可簡單設置為依賴數(shù)組：

requirejs.config({
  shim: {
    'jquery.colorize': ['jquery'],
    'jquery.scroll': ['jquery'],
    'backbone.layoutmanager': ['backbone']
  }
});

但請注意，若你想在IE中使用404加載檢測以啟用path備選(fallbacks)或備錯(errbacks)，則需要給定一個字串值的exports以使loader能夠檢查出腳本是否實際加載了(init中的返回值不會用于enforceDefine檢查中)：

requirejs.config({
  shim: {
    'jquery.colorize': {
      deps: ['jquery'],
      exports: 'jQuery.fn.colorize'
    },
    'jquery.scroll': {
      deps: ['jquery'],
      exports: 'jQuery.fn.scroll'
    },
    'backbone.layoutmanager': {
      deps: ['backbone']
      exports: 'Backbone.LayoutManager'
    }
  }
});

"shim"配置的重要注意事項:

shim配置僅設置了代碼的依賴關系，想要實際加載shim指定的或涉及的模塊，仍然需要一個常規(guī)的require/define調(diào)用。設置shim本身不會觸發(fā)代碼的加載。

請僅使用其他"shim"模塊作為shim腳本的依賴，或那些沒有依賴關系，并且在調(diào)用define()之前定義了全局變量(如jQuery或lodash)的AMD庫。否則，如果你使用了一個AMD模塊作為一個shim配置模塊的依賴，在build之后，AMD模塊可能在shim托管代碼執(zhí)行之前都不會被執(zhí)行，這會導致錯誤。終極的解決方案是將所有shim托管代碼都升級為含有可選的AMD define()調(diào)用。（這一塊不明白~~?。。。?/p>

"shim"配置的優(yōu)化器重要注意事項:

您應當使用 mainConfigFile build配置項來指定含有shim配置的文件位置，否則優(yōu)化器不會知曉shim配置。另一個手段是將shim配置復制到build profile中。（這一塊不明白~~?。。。?/p>

不要在一個build中混用CDN加載和shim配置。示例場景，如：你從CDN加載jQuery的同時使用shim配置加載依賴于jQuery的原版Backbone。不要這么做。您應該在build中將jQuery內(nèi)聯(lián)而不是從CDN加載，否則build中內(nèi)聯(lián)的Backbone會在CDN加載jQuery之前運行。這是因為shim配置僅延時加載到所有的依賴已加載，而不會做任何define的自動裝裹(auto-wrapping)。在build之后，所有依賴都已內(nèi)聯(lián)，shim配置不能延時執(zhí)行非define()的代碼。define()的模塊可以在build之后與CDN加載代碼一并工作，因為它們已將自己的代碼合理地用define裝裹了，在所有的依賴都已加載之前不會執(zhí)行。因此記?。簊him配置僅是個處理非模塊(non-modular)代碼、遺留代碼的將就手段，如可以應盡量使用define()的模塊。

對于本地的多文件build，上述的CDN加載建議仍然適用。任何shim過的腳本，它們的依賴必須加載于該腳本執(zhí)行之前。這意味著要么直接在含有shim腳本的build層build它的依賴，要么先使用require([], function (){})調(diào)用來加載它的依賴，然后對含有shim腳本的build層發(fā)出一個嵌套的require([])調(diào)用。

如果您使用了uglifyjs來壓縮代碼，不要將uglify的toplevel選項置為true，或在命令行中不要使用 -mt。 該選項會破壞shim用于找到exports的全局名稱。

map: 對于給定的模塊前綴，使用一個不同的模塊ID來加載該模塊。

該手段對于某些大型項目很重要：如有兩類模塊需要使用不同版本的"foo"，但它們之間仍需要一定的協(xié)同。 在那些基于上下文的多版本實現(xiàn)中很難做到這一點。而且，paths配置僅用于為模塊ID設置root paths，而不是為了將一個模塊ID映射到另一個。map示例：

requirejs.config({
  map: {
    'some/newmodule': {
      'foo': 'foo1.2'
    },
    'some/oldmodule': {
      'foo': 'foo1.0'
    }
  }
});

如果各模塊在磁盤上分布如下：

foo1.0.js
foo1.2.js
some/
newmodule.js
oldmodule.js

當“some/newmodule”調(diào)用了“require('foo')”，它將獲取到foo1.2.js文件；而當“some/oldmodule”調(diào)用“`require('foo')”時它將獲取到foo1.0.js。

該特性僅適用于那些調(diào)用了define()并將其注冊為匿名模塊的真正AMD模塊腳本。并且，請在map配置中僅使用絕對模塊ID，“../some/thing”之類的相對ID不能工作。

另外在map中支持“*”，意思是“對于所有的模塊加載，使用本map配置”。如果還有更細化的map配置，會優(yōu)先于“*”配置。示例：

requirejs.config({
  map: {
    '*': {
      'foo': 'foo1.2'
    },
    'some/oldmodule': {
      'foo': 'foo1.0'
    }
  }
});

意思是除了“some/oldmodule”外的所有模塊，當要用“foo”時，使用“foo1.2”來替代。對于“some/oldmodule”自己，則使用“foo1.0”。

config:常常需要將配置信息傳給一個模塊。這些配置往往是application級別的信息，需要一個手段將它們向下傳遞給模塊。在RequireJS中，基于requirejs.config()的config配置項來實現(xiàn)。要獲取這些信息的模塊可以加載特殊的依賴“module”，并調(diào)用module.config()。示例：

requirejs.config({
  config: {
    'bar': {
      size: 'large'
    },
    'baz': {
      color: 'blue'
    }
  }
});
//bar.js, which uses simplified CJS wrapping:
//http://requirejs.org/docs/whyamd.html#sugar
define(function (require, exports, module) {
  //Will be the value 'large'
  var size = module.config().size;
});
//baz.js which uses a dependency array,
//it asks for the special module ID, 'module':
//https://github.com/jrburke/requirejs/wiki/Differences-between-the-simplified-CommonJS-wrapper-and-standard-AMD-define#wiki-magic
define(['module'], function (module) {
  //Will be the value 'blue'
  var color = module.config().color;
});

若要將config傳給包，將目標設置為包的主模塊而不是包ID:

requirejs.config({
  //Pass an API key for use in the pixie package'smain module.
  config: {
    'pixie/index': {
      apiKey: 'XJKDLNS'
    }
  },
  //Set up config for the "pixie" package, whose mainmodule is the index.js file in the pixie folder.
  packages: [
    {
      name: 'pixie',
      main: 'index'
    }
  ]
});

packages: 從CommonJS包(package)中加載模塊。

nodeIdCompat: 在放棄加載一個腳本之前等待的秒數(shù)。設為0禁用等待超時。默認為7秒。

waitSeconds: 命名一個加載上下文。這允許require.js在同一頁面上加載模塊的多個版本，如果每個頂層require調(diào)用都指定了一個唯一的上下文字符串。

deps: 指定要加載的一個依賴數(shù)組。當將require設置為一個config object在加載require.js之前使用時很有用。一旦require.js被定義，這些依賴就已加載。使用deps就像調(diào)用require([])，但它在loader處理配置完畢之后就立即生效。它并不阻塞其他的require()調(diào)用，它僅是指定某些模塊作為config塊的一部分而異步加載的手段而已。

callback: 在deps加載完畢后執(zhí)行的函數(shù)。當將require設置為一個config object在加載require.js之前使用時很有用，其作為配置的deps數(shù)組加載完畢后為require指定的函數(shù)。

enforceDefine: 如果設置為true，則當一個腳本不是通過define()定義且不具備可供檢查的shim導出字串值時，就會拋出錯誤。

xhtml: 如果設置為true，則使用document.createElementNS()去創(chuàng)建script元素。

urlArgs: RequireJS獲取資源時附加在URL后面的額外的query參數(shù)。作為瀏覽器或服務器未正確配置時的“cache bust”手段很有用。使用cache bust配置的一個示例：

urlArgs: "bust=" + (new Date()).getTime() 

在開發(fā)中這很有用，但請記得在部署到生成環(huán)境之前移除它。

scriptType: 指定RequireJS將script標簽插入document時所用的type=""值。默認為“text/javascript”。想要啟用Firefox的JavaScript 1.8特性，可使用值“text/javascript;version=1.8”。

§ 4 高級使用

§ 4.1 從包中加載模塊

RequireJS支持從CommonJS包結(jié)構中加載模塊，但需要一些額外的配置。具體地，支持如下的CommonJS包特性：

一個包可以關聯(lián)一個模塊名/前綴。
package config可為特定的包指定下述屬性：
name: 包名（用于模塊名/前綴映射）
location: 磁盤上的位置。位置是相對于配置中的baseUrl值，除非它們包含協(xié)議或以“/”開頭
main: 當以“包名”發(fā)起require調(diào)用后，所應用的一個包內(nèi)的模塊。默認為“main”，除非在此處做了另外設定。該值是相對于包目錄的。

重要事項

雖然包可以有CommonJS的目錄結(jié)構，但模塊本身應為RequireJS可理解的模塊格式。例外是：如果你在用r.js Node適配器，模塊可以是傳統(tǒng)的CommonJS模塊格式。你可以使用CommonJS轉(zhuǎn)換工具來將傳統(tǒng)的CommonJS模塊轉(zhuǎn)換為RequireJS所用的異步模塊格式。

一個項目上下文中僅能使用包的一個版本。你可以使用RequireJS的多版本支持來加載兩個不同的模塊上下文；但若你想在同一個上下文中使用依賴了不同版本的包C的包A和B，就會有問題。未來可能會解決此問題。
如果你使用了類似于入門指導中的項目布局，你的web項目應大致以如下的布局開始（基于Node/Rhino的項目也是類似的，只不過使用scripts目錄中的內(nèi)容作為項目的頂層目錄）:

project-directory/
project.html
scripts/
require.js

而下面的示例中使用了兩個包，cart及store：

project-directory/
project.html
scripts/
cart/
main.js
store/
main.js
util.js
main.js
require.js

project.html 會有如下的一個script標簽：

<script data-main="scripts/main" src="scripts/require.js"></script>

對“cart”的依賴請求會從scripts/cart/main.js中加載，因為“main”是RequireJS默認的包主模塊。對“store/util”的依賴請求會從scripts/store/util.js加載。

如果“store”包不采用“main.js”約定，如下面的結(jié)構：

project-directory/
project.html
scripts/
cart/
main.js
store/
store.js
util.js
main.js
package.json
require.js

則RequireJS的配置應如下：

require.config({
  packages: [
    "cart",
    {
      name: "store",
      main: "store"
    }
  ]
});

減少麻煩期間，強烈建議包結(jié)構遵從“main.js”約定。

§ 4.2 多版本支持

 如配置項一節(jié)中所述，可以在同一頁面上以不同的“上下文”配置項加載同一模塊的不同版本。require.config()返回了一個使用該上下文配置的require函數(shù)。下面是一個加載不同版本（alpha及beta）模塊的示例（取自test文件中）：

<script src="../require.js"></script>
<script>
var reqOne = require.config({
 context: "version1",
 baseUrl: "version1"
});
reqOne(["require", "alpha", "beta",],
function(require,  alpha,  beta) {
 log("alpha version is: " + alpha.version); //prints 1
 log("beta version is: " + beta.version); //prints 1

 setTimeout(function() {
  require(["omega"],
   function(omega) {
    log("version1 omega loaded with version: " +
       omega.version); //prints 1
   }
  );
 }, 100);
});
var reqTwo = require.config({
   context: "version2",
   baseUrl: "version2"
  });
reqTwo(["require", "alpha", "beta"],
function(require,  alpha,  beta) {
 log("alpha version is: " + alpha.version); //prints 2
 log("beta version is: " + beta.version); //prints 2
 setTimeout(function() {
  require(["omega"],
   function(omega) {
    log("version2 omega loaded with version: " +
      omega.version); //prints 2
   }
  );
 }, 100);
});
</script>

 注意“require”被指定為模塊的一個依賴，這就允許傳遞給函數(shù)回調(diào)的require()使用正確的上下文來加載多版本的模塊。如果“require”沒有指定為一個依賴，則很可能會出現(xiàn)錯誤。

§ 4.3 在頁面加載之后加載代碼

上述多版本示例中也展示了如何在嵌套的require()中遲后加載代碼。

§ 4.4 Web Worker 支持

從版本0.12開始，RequireJS可在Web Worker中運行。可以通過在web worker中調(diào)用importScripts()來加載require.js（或包含require()定義的JS文件），然后調(diào)用require就好了。

你可能需要設置baseUrl配置項來確保require()可找到待加載腳本。

你可以在unit test使用的一個文件中找到一個例子。

§ 4.5 Rhino 支持

RequireJS可通過r.js適配器用在Rhino中。

§ 4.6 處理錯誤

通常的錯誤都是404（未找到）錯誤，網(wǎng)絡超時或加載的腳本含有錯誤。RequireJS有些工具來處理它們：require特定的錯誤回調(diào)（errback），一個“paths”數(shù)組配置，以及一個全局的requirejs.onError事件。

傳入errback及requirejs.onError中的error object通常包含兩個定制的屬性：

requireType: 含有類別信息的字串值，如“timeout”，“nodefine”， “scripterror”
requireModules: 超時的模塊名/URL數(shù)組。

如果你得到了requireModules錯，可能意味著依賴于requireModules數(shù)組中的模塊的其他模塊未定義。

§ 4.6.1 在IE中捕獲加載錯

Internet Explorer有一系列問題導致檢測errbacks/paths fallbacks中的加載錯 比較困難：

IE 6-8中的script.onerror無效。沒有辦法判斷是否加載一個腳本會導致404錯；更甚地，在404中依然會觸發(fā)state為complete的onreadystatechange事件。

IE 9+中script.onerror有效，但有一個bug：在執(zhí)行腳本之后它并不觸發(fā)script.onload事件句柄。因此它無法支持匿名AMD模塊的標準方法。所以script.onreadystatechange事件仍被使用。但是，state為complete的onreadystatechange事件會在script.onerror函數(shù)觸發(fā)之前觸發(fā)。

因此IE環(huán)境下很難兩全其美：匿名AMD（AMD模塊機制的核心優(yōu)勢）和可靠的錯誤檢測。

但如果你的項目里使用了define()來定義所有模塊，或者為其他非define()的腳本使用shim配置指定了導出字串，則如果你將enforceDefine配置項設為true，loader就可以通過檢查define()調(diào)用或shim全局導出值來確認腳本的加載無誤。

因此如果你打算支持Internet Explorer，捕獲加載錯，并使用了define()或shim，則記得將enforceDefine設置為true。參見下節(jié)的示例。

注意: 如果你設置了enforceDefine: true，而且你使用data-main=""來加載你的主JS模塊，則該主JS模塊必須調(diào)用define()而不是require()來加載其所需的代碼。主JS模塊仍然可調(diào)用require/requirejs來設置config值，但對于模塊加載必須使用define()。

§ 4.6.2 require([]) errbacks

當與requirejs.undef()一同使用errback時，允許你檢測模塊的一個加載錯，然后undefine該模塊，并重置配置到另一個地址來進行重試。

一個常見的應用場景是先用庫的一個CDN版本，如果其加載出錯，則切換到本地版本：

requirejs.config({
  enforceDefine: true,
  paths: {
    jquery: 'http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min'
  }
});
//Later
require(['jquery'], function ($) {
  //Do something with $ here
}, function (err) {
  //The errback, error callback
  //The error has a list of modules that failed
  var failedId = err.requireModules && err.requireModules[0];
  if (failedId === 'jquery') {
    //undef is function only on the global requirejs object.
    //Use it to clear internal knowledge of jQuery.
    //Any modules that were dependent on jQuery and in the middle of loading will not be loaded yet,
    //they will wait until a valid jQuerydoes load.
    requirejs.undef(failedId);
    //Set the path to jQuery to local path
    requirejs.config({
      paths: {
        jquery: 'local/jquery'
      }
    });
    //Try again. Note that the above require callback
    //with the "Do something with $ here" comment will
    //be called if this new attempt to load jQuery succeeds.
    require(['jquery'], function () {});
  } else {
    //Some other error. Maybe show message to the user.
  }
});

使用“requirejs.undef()”，如果你配置到不同的位置并重新嘗試加載同一模塊，則loader會將依賴于該模塊的那些模塊記錄下來并在該模塊重新加載成功后去加載它們。

注意: errback僅適用于回調(diào)風格的require調(diào)用，而不是define()調(diào)用。define()僅用于聲明模塊。

§ 4.6.3 paths備錯配置

上述模式（檢錯，undef()模塊，修改paths，重加載）是一個常見的需求，因此有一個快捷設置方式。paths配置項允許數(shù)組值：

requirejs.config({
  //To get timely, correct error triggers in IE, force a define/shim exports check.
  enforceDefine: true,
  paths: {
    jquery: [
      'http://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min',
      //If the CDN location fails, load from this location
      'lib/jquery'
    ]
  }
});
//Later
require(['jquery'], function ($) {
});

上述代碼先嘗試加載CDN版本，如果出錯，則退回到本地的lib/jquery.js。

注意: paths備錯僅在模塊ID精確匹配時工作。這不同于常規(guī)的paths配置，常規(guī)配置可匹配模塊ID的任意前綴部分。備錯主要用于非常的錯誤恢復，而不是常規(guī)的path查找解析，因為那在瀏覽器中是低效的。

§ 4.6.4 全局 requirejs.onError

為了捕獲在局域的errback中未捕獲的異常，你可以重載requirejs.onError()：

requirejs.onError = function (err) {
  console.log(err.requireType);
  if (err.requireType === 'timeout') {
    console.log('modules: ' + err.requireModules);
  }
  throw err;
};

§ 5.加載插件

RequireJS支持加載器插件。使用它們能夠加載一些對于腳本正常工作很重要的非JS文件。RequireJS的wiki有一個插件的列表。本節(jié)討論一些由RequireJS一并維護的特定插件：

§ 5.1 指定文本文件依賴

如果都能用HTML標簽而不是基于腳本操作DOM來構建HTML，是很不錯的。但沒有好的辦法在JavaScript文件中嵌入HTML。所能做的僅是在js中使用HTML字串，但這一般很難維護，特別是多行HTML的情況下。.

RequireJS有個text.js插件可以幫助解決這個問題。如果一個依賴使用了text!前綴，它就會被自動加載。參見text.js的README文件。

§ 5.2 頁面加載事件及DOM Ready

RequireJS加載模塊速度很快，很有可能在頁面DOM Ready之前腳本已經(jīng)加載完畢。需要與DOM交互的工作應等待DOM Ready?，F(xiàn)代的瀏覽器通過DOMContentLoaded事件來知會。

但是，不是所有的瀏覽器都支持DOMContentLoaded。domReady模塊實現(xiàn)了一個跨瀏覽器的方法來判定何時DOM已經(jīng)ready。下載并在你的項目中如此用它：

require(['domReady'], function (domReady) {
 domReady(function () {
  //This function is called once the DOM is ready.
  //It will be safe to query the DOM and manipulateDOM nodes in this function.
 });
}); 

基于DOM Ready是個常規(guī)需求，像上述API中的嵌套調(diào)用方式，理想情況下應避免。domReady模塊也實現(xiàn)了Loader Plugin API，因此你可以使用loader plugin語法（注意domReady依賴的!前綴）來強制require()回調(diào)函數(shù)在執(zhí)行之前等待DOM Ready。當用作loader plugin時，domReady會返回當前的document：

require(['domReady!'], function (doc) {
  //This function is called once the DOM is ready,
  //notice the value for 'domReady!' is the currentdocument.
});

注意: 如果document需要一段時間來加載（也許是因為頁面較大，或加載了較大的js腳本阻塞了DOM計算），使用domReady作為loader plugin可能會導致RequireJS“超時”錯。如果這是個問題，則考慮增加waitSeconds配置項的值，或在require()使用domReady()調(diào)用（將其當做是一個模塊）。

總結(jié)

以上所述是小編給大家介紹的RequireJs官方使用教程，希望對大家有所幫助，如果大家有任何疑問請給我留言，小編會及時回復大家的。在此也非常感謝大家對腳本之家網(wǎng)站的支持！