在学习Dojo的时候,第一个问题就是加载器的原理,但在看dojo.js这个加载器的源码的时候,因为没有基础,只知道AMD的规范require 及 define. 所以没办法理清楚整个加载器的代码结构。所有先学习如何来使用 AMD规范才是首要任务,在去学习dojo loader原理,在去学习源代码实现,所以有了这遍文章。
Dojo 已经支持模块用AMD规范来写, 通过这种方式,模块更注意书写及调试,本教程中, 我们将学习所有关于这个新的模块格式,及如何在自己的应用里面使用它。
* 本教程是在 AMD 加载器基础教程之后,所以首先请确定你已经了解了基础 的AMD规范。
贯穿整个教程,我们都将参考一个假设的应用程序, 它的文件结构如下
/ index.html js/ lib/ dojo/ dijit/ dojox/ my/ util/
就像你看到的,整个文件结构跟 上一个教程讨论的不一样。 所以为了更好的使 loader工作,我们将学习如何配置loader. 但首先让我们在学习一下 require 及define更多的功能。
探究更深层次的require
- configuration(可选,默认为 undefined): 一个loader的配置对象, 它允许你在运行的时候重新配置loader.
- dependencies(可选,默认为 空数组[]): 一个包含模块标识符的数组, 如果指定了这个参数, 这些模块会在你的代码运行前被解析。 它们会依据有列表里的顺序加载,也按照列表里的顺序作为参数传递给回调函数。
- 回调函数: 一个函数,里面包含你想要运行的代码,这个函数依赖的模块在会上一个参数dependencies指定。 为了支持异步加载及能够使用这些代码的非全局引用,所以你必须将代码封装在这个回调函数里面。
require({ baseUrl: "/js/",packages: [ { name: "dojo",location: "//ajax.googleapis.com/ajax/libs/dojo/1.9.2/" },{ name: "my",location: "my" } ] },[ "my/app" ]);
在这里,我们稍稍的改变了loader的配置,将原本指向本地的包dojo(js/lib/dojo)指向了 google 的CDN. 跨域加载在AMD格式中隐式的实现。
探究更深层次的define
// in "my/nls/common.js" define({ greeting: "Hello!",howAreYou: "How are you?" });
记住,如果你定义的模块没有使用工厂函数, 你将不能引用任何其它依赖的模块。 所以此类形的模块定义很少使用,仅被用于i18n或者简单的定义配置对象。
loader 是如何工作的?
配置Loader
<script data-dojo-config="async: true" src="js/lib/dojo/dojo.js"></script>除非你只想使用同步模式,否则你应该养成上面的输写习惯。下一步我们需要配置一些让loader知道我们模块在哪里的信息。
var dojoConfig = { baseUrl: "/js/",//服务器绝对路径,如果需要相对于index.html,请指定为./js/ tlmSiblingOfDojo: false,location: "lib/dojo" },{ name: "dijit",location: "lib/dijit" },{ name: "dojox",location: "lib/dojox" },location: "my",main: "app" } ] };
* 记住,你必须在加载dojo.js之前设置dojoConfig变量, 如果你还不了解, 可以参考 Dojo 配置教程 .
/js/my/widget/Person.js它允许我们在文件系统里方便的存储,只需设定一个根目录,其它的部分只要相对于根baseUrl就行了。 而不需要每次都是 require(['js/my/widget/Person'],我们可以简单如 require(["my/widget/Person"])。
/ js/ dojo/ dijit/ dojox/ my/ util/
这样,你就不需要去配置baseUrl 或者 tlmSiblingOfDojo,你的顶级模块(top-level modules) 就跟包含dojo.js的文件夹同级(如模块app.js位于my文件夹内,而你没有设置baseUrl,那么,你可以在index.html 直接require(["my/app"]),dojo与dojox同样的道理 require(['dojo/dom']))。 top-level modules siblings of dojo 的简写为tlmSiblingOfDojo。
- name: 包的名称. 它应该与模块组的文件夹名称相同
- location: 包的路径; 可以是一个相对于baseUrl的相对路径,也可以是一个绝对路径。 我们更希望于从dojo package来加载模块,而不是路径的方式如”dojo/dom" 而不是"lib/dojo/dom"(再看看本文开头的文件结构), 所以我们指定dojo包的 location属性为"lib/dojo". 它会告知loader,试图加载"dojo/dom"模块都应该是加载"/js/lib/dojo/dom.js"文件(记住, baseUrl "js" 文件夹会被添加到文件名的前面)
- main (可选,默认为 main.js): 如果只是指定了包的名字,那么指定的这个文件会被当成包的入口文件。 例如, 如果你请求”dojo",那么实际被加载的文件是"js/dojo/main.js". 由于我们在"my" package 里面重写了这个属性, 如果有人请求"my",他们将实际加载的是 "js/my/app.js".
使用可移值性模块
dojoConfig = { packages: [ { name: "dojo16",location: "lib/dojo16" },{ name: "dijit16",location: "lib/dijit16" },{ name: "dojox16",location: "lib/dojox16" },{ name: "dojo",{ name: "myOldApp",location: "myOldApp" },location: "my" } ],map: { myOldApp: { dojo: "dojo16",dijit: "dijit16",dojox: "dojox16" } } };
这里发生了什么?
你可以参考AMD 配置文档来了解更多map信息
* 如果你已经对loader比较熟悉,特别是packageMap 已经被弃用。 map配置方法是新的使用方法。
创建可移值性的模块
// in "my/widget/NavBar.js" define([ "dojo/dom","my/otherModule","my/widget/InfoBox" ],function(dom,otherModule,InfoBox){ // … });
将请求 "my package"包内的模块, 使用相对模块标识符替换:
// in "my/widget/NavBar.js" define([ "dojo/dom","../otherModule","./InfoBox" ],InfoBox){ // … });
- "dojo/dom" 是另外一个包, 所以我们必须使用标识符全称.
- "my/otherModule" 是一个上级目录, 所以我们使用 "../"
- "my/widget/InfoBox" 是在同一个同录,所以我们使用"./" . ( 如果你仅指定 " InfoBox" 为一个包名,所以你标识符必须以"./" 开头。
考虑一下同一个包中相对标识符的限制。 首先让我们回顾一下map的例子, 你有发现哪有错误吗? 简单的讲,我们只关注了自己写的应用程序使用新老两个版本(myOldApp 使用dojo16,app使用dojo)。 然而我们忽视了一个重要的事情,库的依赖 - dijit 依赖 Dojo,DojoX依赖Dojo及Dijit. 以下的配置将会确保这些依赖可以得到解析。 为了安全起见, 我们也将包映射到了他们自己(map:{ dojo16: {dojo:"dojo16"}}) ,在这种情况下的任何模块都不能使用相对标识符(测试了下,好像可以使用相对标识,不知道说的是什么样的一个情况)。
var map16 = { dojo: "dojo16",dojox: "dojox16" }; dojoConfig = { packages: [ { name: "dojo16",map: { dojo16: map16,dijit16: map16,dojox16: map16,myOldApp: map16 } };
有条件加载模块
有时,你想在满足某条件的情况在加载一个模块。 例如, 你可能想在一个事件(点击)发生后在延迟加载一个模块(不是一开始加载)。 这很简单,如下所示:// in "my/debug.js" define([ "dojo/dom","dojo/dom-construct","dojo/on" ],domConstruct,on){ on(dom.byId("debugButton"),"click",function(){ require([ "my/debug/console" ],function(console){ domConstruct.place(console,document.body); }); }); });
上面代码不好的就是可移性不好,所以需要将”my/debug/console ” 转化为相对路径。 仅仅是将"my/debug/console"变为"./debug/console"又不能使require工作, 因为当require被调用的时候原来模块的上下文已经丢失。 为了解决这个问题, Dojo loader 提供了一个上下文加载器 (context-sensitive require). 使用时,需要在define 的依赖列表中指定一个特别的模块标识符"require".
// in "my/debug.js" define([ "dojo/dom","dojo/on","require" ],on,require){ on(dom.byId("debugButton"),function(){ require([ "./debug/console" ],document.body); }); }); });
现在,内部的require的调用使用内部绑定,可以安全模块在"my/deubg"中使用相对路径来加载模块。
* 上下文为什么会丢失?
记住, require是一个全局定义的函数。 当你执行"click"时, 唯一的上下文是定义"click"事件模块的作用域,它不知道模块是什么. 在局部作用域内没有require函数, 所有全局的require函数会被调用。 回忆下我们之前说的文件结构, 如果我们传递"./debug/console" 给到全局的require,它将试着去加载" js/debug/console.js",但不存在这个文件。
当你使用content-sensitive require(上下文require),我们可以局部的引用一个修改的require函数,它可以维持模块的上下文环境, 所以它能正确的加载"/js/my/debug/console.js".
Content-sensitive require 也可以为一个模块来用来加载资源(图片,模板, css)。 如以下的文件结构
/ js/ my/ widget/ InfoBox.js images/ info.png
在 InfoBox.js 内,我们可以通过调用require.toUrl来获得"info.png"的完整路径,然后将图片的src设置为这个路径。
处理循环依赖
// in "my/moduleA.js" define([ "./moduleB" ],function(moduleB){ return { getValue: function(){ return "oranges"; },print: function(){ // dependency on moduleB log(moduleB.getValue()); } }; }); // in "my/moduleB.js" define([ "./moduleA" ],function(moduleA){ return { getValue: function(){ // dependency on moduleA return "apples and " + moduleA.getValue(); } }; }); // in "index.html" require([ "my/moduleA" ],function(moduleA) { moduleA.print(); });
看起来会输出" apples and oranges",但是你反而获得一个发生在moduleB的错误: Object has no mathod ' getValue',看看在运行"index.html"后, loader会做些什么。
- 解析传递给require的依赖(在index.html)的模块: moduleA
- 解析moduleA的依赖:moduleB
- 解析moduleB的依赖:moduleA
- 检测加载器当前正在尝试处理解析moduleA(即发现这是循环调用)
- 临时地将解析moduleA设置为空数组,退出循环依赖
- 通过调用moduleB的工厂函数,恢复moduleB的解析。 代表moduleA的空对象会被传到给工厂函数。
- 设置moduleB的引用为工厂函数返回的值。
- 通过调用moduleA的工厂函数,继续moduleA的解析。
- 设置moduleA的引用为工厂函数的返回值, 虽然整个loader现在引用了一个有效的值。但是moduleB依然引用的是一个空对象。
- 执行moduleA.print - 由于moduleB 只是引用到一个空对易用。 当调用moduleA.getValue时会获得一个错误。
// in "my/moduleA.js" define([ "./moduleB","exports" ],function(moduleB,exports){ exports.getValue = function(){ return "oranges"; }; exports.print = function(){ log(moduleB.getValue()); }; }); // in "my/moduleB.js" define([ "./moduleA" ],function(moduleA){ return { getValue: function(){ return "apples and " + moduleA.getValue(); } }; }); // in "index.html" require([ "my/moduleA" ],function(moduleA) { moduleA.print(); });
现在当你运行index.html 会发生什么?
- 解析传递给require函数的依赖: moduleA
- 解析 moduleA的依赖: moduleB
- 解析 moduleB的依赖:moduleA
- 检测加载器当前正在尝试处理解析moduleA(即发现这是循环调用)
- 临时地将解析moduleA设置为空对象,退出循环依赖
- 通过调用moduleB的工厂函数,恢复moduleB的解析。 代表moduleA的空对象(持久化对象,跟上一个例子不同的一个对象)会被传到给工厂函数
- 设置moduleB的引用为工厂函数返回的值。
- 通过调用moduleA的工厂函数,继续执行模块A - 已经创建好的moduleA的占位符对象会作为exports参数,传递给工厂函数。
- 在解析完一个含及”exports"的依赖关系的模块后(moduleA),loader对这个模块的引用不在是工厂函数返回的值,而是moduleA的那个已经被创建占位符并当作exports参数传递给moduleA工厂函数创建的对象。
- 执行moduleA.print - 由于moduleB 含 有一个有效的被moduleA填充的引用。 当它调用moduleA.getValue时,会被正确执行。
// in "my/moduleA.js" define([ "./moduleB",exports){ exports.isValid = true; exports.getValue = function(){ return "oranges"; }; exports.print = function(){ // dependency on moduleB log(moduleB.getValue()); } }); // in "my/moduleB.js" define([ "./moduleA" ],function(moduleA){ // this code will run at resolution time,when the reference to 这段代码将运行在模块解析时, 这时引用的模块A为一个空对象,所以moduleA.isValid 是一个undefined. // moduleA is an empty object,so moduleA.isValid will be undefined if(moduleA.isValid){ return { getValue: function(){ return "won't happen"; } }; } // this code returns an object with a method that references moduleA 这段代码将会返回一个引用了moduleA的方法的对象,getValue不能在moduleA没有被实际解析之前调用。 由于模块A中使用了exports. 所以可以调用moduleA的getValue()方法. // the "getValue" method won't be called until after moduleA has // actually been resolved,and since it uses exports,the "getValue" // method will be available return { getValue: function(){ return "apples and " + moduleA.getValue(); } }; }); // in "index.html" require([ "my/moduleA" ],function(moduleA) { moduleA.print(); });
加载非AMD规范的代码
- 以 "/" 开头的标识符
- 以协议开头的标识符(如”http:","https")
- 标识符以".js" 结尾
// in "my/legacyModule.js" dojo.provide("my.legacyModule"); my.legacyModule = { isLegacy: true };
服务器端Javascript
# node.js: node path/to/dojo.js load=my/serverConfig load=my/app # rhino: java -jar rhino.jar path/to/dojo.js load=my/serverConfig load=my/app
查看更多 dojo and nodejs 教程