使用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子產品甚至你自己的子產品和應用程式中是用它。