RequireJS 2.0 API之配置項

轉載自http://blog.csdn.net/kevinwon1985/article/details/8155267

RequireJS 把每個依賴項當作一個script標籤，使用 head.appendChild()來加載。

RequireJS 會計算好依賴關係，按照正確的順序依次加載全部依賴項。而後才調用模塊的構造函數。 

在能同步加載模塊的服務端JS中使用 RequireJS 也很容易，只須要重定義require.load()。能夠用構建系統來作這個，服務端的 require.load 方法在build/jslib/requirePatch.js 中。

將來，這個代碼可能會被看成一個可選的模塊放到 require/ 目錄中。這樣你就能夠在基於主機環境來使用正確的加載模式。

 

配置項§ 3

當咱們在頂層頁面（或者沒有定義一個模塊的頂層腳本文件）中使用 require() ，可使用配置對象來進行配置：

<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>

而且，你能夠在require.js加載前定義一個全局的require對象，它會在require.js加載後自動應用於配置。下面的例子定義了一些依賴項，一旦require()方法調用，他們就會加載：

<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>

注意: 最好這樣寫 var require = {} 而不要這樣寫 window.require = {}, 由於後者在IE下運行不正確。

支持的配置項:

baseUrl: 查找全部模塊的根路徑。因此，在上面第一個例子中，"my/module"的 script 標籤 src="/another/path/my/module.js"。加載普通.js文件的時候， baseUrl 將不會起做用，script的src會直接使用 那些字符串，因此 a.js 和 b.js 會從HTML頁面的同級目錄中加載。

若是沒有明確的配置 baseUrl ，它的默認值是會是加載require.js的HTML頁面所在目錄。若是使用 了data-main ，那麼baseUrl會被設置成data-main指定的腳本所在目錄。

baseUrl 能夠與加載 RequireJS 的頁面是不一樣域。  RequireJS 是能夠加載跨域腳本的。 惟一的例外是，使用text! 插件加載的文本模塊：這些路徑必須與頁面是在同一個域下，至少在開發的時候是這樣的。當使用了 優化工具 後，跨域的文本模塊會被打包進來，這時就加載跨域的文本模塊了。

paths: 映射到不能直接在baseUrl下找到的模塊名。 一般， path 設置的路徑是相對於 baseUrl 的，除非 以 "/" 開頭或包含URL協議 (例如" http:")。例如上例中，"some/module" 模塊的最終生成的script標籤的src="/another/path/some/v1.0/module.js"。 path的設置不要加.js後綴，由於path也多是映射到一個目錄。 若是path映射的是一個模塊，RequireJS會自動加上.js後綴。

 

shim: 爲那些沒有使用 define() 聲明依賴項、沒有設置模塊值、老的、傳統的"瀏覽器全局"腳本配置依賴項和exports。例如 (RequireJS 2.1.0+):

requirejs.config({
    shim: {
        'backbone': {
            //These script dependencies should be loaded before loading
            //backbone.js
            deps: ['underscore', 'jquery'],
            //Once loaded, use the global 'Backbone' as the
            //module value.
            exports: 'Backbone'
        },
        'foo': {
            deps: ['bar'],
            exports: 'Foo',
            init: function (bar) {
                //Using a function allows you to call noConflict for
                //libraries 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 value
                //instead of the object found via the 'exports' string.
                return this.Foo.noConflict();
            }
        }
    }
});

//Then, later in a separate file, call it 'MyModel.js', a module is
//defined, specifying '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" 屬性也能夠配置成一個函數。這種狀況, 它的功能和上面的 "init" 屬性同樣。  "init" 屬性用於RequireJS 2.1.0+ 中，如此， exports配置的字符串值可用於 enforceDefine，也可用於類庫加載後的一些功能性工做。

 

像 jQuery 或者 Backbone 插件這種不須要導出一個模塊值的模塊，能夠用 shim 只配置一個表示依賴項的數組：

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

然而若是你想要在IE中檢測404並執行fallbacks 或者errbacks，那麼就必須配置 exports ，這樣加載器才能檢測腳本是否加載成功：

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只是配置模塊的依賴關係。須要加載 模塊的話，仍是須要用 調用require/define 。 設置shim不會觸發加載代碼。
• 確保"shim"配置的模塊只當另一個"shim"配置的模塊或者沒有依賴關係的AMD模塊的依賴模塊，而且在在他們建立一個全局變量後調用define()(好比 jQuery ，lodash)。 另外，若是你使用一個 AMD 模塊當shim配置的模塊的依賴項，打包後， 那個AMD模塊在shim配置的模塊代碼運行前可能不會被賦值 ，而且會拋出一個錯誤。 最終的解決方案是升級shim配置的模塊的代碼，加一個可選的 AMD define() 調用。

 

