使用dojoConfig配置Dojo

dojoConfig对象(原来是djConfig)允许你设置toolkit各方面的选项值和默认行为。本教程我们将探索哪些是可以的和如何把dojoConfig用到你的代码中。

介绍

dojoConfig对象(在Dojo1.6之前称为djConfig)是主要的配置Dojo途径，它被模块loader引用，也作为Dojo组件的全局选项。如果需要，它可以进一步被自定义应用程序配置点使用。

不赞成使用老的对象名djConfig，但仍然可用，这两种写法是等效的，我们鼓励使用新的dojoConfig。

准备开始

我来通过一些简单的示例来知道dojoConfig实际如何工作。一个直接设置dojoConfig的示例如下：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

<!--setDojoconfiguration,loadDojo--> < script > dojoConfig={ has:{ "dojo-firebug":true }, parseOnLoad:false, foo:"bar", async:true }; </ script > < script src = "//ajax.googleapis.com/ajax/libs/dojo/1.8.1/dojo/dojo.js" ></ script > < script > //Requiretheregistry,parser,Dialog,andwaitfordomReady require(["dijit/registry","dojo/parser","dojo/json","dojo/_base/config","dijit/Dialog","dojo/domReady!"] ,function(registry,JSON,config){ //Explicitlyparsethepage parser.parse(); //Findthedialog vardialog=registry.byId("dialog"); //Setthecontentequaltowhatdojo.configis dialog.set("content","< pre >"+JSON.stringify(config,true)+"</ pre >"); //Showthedialog dialog.show(); }); </ script > <!--andlaterinthepage--> < div id = "dialog" data-dojo-type = "dijit.Dialog" data-dojo-props = "title:'dojoConfig/dojo/_base/config'" ></ div >

查看演示

注意先定义dojoConfig再载入dojo.js，这非常重要。

这个例子中我们设置了3个标记：parseOnLoad:false,has(dojo-firebugsub-property)和async:true，此外定义了一个自拟定特性：foo:"bar"。为了演示，一个dijit.Dialog已经放置在页面当中。require的回调函数转化dojo.config的值为JSON字符串并且放在dialog中显示。在运行结果中看我们的特性：parseOnload，has和foo，但是也有其他的，这与实际情况有关，示例页面使用跨域和Google-CDN-hosted里的Dojo1.8版本。

重要的一点是dojoConfig和dojo/_base/config之间的区别，dojoConfig纯粹是为了输入——它被用来把配置参数传递给loader和模块。在引导过程中，dojo/_base/config记录这些参数以便模块代码以后使用。

这里有一个类似的例子：

1 2 3

<scriptsrc= "//ajax.googleapis.com/ajax/libs/dojo/1.8.1/dojo/dojo.js" data-dojo-config= "has:{'dojo-firebug':true},parseOnLoad:false,foo:'bar',async:1" > </script>

查看示例

在本例中,我们同样的使用data-dojo-config属性在Dojo脚本元素,您已经在其他教程和例子见过。这是与前面的示例功能完全相同。在这两种情况下,我们提供配置选项最终混合到dojo/_base/object对象，在dojo.js载入中，它们可以重新取回在引导过程之后。

你可以证实这一点通过设立一些新的values在dojoConfig里，并检查dojo.config对象。所以，dojoConfig是一个通用的Dojo配置属性包。让我们看看都有哪些选项，我们如何使用它们。

has()配置

一个Dojo1.7中添加的主要特色是使用has()模式进行特性检测，通过包含一个对象特性的散列值做为has的特性，我们可以在dojoConfig中指定has()的特性设置。这个特性设置是为了决定Dojo支持的某一能力。例如，我能够禁用amd工厂扫描(扫描模块用于CommonJSrequire(模块)语句加载的依赖项)：

1 2 3 4 5 6 7

< script > dojoConfig={ has:{ "dojo-amd-factory-scan":false } }; </ script >

Debug/FirebugLite配置

你也许从其他教程中熟悉isDebug设置标志或者在Dojo1.7之前使用过启用debug信息。Dojo1.7和1.8里，has()的特性也做了更高级别的同样规定。为了在老版本的IE中启用FirebugLite辅助调试，我们可以设置dojo-firebug特性（isDebug仍然可以启用它，但是使用特性，在异步模式中将更快加载）。如果你有Firebug或者其他console(控制台)可用，它什么事都不做。但是如果你没有console，他将载入Dojo的FirebugLite版本，并且创建一个consoleUI在页面底部，这可以方便在早期的IE中或者其他不支持调试的浏览器中调试。

要启用调试消息的过时和实验性功能，我们可以我们可以设置dojo-debug-messages为ture(这个默认值是false，除非你设置了isDebug)。如果这个特征设置为false，警告消息将被禁止。启用开发者console(浏览器自带或者使用FirebugLite)和调试信息日志的例子：

1 2 3 4 5 6 7 8

< script > dojoConfig={ has:{ "dojo-firebug":true, "dojo-debug-messages":true } }; </ script >

