完成attribute模块文档

kissyteam · Apr 6, 2015 · e521e74 · e521e74
1 parent 30a9710
commit e521e74
Show file tree

Hide file tree

Showing 6 changed files with 327 additions and 0 deletions.
diff --git a/demo/event.html b/demo/event.html
@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset='utf-8'>
+    <title>event demo</title>
+    <script src="//g.alicdn.com/kissy/k/6.0.0/seed-min.js" charset="utf-8" data-config="{combine:true}"></script>
+</head>
+<body>
+<h2>event demo</h2>
+<script>
+    KISSY.add('demo',function(S,require,exports, module){
+        var Base = require('base');
+        var $ = require('node').all;
+        var Demo = Base.extend({
+            initializer: function(){
+
+            }
+        },{
+            ATTRS:{
+                name: {
+                    value: '明河',
+                    setter: function(v){
+                        $('body').append('<p>name:'+v+'</p>');
+                        return v;
+                    }
+                }
+            }
+        });
+        //将类暴露出去给外部使用
+        module.exports = Demo;
+    });
+    KISSY.use('demo,node',function(S,Demo,Node){
+        var $ = Node.all;
+        var demo = new Demo();
+        demo.on('beforeNameChange',function(ev){
+            $('body').append('<h2>beforeNameChange:</h2>');
+            $('body').append('<p>ev.newVal:'+ev.newVal+'</p>');
+            $('body').append('<p>ev.prevVal:'+ev.prevVal+'</p>');
+            $('body').append('<p>ev.attrName:'+ev.attrName+'</p>');
+        });
+        demo.on('afterNameChange',function(ev){
+            $('body').append('<h2>afterNameChange:</h2>');
+            $('body').append('<p>ev.newVal:'+ev.newVal+'</p>');
+            $('body').append('<p>ev.prevVal:'+ev.prevVal+'</p>');
+            $('body').append('<p>ev.attrName:'+ev.attrName+'</p>');
+        });
+
+        demo.set('name','剑平');
+    });
+</script>
+</body>
+</html>
diff --git a/demo/getter.html b/demo/getter.html
@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset='utf-8'>
+    <title>getter demo</title>
+    <script src="//g.alicdn.com/kissy/k/6.0.0/seed-min.js" charset="utf-8" data-config="{combine:true}"></script>
+</head>
+<body>
+<h2>get/getter demo</h2>
+<script>
+    KISSY.add('demo',function(S,require,exports, module){
+        var Base = require('base');
+        var Demo = Base.extend({
+            initializer: function(){
+
+            }
+        },{
+            ATTRS:{
+                name: {
+                    value: '明河'
+                },
+                msg:{
+                    value:'',
+                    getter: function(v){
+                        var name = this.get('name');
+                        return name + '很2';
+                    }
+                }
+            }
+        });
+        //将类暴露出去给外部使用
+        module.exports = Demo;
+    });
+    KISSY.use('demo,node',function(S,Demo,Node){
+        var $ = Node.all;
+        var demo = new Demo();
+        $('body').append('<p>name:'+demo.get('name')+'</p>')
+        $('body').append('<p>msg:'+demo.get('msg')+'</p>')
+    });
+</script>
+</body>
+</html>
diff --git a/demo/setter.html b/demo/setter.html
@@ -0,0 +1,40 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset='utf-8'>
+    <title>setter demo</title>
+    <script src="//g.alicdn.com/kissy/k/6.0.0/seed-min.js" charset="utf-8" data-config="{combine:true}"></script>
+</head>
+<body>
+<h2>set/setter demo</h2>
+<script>
+    KISSY.add('demo',function(S,require,exports, module){
+        var Base = require('base');
+        var $ = require('node').all;
+        var Demo = Base.extend({
+            initializer: function(){
+
+            }
+        },{
+            ATTRS:{
+                name: {
+                    value: '明河',
+                    setter: function(v){
+                        $('body').append('<p>name:'+v+'</p>');
+                        return v;
+                    }
+                }
+            }
+        });
+        //将类暴露出去给外部使用
+        module.exports = Demo;
+    });
+    KISSY.use('demo,node',function(S,Demo,Node){
+        var demo = new Demo();
+        demo.set('name','剑平');
+        //value 没有变化不会重复触发,所以配置 force : true
+        demo.set('name','剑平',{force:true});
+    });
+</script>
+</body>
+</html>
diff --git a/doc/api.md b/doc/api.md
@@ -0,0 +1,151 @@
+### get(name)
+
+获取名为name的属性值。
+
+#### 使用例子
+
+[demo](https://jsfiddle.net/minghe36/7sjze0jq/)
+
+    demo.get('name');
+
+配置的属性如下：
+
+    {
+        ATTRS:{
+            name: {
+                value: '明河'
+            }
+        }
+    }
+
+配置 getter 后，get() 会取 getter 函数的返回值：
+
+[demo](https://jsfiddle.net/minghe36/7sjze0jq/)
+
+    {
+        ATTRS:{
+            msg:{
+                value:'',
+                getter: function(v){
+                    var name = this.get('name');
+                    return name + '很2';
+                }
+            }
+        }
+    } 
+
+getter函数的上下文 this 指向类的实例，所以可以使用 this.get('name') 获取类的属性。
+
+获取 msg 属性：
+
+    demo.get('msg')
+
+
+### set(name, value, opts)
+
+设置名为 name 的属性值为 value。
+
+opts 参数一般不用配置，有一些特殊的场景可能会用到：
+
+* silent {boolean} - 默认 false , 是否触发 change 系列事件
+* error {Function} - 验证失败的回调，包括失败原因
+* force {boolean} - 是否强制触发 change 事件，默认值为 false，当值发生变化时才触发
+
+#### 使用例子
+
+[demo](https://jsfiddle.net/minghe36/pz8bgozu/)
+
+    var Demo = Base.extend({
+        initializer: function(){
+
+        }
+    },{
+        ATTRS:{
+            name: {
+                value: '明河',
+                setter: function(v){
+                    $('body').append('<p>name:'+v+'</p>');
+                    return v;
+                }
+            }
+        }
+    });
+
+设置属性：
+
+    var demo = new Demo();
+    demo.set('name','剑平');
+
+set() 会触发 属性的 setter 方法。
+
+留意，当设置的值与旧的值相同时，不会触发 setter ，比如再次设置：
+
+    demo.set('name','剑平');
+
+是没有执行 setter 的，想要触发需要使用 force 配置：
+
+    demo.set('name','剑平',{force:true});
+
+### reset(name,opts)
+
+重置属性 name 为初始值. (调用一次 set() ) 。
+
+    demo.reset('name');
+
+### hasAttr(name)
+
+判断是否有名为 name 的属性。
+
+    demo.hasAttr('name');
+
+### removeAttr(name)
+移除名为 name 的属性，很少用。
+
+    demo.removeAttr('name');
+
+### addAttr(name, attrConfig )
+
+给宿主对象增加一个属性。不推荐采用这种方式给宿主增加属性。
+
+### addAttrs()
+
+批量添加属性。不推荐采用这种方式给宿主增加属性。
+
+### beforeAttrNameChange(ev)
+
+attribute 模块强大之处是会给所有的属性注入 change 事件，方便监听每个属性值的改变。
+
+属性改变事件，名为 “attrName” 的属性, 在改变它的值之前触发该事件。
+
+[demo](https://jsfiddle.net/minghe36/c7g2n2qn/)
+
+    var demo = new Demo();
+    demo.on('beforeNameChange',function(ev){
+        $('body').append('<h2>beforeNameChange:</h2>');
+        $('body').append('<p>ev.newVal:'+ev.newVal+'</p>');
+        $('body').append('<p>ev.prevVal:'+ev.prevVal+'</p>');
+        $('body').append('<p>ev.attrName:'+ev.attrName+'</p>');
+    });
+
+    demo.set('name','剑平');
+
+ev 对象：
+
+* newVal 将要改变到的属性值
+* prevVal 当前的属性值
+* attrName 当前的属性名
+
+### afterAttrNameChange(ev)
+
+属性改变事件，名为 “attrName” 的属性, 在改变它的值之后触发该事件。
+
+[demo](https://jsfiddle.net/minghe36/c7g2n2qn/)
+
+    var demo = new Demo();
+    demo.on('afterNameChange',function(ev){
+        $('body').append('<h2>afterNameChange:</h2>');
+        $('body').append('<p>ev.newVal:'+ev.newVal+'</p>');
+        $('body').append('<p>ev.prevVal:'+ev.prevVal+'</p>');
+        $('body').append('<p>ev.attrName:'+ev.attrName+'</p>');
+    });
+
diff --git a/doc/demo-list.md b/doc/demo-list.md
@@ -0,0 +1,3 @@
+* [get/getter](https://jsfiddle.net/minghe36/7sjze0jq/)
+* [set/setter](https://jsfiddle.net/minghe36/pz8bgozu/)
+* [event](https://jsfiddle.net/minghe36/c7g2n2qn/)
diff --git a/doc/guide.md b/doc/guide.md
@@ -0,0 +1,39 @@
+### 使用说明
+
+attribute 让类拥有统一的处理属性的方式，让属性拥有getter与setter方法，弥补javascript在属性处理上的不足。
+
+attribute 模板不推荐单独混入使用，有属性需求的，请使用 base 模块。
+
+### 基本使用例子
+
+    var Base = require('base');
+    var Tip = Base.extend({
+        initializer: function(){
+            var self = this;
+            var $target = self.get('$target');
+            S.log($target.length);
+        }
+    },{
+         ATTRS:{
+            $target:{
+                value:'body',
+                getter:function(v){
+                    return $(v);
+                }
+            }
+         }
+     });
+     
+ATTRS 是 Base 用于添加类属性/参数的 object。请看 base 讲解。
+
+类的属性也可以 addAttr() 动态配置，但不推荐直接这么使用。
+
+每个属性的配置项如下：
+
+* value  (String|Number) 属性默认值，注意默认值请不要设置为复杂对象（通过自定义构造器 new 出来的），复杂对象可设置 valueFn 返回
+* valueFn (Function) 如果是复杂对象，请使用 valueFn ，很少用，使用 value 就好
+* setter (Function) 写属性时的处理函数，传入从 set() 参数得到的属性值和属性名，如果返回非 undefined 则作为新的属性设置值  
+* getter (Function) 读属性时的处理函数 
+* validator  (Function) 比较少用，写属性时的验证函数，传入从 set() 参数得到的属性值和属性名，返回 false 则不改变该属性值
+
+务必留意，getter、setter 必须有返回值。