優化工具配置中的 "shim" 的重要注意事項:

• 你須要在 mainConfigFile打包配置 中指定shim配置項所在的配置文件。 不然，優化工具找不到 shim 配置。 另外一種作法是在打包的配置文件中保留shim配置的副本。
• 不要在shim配置中混合使用 CDN 加載。 案例：你從CDN加載jQuery，但從本地加載依賴jQuery的Backbone 。當你打包的時候，確保內置jQuery到打包的文件中而且不要從CDN加載。不然，Backbone也會被內置到打包的文件而且在 從CDN加載的jQuery加載前執行。 這是由於shim配置的模塊只是延時到依賴模塊加載完後再加載， 可是不會自動的使用define包裝。 打包後，Backbone 內置了，而來自CDN的jQuery不會被內置，Backbone 會在jQuery加載前、文件加載後執行，而不能在依賴模塊jQuery加載後再執行define包裝的代碼。 define()包裝的模塊能夠與 CDN加載的代碼一塊兒使用，由於這些模塊正確的使用了define工廠函數進行了包裝，這使得他們在依賴項加載前是不會執行的。總結: shim配置是一個爲了解決非模塊代碼，歷史代碼的方法。 用define()包裝的模塊更好。
• 若是你使用uglifyjs來壓縮你的代碼，不要設置uglifyjs的配置項toplevel 爲 true，或者在用命令行的時候不要使用參數-mt。 這些方法會破壞shim須要使用的全局變量名。

• map: 對於給定的相同的模塊名，加載不一樣的模塊，而不是加載相同的模塊。

  這種特性在某些大型項目是很是有用的。例如那種有兩套不一樣的模塊依賴兩個不一樣版本的'foo'模塊，而且這兩套模塊須要相互協做。

  這時 使用context配置來支持多版本模塊加載 是不行的。這種狀況下，  paths config 只能設置模塊的根路徑，而不是映射一個模塊到另外一個。

   

  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' 模塊中 `require('foo')` 時，加載的是 foo1.2.js ，當 'some/oldmodule' 模塊中 `require('foo')` 時，加載的是 foo1.0.js。

  這個特性只在使用 define()包裝的AMD模塊時纔有效，而且必須是匿名模塊。

   map的值也能夠是"*"，表示全匹配，即全部模塊遵循這一設置。若是還有其餘匹配項，將會比"*"的配置優先級高。例如:

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

  在`require('foo')` 時，除了"some/oldmodule" 中會加載 "foo1.0"， 其餘模塊都加載"foo1.2" 。

  config: 傳遞一個配置信息到模塊中是一個常見的需求。這個配置信息一般是應用的一部分，咱們須要把它傳遞到模塊中。 在 RequireJS 中，requirejs.config()中的config 配置項 就是爲了解決這個需求。 模塊中能夠經過內置依賴模塊"module" ，經過調用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;
  });

   

  packages: 配置從CommonJS 包來加載模塊。詳見 packages topic。

  waitSeconds: 放棄加載腳本前的等待的秒數。 設置爲 0 則禁用此功能。默認是 7 秒。

  context: 加載上下文配置(require.config的對象)的名字。 只要頂級 require調用指定一個惟一context字符串，require.js就能夠在一個頁面中加載多個版本的模塊。要正確的使用它，參考 Multiversion Support 。

  deps: 須要加載的依賴項的數組。當在require.js加載前使用全局 require對象來定義配置的時候頗有用，也能夠在require()必定義後就立刻加載指定依賴項的時候用。

  callback: 全部依賴項加載後執行的回調函數。 當在require.js加載前使用全局 require對象來定義配置的時候頗有用，也能夠用在require.config中。

  enforceDefine: 若是設置爲true， 當加載的腳本是沒用define()包裝過，且在shim配置中沒有配置exports值時會拋錯。 詳見 Catching load failures in IE 。

  xhtml: 若是設置爲 true，requireJS 將使用document.createElementNS() 來建立script標籤。

  urlArgs:RequireJS 用來匹配資源的額外的 URL的查詢參數 。一般的用法是在瀏覽器或者服務器配置不對的時候禁用緩存。例如:

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

  這在開發的時候頗有用，可是在部署的時候最好刪除它。

  scriptType:  設置 RequireJS生成的 script 標籤的 type屬性值。默認是"text/javascript"。 可設置爲"text/javascript;version=1.8" 來使用Firefox's JavaScript 1.8特性。