禁用一个guaranteedconsole对象，我们可以设置dojo-guarantee-console特性设为false。这个功能默认为true，如果必要将创建一个虚拟控制台对象，这样任何console.*的消息语法在您的代码中将安全地和稳定地执行不会抛出异常。

为了进一步在页面中设置console，下面附加的选项是可以使用的：

• debugContainerId:指定一个特定的元素去包含consoleUI。

• popup:使用弹出窗口而不是在当前窗口中显示console。

Loader配置

在Dojo1.7中，为了适应新的AMD模块格式，Dojo使用一个新的loader。这个新的loader添加了一些新的配置选项，这些是至关重要的，它能够定义包裹，别名或者更多。更多关于新loader的介绍，可以查看HelloDojotutorial。重要的loader配置参数包括：

• baseUrl:当转化一个模块标识符为地址或者URL时，baseUrl将添加给它。

1	baseUrl: "/js"

• packages:一个对象数组，它提供了包裹名字和位置。

1 2 3 4

packages:[{ name: "myapp" , location: "/js/myapp" }]

• aliases:允许你设置模块的别名。

1 2 3 4

aliases:[ //[aliasname,truename] [ "cookie" , "dojo/cookie" ] ]

• paths:允许自定义路径。

1 2 3

paths:{ "text" : "./text" }

• packagePaths:速记符号，可以用来指定多个相同根目录的包裹配置。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

//ShorthandusingpackagePaths: packagePaths:{ "path/to/some/place" :[ "package1" , { name: "package2" , main: "base" } ] } //...isequivalentto: packages:[{ name: "package1" , location: "path/to/some/place/package1" },{ name: "package2" , location: "path/to/some/place/package2" }]

• async:定义Dojo核心是否异步加载，可以设置为true,false或legacyAsync,这使得loader永久处在legacy跨域模式。

1	async: true

• parseOnLoad:如果为true，当DOM和所有初始依赖项(包含在dojoConfig.deps数组中)被载入后使用dojo/parser解析页面。

1	parseOnLoad: true

推荐设置为false(或者省略这个属性)，然后开发者明确的引用dojo/parser调用parser.parse()。

• deps:一个应该在Dojo载入完成后立即载入的资源路径数组。

1	deps:[ "dojo/parser" ]

• callback:一个在deps被取出后执行的回调函数。

1 2 3

callback: function (parser){ //Usetheresourcesprovidedhere }

• waitSeconds:等待加载模块超时时间，默认为0(永远等待)。

1	waitSeconds: 5

• cacheBust:如果为true，添加时间值到每个模块URL中作为querystring避免模块缓存。

1	cacheBust: true

现在让我们创建一个简单的示例，并使用一些基本的参数。一个非常普遍的方案是使用CDN中的DojoToolkit和本地的模块。我们使用了GoogleCDN和/documentation/tutorials/1.8/dojo_config/demo空间里的模块：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

<!--ConfigureDojofirst--> <script> dojoConfig={ has:{ "dojo-firebug" : true , "dojo-debug-messages" : true }, //Don'tattempttoparsethepageforwidgets parseOnLoad: false , packages:[ //Anyreferencestoa"demo"resourceshouldloadmoduleslocally,*not*fromCDN { name: "demo" , location: "/documentation/tutorials/1.8/dojo_config/demo" } ], //Timeoutafter10seconds waitSeconds:10, aliases:[ //Insteadofhavingtotype"dojo/domReady!",wejustwant"ready!"instead [ "ready" , "dojo/domReady" ] ], //Get"fresh"resources cacheBust: true }; </script> <!--LoadDojo,Dijit,andDojoXresourcesfromGoogleCDN--> <scriptsrc= "//ajax.googleapis.com/ajax/libs/dojo/1.8.1/dojo/dojo.js" ></script> <!--Loada "demo" module--> <script> require([ "demo/AuthoredDialog" , "dojo/parser" , "ready!" ], function (AuthoredDialog,parser){ //Parsethepage parser.parse(); //Dosomethingwithdemo/AuthoredDialog... }); </script>

通过使用packages配置，我们获得了所有指向本地/documentation/tutorials/1.8/dojo_config/demo/文件夹的demo/*引用，而且允许使用任何GoogleCDN中的dojo，dijit和dojox引用。如果没定义demo包裹，请求将会通过//ajax.googleapis.com/ajax/libs/dojo/1.8.1/dojo/demo/AuthoredDialog.js.。同样的我们使用alias把ready和dojo/domReady两个名称结合一起。

查看演示

documentationaboutthenewloader提供了更多新loader的细节。

新的loader同样支持legacydojo.require()加载资源和modulePaths这样的配置属性，在sametutorialforDojo1.6中有讲解，因此开发者可以安全的升级现有程序不必担心。

区域设置和国际化

Dojo'si18n系统有自己权利证明文档，和拥有有价值的教程。但是我们在这提到只为重复说明dojoConfig的工作方式。

你可以在dojoConfig中使用Dojo'si18n组件为任何widgets或者局部内容进行配置。locale(区域设置)选项允许你通过浏览器重写Dojo的默认值。一个简单的演示展示了它的工作：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

<script> var dojoConfig={ has:{ "dojo-firebug" : true , "dojo-debug-messages" : true }, parseOnLoad: true , //lookforalocale=xxquerystringparam,elsedefaultto'en-us' locale:location.search.match(/locale=([\w\-]+)/)?RegExp.$1: "en-us" }; </script> <scriptsrc= "//ajax.googleapis.com/ajax/libs/dojo/1.8.1/dojo/dojo.js" ></script> <script> require([ "dojo/date/locale" , "dijit/Dialog" , "dojo/json" , "dojo/_base/config" , "dojo/_base/window" , "dojo/i18n" , "dojo/domReady!" ] , function (locale,config,win){ var now= new Date(); var dialog= new Dialog({ id: "dialog" , //setatitleonthedialogoftoday'sdate, //usingalocalizeddateformat title: "Today:" +locale.format(now,{ formatLength: "full" , selector: "date" }) }).placeAt(win.body()); dialog.startup(); dialog.set( "content" , "<pre>" +JSON.stringify(config, true )+ "</pre>" ); dialog.show(); }); </script>

演示dojo.config.locale='zh'(Chinese)

示例中，我们定义了config对象的locale特性，并找到querystring的locale=xx参数。这只是演示，通常你可能硬编码locale。提前设置locale在任何模块加载之前，确保正确的局部消息绑定在需要加载的依赖项上。在这个例子里，我们使用dojo/date/locale模块格式化一个时间对象，把它作为字符串用于Dialog标题。

对于多语言的页面，你需要加载绑定了浏览器或者dojoConfig.locale特性指定的locales的资源。这种情况下，使用extraLocale配置特性和带有一个locale名字的字符串数组。

自定义特性

因为dojo.config一直是已知的，它是提供页面配置的逻辑位置，多个其他Dojo模块使用它们自己特别的配置特性。我们看Dijit中，特别是在DojoX，它们的模块标志和行为是可以被设置的：

• DijitEditor

allowXdRichTextSave

• dojoxGFX

dojoxGfxSvgProxyFrameUrl,forceGfxRenderer,gfxRenderer

• dojox.htmlmetrics

fontSizeWatch

• dojox.iotransportsandplugins

xipClientUrl,dojoCallbackUrl

• dojox.image

preloadImages

• dojox.analyticsplugins

sendInterval,inTransitRetry,analyticsUrl,sendMethod,maxRequestSize,idleTime,watchMouseOver,sampleDelay,targetProps,windowConnects,urchin

• dojox.cometd

cometdRoot

• dojox.form.FileUploader

uploaderPath

• dojox.mobile

mblApplyPageStyles,mblHideAddressBar,mblAlwaysHideAddressBar,mobileAnim,mblLoadCompatCssFiles

它能够在dojox模块使用，同样也可以在你自己的应用程序和模块中使用。dojoConfig是一个理想的位置去提供给行为和页面或者应用程序配置特性。考虑下面的代码：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

<script> dojoConfig={ has:{ "dojo-firebug" : true }, app:{ userName: "Anonymous" } }; </script> <scriptsrc= "//ajax.googleapis.com/ajax/libs/dojo/1.8.1/dojo/dojo.js" ></script> <script> require([ "dijit/Dialog" , "dijit/registry" , "dojo/_base/lang" , "dojo/json" , "dojo/io-query" , "dojo/domReady!" ] , function (Dialog,registry,lang,ioQuery){ //pullconfigurationfromthequerystring //andmixitintoourappconfig var queryParams=ioQuery.queryToObject(location.search.substring(1)); lang.mixin(config.app,queryParams); //Createadialog var dialog= new Dialog({ title: "Welcomeback" +config.app.userName, content: "<pre>" +JSON.stringify(config, true )+ "</pre>" }); //Drawontheappconfigtoputupapersonalizedmessage dialog.show(); }); </script>

查看应用程序配置演示

这个例子里，我们添加给dojoConfig一个"app"特性，我们可以在后面通过dojo.config引用它，提供给Dialog一个个性化的问候。有许多方式填充dojoConfig.app。它可以预先设置合适的默认值，然后在后来混入特殊的值。在生产中，dojoConfig可能被写在服务器端。另外你可能通过cookie使用JSON格式的值填充它，或者在我们前面的例子——你可以从querystring中提取配置数据。在开发和测试模式，你可以使用一个模版提供假定的值，或者载入一个脚本或模块填充它。

结语

在本教程中，我们讨论了许多常见填充dojo.config的方式——通过dojoConfig或data-dojo-config——并了解它的值如何影响行为和提供特性给Dojo模块。

dojo.config在Dojo引导和生命周期中，是一个很好的定义位置和角色，这意味着同样的概念也适用于Dojo模块甚至你自己的模块和应用程序中是用它。