用 Dojo 1.x 开发小部件

有关 Dojo 小部件的更多内容

如之前所述，一个 Dojo 小部件就是一个继承自某个特定类（dijit._Widget类）的 Dojo 类声明。该类定义了小部件的基本行为，提供了由所有小部件实现所共享的一些常用函数。由 _Widget 类实现的最为重要的任务是：

• 定义create方法，在小部件实例化时自动调用；此方法执行所有所需的创建步骤
• 定义一些template方法，提供面向小部件实现者的特殊 hook，使它们能够在某个特定的创建阶段实现特定的初始化动作
• 定义大量destroy方法，用来清除所分配的小部件资源
• 定义event management方法，用来关联小部件方法与 DOM 节点/方法调用事件

小部件创建阶段

create方法执行如下的基本步骤来进行小部件初始化：

如果没有 ID，就为这个小部件创建一个惟一 ID。

所有 Dojo 小部件都必须由惟一 ID 标识。在小部件被初始化时，就可以提供小部件 ID。如果不提供，Dojo 就会创建一个具有如下格式的 ID：

packageName_className_number

例如，一个按扭可以有这样一个自动生成的 ID：dijit_form_Button_0。

packageName是小部件包，点被换成了下划线（例如，dijit_form），而number是一个在小部件的基础上不断变大的数字。

在全局小部件注册表中注册这个小部件

随后，可以用dijit.byId方法来查找小部件，查找将返回与给定 ID 相对应的小部件对象。注册表是一个存在于 dijit.registry_hash 中的全局空间的一个 Object。使用类似 FireBug（参见参考资料）这样的调试工具深入此注册表可能会对跟踪（比如跟踪漏掉的小部件）有用。

映射属性

小部件属性可以被重新映射到小部件模板的用户定义节点。要映射的属性及映射的目标可在attributeMap对象内列出。这些对象的每个属性都以如下方法定义映射：

1. 属性名称标识包含将要设置的值的小部件属性名
2. 属性值标识包含目标 DOM 节点的小部件属性名。如果指定的是一个空字符串，那么就会使用domNode。

清单 9 给出了一个示例

清单 9. 声明一个 dojo 小部件

