Dojo 1.10 教程(2)-基础入门篇dojoConfig配置

本篇教程翻译自dojo官网上的dojo1.10教程，中间对部分内容进行了酌情增删，限于个人水平，如果有什么地方翻译不到位或者理解上出了偏差，敬请指出，谢谢!@H_502_5@
转载请注明出处。

@H_502_5@

原文地址:ConfiguringDojo with dojoConfig@H_502_5@

序言@H_502_5@
dojoConfig对象(以前是djConfig)允许你为dojo设置一些默认的选项。在这篇教程里将会为大家说明如何在你的代码里面使用。

介绍@H_502_5@
使用(1.6版本之前是叫djConfig)是在页面中或者应用中主要的配置Dojo的方法。就像的那些可以全局使用的模块一样，它被模块加载器所引用。如果有这方面的要求的话，在一般的应用中，它可以作为一个配置点。

旧的对象名已经弃用了，但是在任何使用Dojo2.0之前版本的代码中都支持，之后的版本将不再支持。在写这篇教程的时候，大多数的文档依旧在用对象，这两种写法是等价的。但是建议最好从现在起就开始使用。

开始@H_502_5@

让我们来通过一些简单的例子来说明在实践中是如何使用的。一共有两种方式。

下面是第一种配置的示例:

<!-- set Dojo configuration,load Dojo-->
<script>
    dojoConfig= {
        has: {
            "dojo-firebug": true
        },parSEOnLoad: false,foo: "bar",async: true
    };
</script>
<scriptsrc="//ajax.googleapis.com/ajax/libs/dojo/1.10.1/dojo/dojo.js"></script>
 
<script>
// Require the registry,parser,Dialog,andwait for domReady
require(["dijit/registry","dojo/parser","dojo/json","dojo/_base/config","dijit/Dialog","dojo/domReady!"],function(registry,JSON,config) { purely
    // Explicitly parse the page
    parser.parse();
    // Find the dialog
    vardialog = registry.byId("dialog");
    // Set the content equal to whatdojo.config is
    dialog.set("content","<pre>"+ JSON.stringify(config,null,"\t") + "</pre>");
    // Show the dialog
    dialog.show();
});
</script>
 
<!-- and later in the page -->
<divid="dialog"data-dojo-type="dijit/Dialog"data-dojo-props="title: 'dojoConfig /dojo/_base/config'"></div>

需要注意的是定义了的script标签是放在了dojo.js文件之前，这点格外的重要--如果弄反了，配置信息就会被忽略掉。

在这个例子中，我们设置了三项内容:parSEOnLoad: false,has(dojo-firebug的子属性),以及async: true。此外，还指定了一个惯例属性:foo: "bar".对于这个例子，一个dijit/Dialog组件被放在了页面中，requirecallback函数将的内容转换成了json格式，并放在了dialog中以便展示。在页面结果中能看到当初配置的属性信息:parSEOnLoad,hasfoo。但是也包含了一些其他的配置信息，这些额外的配置信息表明了示例页面使用了跨域以及google CDN上的dojo1.10。

下面是第二种配置dojoConfig的示例:

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

在这个例子中，我们在 script 标签中使用了 data-dojo-config 属性，这在功能上和第一种配置方式没有任何区别。在这两个例子中，配置参数将会被加入 dojo/_base/config 对象中。这点你可以通过在 dojoConfig 中加入一些新的值，然后在控制台检查 dojo.config 对象来进行确认。

has() 配置@H_502_5@

has()是Dojo1.7+版本加入的一项新的特性。我们可以在通过在中向has属性加入一组对象来为它指明自己的特征。这种设置方式如今已经被用来在中定义一些确定支持的功能。例如，我们可以使用如下的方式来关闭amd模块扫描:

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

Debug/Firebug Lite配置@H_502_5@

通过其它系列的教程，或者使用过是Dojo1.7之前的版本，也许你现在对isDebug这个属性已经比较熟悉，它是用来开启debug模式。在1.7+的版本，模式也可以通过在更高的粒度上进行声明。在旧版本的浏览器上使用Firebug Lite来开启，我们需要设置dojo-firebug(也能来加载这些，但是使用这种方式可以在异步的模式下更早的加载模式。在开启模式之后，如果你有Firebug或者是其他的控制台并且打开了，那么不会在进行任何额外的操作。但是如果你没有这样的一个控制台，它将会加载，并在页面的底部创建一个控制台窗口。这在老版本的IE或者是其它的没有很好的开发者工具的浏览器下很是有帮助。

为那些测试版的或者是已经弃用了的专题显示信息，我们可以将dojo-debug-message设置为true(默认的是false，除非你已经设置了isDebug)，如果这一项被设置成了，那么那些警告信息就不会再显示出来。如下例子是开启开发者控制台浏览器自带的或者是使用自身的Firebug Lite)并显示信息:

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

如果要禁用控制台，那么可以将 dojo-guarantee-console 选项设置为 false 。这个选项默认为 true ，设置为的时候，如果需要的话它会创建出一个虚拟的控制台以便你的代码里的任何 console.* 的日志信息都安全安静的执行而不会抛出任何的异常。

