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模块甚至你自己的模块和应用程序中是用它。