dojo.declare(
 "MyWidget",dijit._Widget,{
 // the attribute to map (name and value)
 title: "myTitle",// the DOM node to be used to set the 
 // title attribute to the "myTitle" value
 titleNode: null,// the attribute map 
 // the title attribute is mapped to the titleNode
      attributeMap: {title: "titleNode"},// the template string
      templateString: "<div><span dojoAttachPoint="titleNode"></span></div>",

得到的小部件模板将是：

<div><span title="myTitle"></span></div>

请注意，由于base _Widget类已经映射了某些基本的 HTML 属性（如 ID、类、样式），因此实现者不能覆盖attributeMap属性。相反，它们必须混合基础类attributeMap属性与它们的值。清单 10 显示了从 _FormWidget类中检索出来的一个示例。

清单 10. 混合基础类 attributeMap 属性与定制值

attributeMap: 
 dojo.mixin(
 dojo.clone(dijit._Widget.prototype.attributeMap),{id:"focusNode",tabIndex:"focusNode",alt:"focusNode"}
),

模板方法

在小部件创建阶段，我们要在某些特定的初始化阶段调用一些方法来为实现者提供一个执行一些操作的机会。下面的方法会被调用：

1. postMixInProperties：这个方法会在所有小部件参数均被设置（混合入）为小部件实例属性后调用。如果基于的是由实例化所提供的那些属性，此时非常适合进行进一步的属性初始化。
2. buildRendering：在需要为小部件生成呈现时，调用此方法。这个 hook 由dijit._Templated混入类实现，用 HTML 模板扩展原始的小部件。实现者可潜在地提供它们的实现来完善_Templated类作业。
3. postCreate：在小部件的 DOM 准备好并被插入到页面后，调用此方法。此时，这个实现者可以在小部件的 DOM 结构之上操作。子小部件尚未启动。
4. startup：在小部件上操作的最后时机。此时，子小部件已经启动。
5. uninitialize：在小部件被消毁时调用。实现者有机会执行一些非自动的清理。

模板方法可以由实现者提供，但必须注意的一点是超类有可能已经实现了其模板方法。要确保对链中所有类的正确初始化，实现者必须手动编写超类方法调用的代码，如清单 11 所示。

清单 11. 超类方法调用的示例

startup: function()
{
 // call the superclass' method
   this.inherited("startup",arguments);
 // your code here
}

作为一个通用约定，对于所有创建方法（除uninitialize以外的所有模板方法），超类的方法应第一个被调用以确保在处理超类的条目前它们已被正确地初始化。

uninitialize方法则要遵照相反的规则。

最后一个要注意的是startup方法。别忘了，若小部件通过声明被创建，startup 方法是通过dojo.parser.parse方法自动调用的。倘若小部件是由编程方式创建，情况就不一样了，必须像下面例子所示的那样手动完成。

var w = new MyWidget({});
w.startup();

小部件销毁阶段

创建后，小部件将一直存在，直到执行一个显式的销毁请求。实现者负责管理小部件的整个生命周期，包括小部件的销毁。否则，将会导致有遗漏的小部件存在，直到整个页面清理发生。这个小部件提供了四种销毁方法：

destroyRendering：这个方法用来清理小部件的呈现条目。除非实现者需要的是部分清理，否则该方法往往由其他摧毁方法调用。
• destroyDescendants：销毁所有的子小部件。除非实现者需要的是部分清理，否则该方法由destroyRecursive方法调用。
• destroy：销毁所有的小部件条目（不包括子小部件）。
• destroyRecursive：销毁小部件条目及子小部件。如果小部件包含有内部小部件，那么必须调用此方法。

在本示例中，小部件包含有内部小部件（例如：在其模板中有一些小部件），所以实现者必须要记得触发子小部件，以便销毁这些子小部件并且无需让小部件用户决定调用何种销毁方法。清单 12 给出了实现此目的一种可能方式。

清单 12. 触发小部件销毁的示例

uninitialize: function()
{
 // destroy the descendants
 this.destroyDescendants();
 // call the superclass' method
   this.inherited("uninitialize",arguments);
}

事件管理

Dojo 小部件可以对来自于 DOM 节点或对象的外部事件做出反应。这类事件可通过使用小部件的connect方法被手动连接，该方法具有如下所示的签名（非常类似于dojo.connect方法）：

connect: function(/*Object|null*/ obj,/*String*/ event,/*String|Function*/ method);

或者，也可以通过使用dojoAttachEvent属性在模板中声明此连接的方法进行自动连接。在这两种情况下，此连接都可以由小部件在 _connects 数组内内部跟踪。所有连接在销毁时都将会自动断开。这样，小部件与 DOM 节点间的相互引用就被打破了。

如果，在小部件生命周期内一些连接已经不再需要，那么实现者就可以通过调用disconnect方法来手动断开这些连接以减少事件的处理。

小部件模板

如前面看到的，小部件必须继承自dijit._Widget类，它定义并提供了 Dojo 小部件的基本行为。这样一个基类定义了负责构建小部件呈现元素的buildRendering方法。比如，一个小部件实现者可以用这种方法创建小部件标记并将其设置到小部件 DOM 节点。另一种方案是使用 DOM API 创建小部件结构。在这两种情况下，实现者都必须以某种方式编程实现buildRendering方法。

Dojo 提供了一个强大的抽象，即dijit-._Templated混入类，可以将小部件呈现定义与小部件行为实现分离开来。想要开发这样一个抽象，实现者需要从_Templated类继承，如清单 13 所示。

清单 13. 从 _Templated 类继承

dojo.declare(
 "widgets.MyWidget",dijit._Templated
 {
 templatePath: dojo.moduleUrl("widgets","templates/MyWidget.html"),}
);

_Templated类提供了它自身的buildRendering实现，该实现利用了一个类似 HTML 的定义。这个定义有可能存在于两个不同的地方。

1. 一个外部文件。在这种情况下，该文件由templatePath属性引用。
2. 一个内部字符串属性。在这种情况中，模板直接通过templateString属性在小部件内定义。如果指定了templateString，那么templatePath可被忽略，即便指定，也是如此。

第一种选择是一种组织小部件源代码的最干净的方法，因为这个标记可被写入一个不同的文件，也可被以一种可读的方式格式化，同时不必费心于字符串的串联，并且字符串分界符不可转义。而第二种选择要更好一些，因为无需从浏览器载入第二个文件。然而，您不必担心，因为 Dojo 提供了一个构建工具，能将外部模板内部化到小部件源代码。

一个模板可以通过引用小部件属性而被参数化。在小部件公开某些能直接影响此标记的配置参数时，或是这个标记必须要依照外部首选项而有条件地生成时，这一点将会很有用。小部件属性通过使用这样的语法引用：${propertyName}。

模板可以包含其他的小部件声明。不过，为了将它们考虑进去，小部件开发人员必须将widgetsInTemplate属性设为 true，该属性默认情况下被设为 false 以便跳过并非必需的处理。

模板可以包含如下两种特殊的属性声明：

• dojoAttachPoint：如果指定，这个标记属性必须被设置为一个小部件属性名。对应于此标记的 DOM 将被设置为此小部件的属性。模板内的几个标记可以有一个或多个附加点。
• dojoAttachEvent：这个标记属性会列出在触发 DOM 事件时必须被回调的那些小部件方法。

清单 14 给出了一个模板示例。

清单 14. 特殊属性声明的模板示例

<span 
 class="textInputDefault" 
 dojoAttachEvent="onclick:_onClick">
 <img 
 class="textInputIcon" 
 src="${constants.DEFAULT_ICON}" 
 dojoAttachPoint="_iconNode"/>
 <input 
 class="textInputNode"
 size="${size}"
 type="${type}"
 value=""
 dojoAttachPoint="_inputNode,_focusNode" 
 dojoAttachEvent="onkeyup:_onKeyUp,onkeypress:_onKeyPress,onchange:_onChange"
 />
 <span 
 class="textInputRight">&nbsp;
 </span>
</span>

<span type='text' dojoType='ajaxcommon.widgets.DateInputBox' id='validFrom'>
<script type='dojo/method'event='onValueChanged'>AWT.dispatchOnChange(this.id);</script>
</span>

dojo.provide("ajaxcommon.widgets.DateInputBox"); 

dojo.require("ajaxcommon.resources.Images");
dojo.require("ajaxcommon.widgets._DateTimePicker");
dojo.require("ajaxcommon.widgets.picker.PickerInputBox");
dojo.require("ajaxcommon.widgets.picker.DatePicker");
dojo.declare(
   "ajaxcommon.widgets.DateInputBox",[ajaxcommon.widgets.picker.PickerInputBox,ajaxcommon.widgets._DateTimePicker],{
      /** the picker icon */
      pickerIcon: ajaxcommon.resources.Images.get()["CALENDAR_ICON"],/** the picker disabled icon */
      pickerDisabledIcon: ajaxcommon.resources.Images.get()["DISABLED_CALENDAR_ICON"],/** the picker icon title */
      pickerIconTitle: ajaxcommon.resources.Labels.get()["PICK_DATE"],/** constraints */
      constraints: {selector: "date",formatLength: "short",wideYear: true},/**
       * Constructor.
       */
      constructor: function()
      {
         // even if the format length is short,ensure the wide year (yyyy)
         // by overriding the datePattern
         if (this.constraints.formatLength === "short" && this.constraints.wideYear) {
            this.constraints.datePattern = this._getWideDatePattern();
         }
         // set the regex for the text
         this.textRegExp = "^(" + dojo.date.locale.regexp(this.constraints) + “){0,1}$";
         // set the regex message for the text
         this.textRegExpMessage = 
            this._labels.format("DATE_INVALID_VALUE",{example: this._getExampleValue()});
         // set the picker class
         this.pickerClass = "ajaxcommon.widgets.picker.DatePicker";
      },/**
       * Returns the date pattern with the wide-year (yyyy)  
       */
      _getWideDatePattern: function()
      {
         // get the bundle
         var bundle = dojo.date.locale._getGregorianBundle();
         // get the pattern
           var pattern = bundle["dateFormat-short"];
           // replace the yy to yyyy if not yet yyyy
           if ( pattern.search(/yyyy/gi) === -1 ) {
              // the year is not in the wide form
              pattern = pattern.replace(/yy/gi,"yyyy");
           }
           return pattern;
      },/** 
       * Returns a string containing an example of accepted value. 
       */      
      _getExampleValue: function()
      {
         // get a sample date object (my birthday!!!)
         var d = new Date();
         d.setDate(15);
         d.setMonth(4);
         d.setYear(1971);
         // format the date in the current locale and return 
         return dojo.date.locale.format(d,this.constraints);
      }
   }      
);

<span
    class="picker"
    ><span 
        tabindex="${tabindex}"
        dojoType="${_textBoxWidget}"
        dojoAttachPoint="_textNode,_focusNode"
        required="${required}"
        size="${size}"
        minLength="${textMinLength}"
        maxLength="${textMaxLength}"
        regExp="${textRegExp}"
        regExpReference="${textRegExpReference}"
        regExpMessage="${textRegExpMessage}"
        minWidth="${minWidth}"
    ></span
    ><span 
        dojoAttachPoint="_pickerButtonContainer">
        <img 
            tabindex="${tabindex}"
            src="${pickerIcon}"
            dojoAttachPoint="_pickerButtonNode"
            dojoAttachEvent="onclick:_onClick,onkeyup:_onKeyUp"
            class="pickerButton"
            title="${pickerIconTitle}"
    /></span>
</span>

来源：http://www.ibm.com/developerworks/cn/web/wa-aj-dojotool/

（编辑：李大同）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!