下面的这些额外的选项能够更大程度的配置这个页面的内的控制台:

301

页面

加载配置@H_502_5@

Dojo1.7采用了一种新的加载器来适应新的AMD规范。这个新的加载器新增了很多新的很重要的配置选项，这些配置选项包括了定义packages、maps等等。详情请见在后面系列的教程中会有说明，也可以去官网查看原教程。这些比较重要的配置选项如下:

baseUrl:在根据模块id去寻找相应模块的时候，指定寻找的根路径。

</pre><pre name="code" class="html">baseUrl: "/js"

packages：一个提供了packagename 和这个package对应的路径的对象数组。

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

map:允许你将模块id映射到不同的路径。

<span style="font-family: Arial,sans-serif;"></span>

//PS:意思就是在dijit16这个模块里面，dojo指的就是dojo16这个模块。如果还不明白，在后面马上就会有一个综合的例子
map: {
    dijit16: {
        dojo: "dojo16"
    }
}

</pre>paths:模块id跟文件路径的映射map。</p><p><pre name="code" class="html">var dojoConfig = {
    packages: [
        "package1","package2"
    ],paths: {
        package1: "../lib/package1",package2: "/js/package2"
    }
};
 
// ...is equivalent to:
var dojoConfig = {
    packages: [
        { name: "package1",location: "../lib/package1" },{ name: "package2",location: "/js/package2" }
    ]
};

async:定义Dojo是否需要异步加载。Async的值可以是true、false或者是legacyAsync，legacyAsync是将加载器完全的放在传统的跨域模式里。

async: true

