Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
The Base Class of Widget
JavaScript

Merge pull request #83 from crossjs/master

remove unnecessary semicolons
latest commit 754704e580
@army8735 army8735 authored
Failed to load latest commit information.
docs update docs
examples fix doc
src remove unnecessary semicolons
tests upgrade for spm@3.x
.gitignore fix doc
.spmignore upgrade for spm@3.x
.travis.yml fix doc
HISTORY.md upgrade for spm@3.x
README.md fix doc
package.json fix the indent
widget.js upgrade for spm@3.x

README.md

Widget


spm package Build Status Coverage Status

Widget 是 UI 组件的基础类,约定了组件的基本生命周期,实现了一些通用功能。基于 Widget 可以构建出任何你想要的 Web 界面组件。


使用说明

Widget 继承了 base,可使用其中包括 classeventsattributeaspect 等功能。

简单的继承

var WidgetA = Widget.extend({
  attrs: {
    a: 1
  },

  method: function() {
    console.log(this.get('a'));
  }
});

var widget = new WidgetA({
  a: 2
}).render();
widget.method(); // => 2

生命周期

Widget 有一套完整的生命周期,控制着组件从创建到销毁的整个过程。主要有 initializerenderdestroy 三个过程。

Initialize

Widget 在实例化的时候会做一系列操作:

.initAttrs() // 初始化属性,将实例化时的数据和默认属性做混合
.parseElement() // 模板解析
.initProps() // 提供给用户处理属性
.delegateEvents() // 事件代理,将事件代理到 `this.element` 上
.setup() // 实例化最后一步,用户自定义操作,提供给子类继承。

具体方法的使用可查看 API 文档。

Render

this.element 插入到文档流,默认插入到 document.body,可以通过 parentNode 指定。

Render 这一步操作从 Initialize 中独立出来,因为有些组件在实例化的时候不希望操作 DOM,如果希望实例化的时候处理可在 setup 里调用 this.render()

Destroy

组件销毁。将 widget 生成的 element 和事件都销毁。

和 Attribute 的关系

Widget 使用了 Attribute,支持 getter/setter,但 Widget 做了一层扩展。

var WidgetB = Widget.extend({
  attrs: {
    a: 1
  },

  _onRenderA: function(val) {
    console.log(val)
  }
});

var widget = new WidgetB();
widget.render(); // => 1
widget.set('a', 2); // => 2

提供了 _onRender + 属性名(首字母大写)的特性,在两种情况会触发

  1. 在属性改变的时候

  2. 在调用 render 方法的时候(插入文档流之前),但当属性值为 nullundefined 时则不会触发。

模板渲染

每个 Widget 只会对应一个 element,会对他的 DOM 及事件进行操作。

element 的生成有两种情况

  1. 实例化的时候传入
  2. 由 template 生成

Widget 默认处理模板的方式是直接转换成 jQuery 对象,但不能处理数据。涉及到复杂的模板可以覆盖 parseElementFromTemplate 方法,可以继承覆盖也可以混入(比如 templatable)。

事件代理

事件代理是 Widget 非常好用的特性,将所有的事件都代理到 this.element 上。这样可以使得对应的 DOM 内容有修改时,无需重新绑定,在 destroy 的时候也会销毁这些事件。

widget.delegateEvents() 会在实例初始化时自动调用,这时会从 this.events 中取得声明的代理事件,比如

var MyWidget = Widget.extend({
    events: {
        "dblclick": "open",
        "click .icon.doc": "select",
        "mouseover .date": "showTooltip"
    },
    open: function() {
        ...
    },
    select: function() {
        ...
    },
    ...
});

events 中每一项的格式是:"event selector": "callback",当省略 selector 时,默认会将事件绑定到 this.element 上。callback 可以是字符串,表示当前实例上的方法名; 也可以直接传入函数。

events 还可以是方法,返回一个 events hash 对象即可。比如

var MyWidget = Widget.extend({
    events: function() {
        var hash = {
            "click": "open",
            "click .close": "close"
        };

        return hash;
    },
    ...
});

events 中,还支持 {{name}} 表达式,比如上面的代码,可以简化为:

var MyWidget = Widget.extend({
    events: {
        "click": "open",
        "click .close": "close",
        "mouseover {{attrs.panels}}": "hover"
    },
    ...
});
Something went wrong with that request. Please try again.