使用dojoConfig配置Dojo

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

介绍

dojoConfig对象(在Dojo 1.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 <!-- set Dojo configuration, load Dojo --> < 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 > // Require the registry, parser, Dialog, and wait for domReady require(["dijit/registry", "dojo/parser", "dojo/json", "dojo/_base/config", "dijit/Dialog","dojo/domReady!"] , function(registry, parser, JSON, config) {      // Explicitly parse the page      parser.parse();      // Find the dialog      var dialog = registry.byId("dialog");      // Set the content equal to what dojo.config is      dialog.set("content", "< pre >" + JSON.stringify(config, true) + "</ pre >");      // Show the dialog      dialog.show(); }); </ script >                                                                  <!-- and later in the page --> < 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-firebug sub-property)和 async: true，此外定义了一个自拟定特性：foo: "bar"。为了演示，一个dijit.Dialog已经放置在页面当中。require的回调函数转化dojo.config的值为JSON字符串并且放在dialog中显示。在运行结果中看我们的特性：parseOnload，has和foo，但是也有其他的，这与实际情况有关，示例页面使用跨域和Google-CDN-hosted里的Dojo 1.8版本。

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

这里有一个类似的例子：

1 2 3 <script src= "//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()配置

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

1 2 3 4 5 6 7 < script >      dojoConfig = {          has: {              "dojo-amd-factory-scan": false          }      }; </ script >

Debug/Firebug Lite配置

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

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

1 2 3 4 5 6 7 8 < script >      dojoConfig = {          has: {              "dojo-firebug": true,              "dojo-debug-messages": true          }      }; </ script >

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

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

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

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

Loader 配置

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

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

1 baseUrl:  "/js"

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

1 2 3 4 packages: [{      name:  "myapp" ,      location:  "/js/myapp" }]

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

1 2 3 4 aliases: [      // [alias name, true name]      [ "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 // Shorthand using packagePaths: packagePaths:{      "path/to/some/place" :[          "package1" ,          {              name: "package2" ,              main: "base"          }      ] } // ...is equivalent to: 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) {      // Use the resources provided here }

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

1 waitSeconds:  5

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

1 cacheBust:  true

现在让我们创建一个简单的示例，并使用一些基本的参数。一个非常普遍的方案是使用CDN中的Dojo Toolkit和本地的模块。我们使用了Google CDN和/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 <!-- Configure Dojo first --> <script>      dojoConfig = {          has: {              "dojo-firebug" :  true ,              "dojo-debug-messages" :  true          },          // Don't attempt to parse the page for widgets          parseOnLoad:  false ,          packages: [              // Any references to a "demo" resource should load modules locally, *not* from CDN              {                  name:  "demo" ,                  location:  "/documentation/tutorials/1.8/dojo_config/demo"              }          ],          // Timeout after 10 seconds          waitSeconds: 10,          aliases: [              // Instead of having to type "dojo/domReady!", we just want "ready!" instead              [ "ready" ,  "dojo/domReady" ]          ],          // Get "fresh" resources          cacheBust:  true      }; </script>         <!-- Load Dojo, Dijit, and DojoX resources from Google CDN --> <script src= "//ajax.googleapis.com/ajax/libs/dojo/1.8.1/dojo/dojo.js" ></script>         <!-- Load a  "demo"  module -->         <script>      require([ "demo/AuthoredDialog" ,  "dojo/parser" ,  "ready!" ],  function (AuthoredDialog, parser) {          // Parse the page          parser.parse();                  // Do something with demo/AuthoredDialog...      }); </script>

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

查看演示

 documentation about the new loader 提供了更多新loader的细节。

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

区域设置和国际化

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

你可以在dojoConfig中使用Dojo's i18n组件为任何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 ,          // 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.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, Dialog, JSON, 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,  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，它们的模块标志和行为是可以被设置的：

• 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

它能够在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> <script src= "//ajax.googleapis.com/ajax/libs/dojo/1.8.1/dojo/dojo.js" ></script> <script>      require([ "dijit/Dialog" ,  "dijit/registry" ,  "dojo/parser" ,  "dojo/_base/lang" ,      "dojo/json" ,  "dojo/_base/config" ,  "dojo/io-query" ,  "dojo/domReady!" ]      ,  function (Dialog, registry, parser, lang, JSON, config, ioQuery) {                // pull configuration from the query string          // and mix it into our app config          var  queryParams = ioQuery.queryToObject(location.search.substring(1));          lang.mixin(config.app, queryParams);                // Create a dialog          var  dialog =  new  Dialog({              title:  "Welcome back "  + config.app.userName,              content:  "<pre>"  + JSON.stringify(config,  true ) +  "</pre>"          });                // Draw on the app config to put up a personalized message          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模块甚至你自己的模块和应用程序中是用它。