使用dojoConfig配置dojo（翻译）

http://dojotoolkit.org/documentation/tutorials/1.10/dojo_config/index.html

dojoConfig对象（原来是djConfig对象），我们可以通过该对象设置dojo toolkit的选项和默认行为。在本教程，我们将探讨如何在我们的代码中使用dojoConfig。

介绍

dojoconfig对象（在dojo 1.6版本之前为djcofig）是用来在页面或Web应用中配置dojo的主要方式。该对象作为一个全局对象被模型加载器引用。如果需要的话，该对象可以进一步被用来配置自定义的web应用。

之前老的djconfig对象已经本废弃，但在2.0版本之前，已经存在的代码还可以继续运行。在本教程编写的时候，还有很多应用正在使用djconfig。目前这两个对象可以直接替换，但从现在开始，我们推荐大家使用dojoconfig。

开始

下面我们通过一个例子看下dojoConfig如下使用，代码如下：

<!-- 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.10.4/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, null, "	") + "```");
    // 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>

 需要注意的是，在dojo.js在被加载之前，就把dojoConfig相关的代码定义到了一个javascript代码块里。如果两者顺序反的话，配置的信息将被忽略。

在这个例子中，我们设置了三个标记，parseOnLoad: false、has(dojo-firebug sub-property), 和async: true。初此之外，一个自定义的属性也被定义，foo: "bar"。在这个例子中，一个dijit/dialog类型节点被放置到了页面中。系统的主要代码定义在reaiure函数的回调函数中，该函数的作用是把dojoConfig的值转换成Josn字符串，并在弹出的对话框中显示出来。结果是我们设置的属性信息，parseOnLoad, has, 和 foo。单但也有一些其他信息，例如页面的跨域信息和Google-CDN-hosted version of Dojo 1.10。

区分dojoConfig和dojo/_base/config对我们来说非常重要。dojoConfig的作用比较单纯，只是对dojo的加载器和模块进行相关参数定义。当页面引导启动之后（dojoConfig定义之后），在加载器或其他模块使用配置信息时，可通过dojo/_base/config获取。

下面的代码是以声明的方式定义dojoConfig。

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

 在这个例子中，我们使用了之前教程或例子使用到的data-dojo-config属性，该属性定义到了dojo的<script>代码块的属性中。这种定义方式和我们上面的例子起到的作用是一样的。这两个例子中，我们最终设置的参数最终都写入到了dojo/_base/config对象中。这些设置在加载dojo.js后立即生效。

为了确认这一点，你可以在dojoConfig里面设置一些新的参数，然后在控制台加载dojo.config的信息，对比检查。所以说，dojoConfig是一个通用的配置dojo的属性-值列表对象，下面让我们看下dojoConfig有哪些设置，以及我们如何使用它。

has()配置

在1.7版本及以后，has()是dojo新添加的最具有特色的功能之一，使用该函数可以进行特性检测。我们可以使用该函数，检测dojoConfig中是否包含制定的特性，其原理就是使用该函数检测对象的属性值哈希表。现在这种特性可以用来检测dojo是否支持某种功能。例如我们可以禁用dojoConfig中的某个特性，代码如下所示：

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

Debug/Firebug Lite 配置

你可能从其他教程或者通过使用dojo1.7版本熟悉isDebug标签，该标签的作用就是打开调试功能。在dojo1.7之后的版本，现在通过has()特性来设置这些信息。通过has()特性设置dojo-firebug特性，让Firebug Lite支持调试较老版本的IE浏览器（isDebug依然可以使用，但在异步模式下，通过设置特性的方式会更加简单易用）。如果现在有firebug插件或者其他的控制台输出工具，dojo配置的信息不会做任何事情。但如果你没有其他的控制台输出工具，系统会加载dojo版本对应的firebug lite，并在页面的底部创建一个控制台输出界面。在没有很好的开发工具或早期版本IE环境下，这就一种很好的方式。

如果想查看调试信息，可设置dojo-debug-messages属性为True。如果设置为false，一些警告信息就会被忽略。例如下面代码就打开调试控制台面板，并显示调试信息。

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

我们可以通过设置dojo-guarantee-console特性为False关闭Dojo自带的控制台对象。该属性默认为true。如果需要的话，可以创建一个虚拟的控制台对象，可以通过调用console.*相关的函数记录日志，并避免系统抛出异常。

在页面中的控制台对象的一些配置还有以下几个：

• debugContainerId，制定一个页面节点，作为控制台UI的容器载体。
• popup：弹出一个新窗口显示控制台，而不是在当前的页面你上显示。

加载配置

在dojo的1.7版本中，为了和toolkit的AMD模式保持一致，dojo设计了新的加载方式。在新的加载器中，添加了一些新的配置项，例如包配置、映射配置等。关于加载器的详细信息，请参考Advanced AMD Usage tutorial。加载器比较重要的配置参数有一下几个。

• baseUrl：该属性设置了模块的前置路径，当dojo把模块转换成路径或url的时候，就会使用该属性。

 baseUrl: "/js"

• packages：一组包含了包名称和包位置的对象集合。

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

• map：允许你映射不同的模型标识路径。

    map: {
        dijit16: {
            dojo: "dojo16"
        }
    }