parSEOnLoad：如果设置为true，那么在DOM和所有要加载的dependencies(包括写在dojoConfig.deps数组中的加载后，会使用dojo/parse模块来对页面进行解析。

parSEOnLoad: true

推荐将parSEOnLoad

设为false(默认值就是false，因此你可以直接忽略这个选项)，这样的话开发者就会明确的去require dojo/parser模块并去调用parser.parse()函数。

deps:一个一旦Dojo加载后就会立即开始加载的资源路径的数组。

deps: ["dojo/parser"]

callback:一旦取到deps，就会执行callback函数。

callback: function(parser) {
    // Use the resources provided here
}

waitSeconds：等待多长时间才会将模块标记为加载超时。默认是0(一直等待)。

waitSeconds: 5

cacheBust:如果是true，为每一个模块的URL添加一个时间来作为querystring,以便避免从缓存中读取内容。

cacheBust: true

现在我们来创建一个简单的使用这些基本参数的例子。一个非常常见的情况就是我们将CDN上的DojoToolKit和本地的模块放在一起使用。现在假设我们使用的是GoogleCDN，本地的模块的路径为/documentation/tutorials/1.10/dojo_config/demo,创建的例子如下:

<!-- Configure Dojo first -->
<script>
    dojoConfig = {
        has: {
            "dojo-firebug": true,"dojo-debug-messages": true
        },// 不用尝试解析页面上的窗体小部件
        parSEOnLoad: false,packages: [
            // 任何指向 "demo" 的引用在加载"demo"这个模块的时候都应该加载本地的,而不是从 CDN
            {
                name: "demo",location: "/documentation/tutorials/1.10/dojo_config/demo"
            }
        ],// 超时时间为10s
        waitSeconds: 10,map: {
            // 不想使用 "dojo/domReady!",就是想用 "ready!" 来替代
            "*": {
                ready: "dojo/domReady"
            }
        },// 不会加载缓存中的资源
        cacheBust: true
    };
</script>
 
<!-- 加载<span style="font-family: Arial,sans-serif;">Google CDN上的</span><span style="font-family: Arial,sans-serif;"> Dojo,Dijit,and DojoX资源  --></span>
<script src="//ajax.googleapis.com/ajax/libs/dojo/1.10.1/dojo/dojo.js"></script>
 
<!-- 加载 "demo" 模块 -->
 
<script>
    require(["demo/AuthoredDialog","ready!"],function(AuthoredDialog,parser) {
        // 解析页面
        parser.parse();
 
        // Do something with demo/AuthoredDialog...
    });
</script>

通过使用packages配置，我们将所有指向demo/*的引用都又指向到了我们本地的/documentation/tutorials/1.10/dojo_config/demo/这个目录，同时呢又影响CDN上的dojo,dijit，还有dojox的使用。如果没有定义demo这个package，那么对demo/ AuthoredDialog的请求就会转向 //ajax.googleapis.com/ajax/libs/dojo/1.10.1/dojo/demo/AuthoredDialog.js。我们也使用了别名，就是用ready来指代dojo/domReady.。

关于Dojo加载器的详情可以看 documentation about the new loader这篇文章。

新的加载器也支持传统的dojo.require()的资源加载，也可以配置比如modulePaths这样的在1.6版本就已经被覆盖掉了属性，这样的话开发者就可以放心的升级已经有的应用。

本地化和国际化@H_502_5@

Dojo的i18n(国际化)系统是按照自己的规则习惯来写的，对他本身的教程也很有用，我们在这里就接触这个仅仅是为了说明dojoConfig可以针对国际化来进行一些配置。

你可以使用dojoConfig的国际化功能来为任何的小部件或者内容来进行本地化配置，本地化选项可以允许你重写浏览器默认给Dojo的内容。下面的简单例子就是展示它是如何工作的:

<script>
    var dojoConfig = {
        has: {
            "dojo-firebug": true,parSEOnLoad: true,// look for a locale=xx query string param,else default to 'en-us'
        locale: location.search.match(/locale=([\w\-]+)/) ? RegExp.$1 : "en-us"
    };
</script>
<script src="//ajax.googleapis.com/ajax/libs/dojo/1.10.1/dojo/dojo.js"></script>
<script>
    require(["dojo/date/locale","dojo/_base/window","dojo/i18n",function(locale,config,win) {
        var now = new Date();
        var dialog = new Dialog({
            id: "dialog",// set a title on the dialog of today's date,// using a localized date format
            title: "Today: " + locale.format(now,{
                    formatLength:"full",selector:"date"
            })
        }).placeAt(win.body());
        dialog.startup();
 
        dialog.set("content","<pre>" + JSON.stringify(config,"\t") + "</pre>");
        dialog.show();
    });
</script>

点此查看本示例的演示

在这个示例中，我们为dojoConfig对象定义了locale这个属性，我们从query string中去匹配locale=xx这个参数。这只是一个演示示例，一般情况下的值是个写死的固定值。在所有的模块加载前定义属性，可以保证任何绑定到了dependencies数组的本地化信息都能够按需正常显示。在这个例子中，我们使用了dojo/date/locale模块来将一个日期对象格式化为了本地的字符串，然后将它设置为了对话框的标题。

对于使用了多语言的页面，就像浏览器或者是dojoConfig.locale属性指定的那个值一样，你还需要再加载其他的内容。这种情况下，就要使用extraLocale这个配置属性，这个属性对应的值是一个存放了localename的字符串数组。

当使用了dojo/parser模块的时候，DOM节点上的lang=?会覆盖掉。这在Dojo2.0会进行改进。当然你也可以为单个的部件指定lang这个属性，从而只在那个部件上覆盖掉。

自定义属性@H_502_5@

鉴于dojo.config是众所周知的配置页面属性的地方，Dojo中的其他模块也会在这里对它们自身进行一些配置。我们经常看到的有对dijit、尤其是dojox的配置。

Dijit Editor

allowXdRichTextSave

dojox GFX

dojoxGfxSvgProxyFrameUrl,forceGfxRenderer,gfxRenderer

dojox.html metrics

fontSizeWatch

dojox.io transports and plugins

xipClientUrl,dojoCallbackUrl

dojox.image

preloadImages

dojox.analytics plugins

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

它可以在的模块中使用，那当然也能够使用在你自己的模块中。是一个非常理想的配置页面或者应用属性的地方。注意下面这个例子:

<script>
    dojoConfig = {
        has: {
            "dojo-firebug": true
        },app: {
            userName: "Anonymous"
        }
    };
</script>
<script src="//ajax.googleapis.com/ajax/libs/dojo/1.10.1/dojo/dojo.js"></script>
<script>
    require(["dijit/Dialog","dijit/registry","dojo/_base/lang","dojo/io-query",function(Dialog,registry,lang,ioQuery) {
 
        // 从query string中获取配置信息，并且将它加入到我们的app配置
        var queryParams = ioQuery.queryToObject(location.search.substring(1));
        lang.mixin(config.app,queryParams);
 
        // 创建一个对话框
        var dialog = new Dialog({
            title: "Welcome back " + config.app.userName,content: "<pre>" + JSON.stringify(config,"\t") + "</pre>"
        });
 
        // 使用app config来展示个性化信息
        dialog.show();
 
    });
</script>

点此查看本示例的演示

在这个示例中，我们在定义了一个app属性，随后我们通过引用来为对话框提供了个性化的问候信息。有很多给dojoConfig.app赋值的方式。它可以先赋上一个合理的默认值，然后随后再加入特定的值。在生产模式中，写着dojoconfig的script块可能会写在了服务端。另外你可以通过cookie中以JSON格式保存的配置信息的值来构建它，或者像我们前面的例子——你可以直接从querystring中提取配置数据。在开发和测试模式，你可以使用一个模版提供虚拟的值，或者载入一个脚本或模块来构建它。

总结@H_502_5@

在这篇教程中，我们展示了常用的构建dojo.config的方式--通过dojoConfig或者是data-dojo-config--以及配置信息是如何影响模块的行为的。

Dojo引导和生命周期中有着清晰位置和角色的dojo.config属性意味着相同的概念也适用于Dojo模块甚至是你自己的模块及应用。

扩展阅读@H_502_5@

原文链接：https://www.f2er.com/dojo/291125.html