• paths：把模型标识映射到不同的路径下。

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时，是否是异步执行，可以设置为True、False或者legacyAsync，which puts the loader permanently in legacy cross-domain mode。

  async: true

 parseOnLoad：如果设置为true，那么当页面的DOM节点以及最初的依赖关系加载完毕后，使用dojo/parser进行解析。依赖哪些关系，可通过dojoConfig.deps的属性查看。

parseOnLoad: true

不过也有人推荐，parseOnLoad属性可以设置成Flase（其实该属性默认就是False，直接忽略该属性就可以了），开发者可以明确的加载（require）dojo/parser，并调用parser.parse()函数。

• deps：该属性保存了一些资源列表，一旦dojo被加载，这些资源就立即加载。

 deps: ["dojo/parser"]

 callback：一旦deps被取回，就执行该回调函数。

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

•  waitSeconds: 设置一个时间，单位为秒，等待一个模块加载，如果超过该时间，则发出一个信号。默认为0，就是一直等待模型加载完毕。

waitSeconds: 5

  cacheBust: If true, appends the time as a querystring to each module URL to avoid module caching:

cacheBust: true

现在让我们创建一个设置平常最常用参数的简单例子。一种最常见的应用场景就是使用CDN上的dojo库，并在本地自定义了一些模型。我们在本例中使用Google CDN上的库以及定义在/documentation/tutorials/1.10/dojo_config/demo路径下的自定义模型库。

<!-- 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.10/dojo_config/demo"
            }
        ],
        // Timeout after 10 seconds
        waitSeconds: 10,
        map: {
            // 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.10.4/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>

 通过对包的配置，我们创建了一个快捷引用Demo/*，该引用可以访问我们本地/documentation/tutorials/1.10/dojo_config/demo/文件夹包含的模块。我们从Google CDN上也获取了对dojo、dijit和dojox的引用。如果Demo包没有被定义，当我们请求demo/AuthoredDialog时，dojo会帮我们定位到/ajax.googleapis.com/ajax/libs/dojo/1.10.4/dojo/demo/AuthoredDialog.js，这个位置显然是错误的。我们也可以定义别名，例如把ready和dojo/domReady绑定到一起。

 documentation about the new loader 这篇文章提供了大量的相关细节知识。

新的加载器仍然支持以前的用法，通过dojo.require()加载资源、配置模块路径等属性信息。这可以帮助开发者稳步的更新当前已经存在的web应用。

本地化和国际化

dojo的 i18n 模块有单独的教程来讲解，在此，我们只是展示一下该模块如何配合dojoConfig工作的。

你可以使用Dojo's i18n构造器配置dojo提供的小部件中或模块中的内容。The locale option lets you override the default provided to Dojo by your browser。一个简单的实例可以说明其实如何工作的。

<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.10.4/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, null, "	") + "```");
        dialog.show();
    });
</script>

Demo with dojo.config.locale ='zh' (Chinese)

在上面的例子中，我们在dojoConfig对象上定义locale属性的地方可以看到是local=XX，参数是一个查询语句返回的值。但这只是一个演示，更多的时候，你只要硬编码，写死就可以了。在设置本地语言包之前，请确保把所有的模块都已经设置好了。在本例中，我们就使用ojo/date/locale module模块，把日期对象转换成了本地字符串，显示在了对话框标题上。

针对支持多语言的页面，你需要加载多个语言集，一个设置给浏览器或者dojoConfig的locale属性。在这个例子中，我们使用了extraLocaleconfig属性，该属性可以保存本地语言包名称集合。

当使用dojo/parser时，设置了lang=属性会覆盖dojoConfig.locale的设置。这种模式会在2.0版本的时候改变。你现在依然可以使用lang属性设置你自定义的小部件的语言设置。

自定义属性

Because dojo.config is always known to exist, and is the logical place to provide for page-scoped configuration, several other modules in Dojo use it for their own particular configuration properties. We see this in Dijit, and especially in DojoX, where module flags and behavior can be set:

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

What works for dojox modules also works for your own applications and modules. dojoConfig is an ideal place to provide configuration for behavior and page- or application-wide properties. Consider the following:

<script>
    dojoConfig = {
        has: {
            "dojo-firebug": true
        },
        app: {
            userName: "Anonymous"
        }
    };
</script>
<script src="//ajax.googleapis.com/ajax/libs/dojo/1.10.4/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, null, "	") + "```"
        });

        // Draw on the app config to put up a personalized message
        dialog.show();

    });
</script>

 In this example, we've tacked on an "app" dojoConfig property, which we later reference via dojo.config to put up a personalized greeting in the Dialog. There are many ways to approach populating dojoConfig.app. It can be pre-populated with reasonable defaults and mixed-in with specific values later. In production, the dojoConfig script block might get written out on the server-side. Alternatively, you could populate it from a cookie with JSON-formatted configuration values, or—as in our earlier example—you could extract configuration data straight from the query string. In development and test mode, you could use a template that provides dummy values, or load a script or module that populates it。

结论

In this tutorial, we've covered many common ways in which dojo.config can be populated—via dojoConfig or data-dojo-config—and how its values influence behavior and supply properties to Dojo modules.

The well-defined position and role dojo.config has in the Dojo bootstrap and lifecycle means that the same concept applies neatly to Dojo modules and even your own modules and applications.

版本记录

• dojoConfig (djConfig) documentation
• Dojo AMD loader configuration reference
• i18n docs