project

jQuery指令插件


License
MIT
Install
bower install project

Documentation

jplus

jQuery指令插件

在线教程与案例

介绍

引用jplus

作为jQuery插件引入

<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="jplus.js"></script>

将数据同步到视图

首先:在html中使用data-bind属性,按照css语法书写key:value;

<div id="scope">
    <p data-bind="attr-class:className">Hello <span data-bind="text:name"></span></p>
</div>

然后:在javascript中调用jQuery的refresh方法

$('#scope').refresh({
    name: 'jplus.js',
    className: 'descri'
})

大功告成

html 标签的data-bind属性中,key可以为如下内容

  • jQuery实例的方法,即在实例化后,手动添加在该实例上的方法名
  • jQuery的原型方法的名字,即$.fn上的方法名
  • jQuery实例对应的dom元素的方法名与属性名

而value则对应数据对象的属性名。

key和value都支持点操作符和方括号操作符链式取值, 如下都是合法的

  • a.b.c.e.f
  • a[0].b[1]

注意事项:避免空指令。如果找不到对应的方法函数,数据将直接成为dom元素的属性

将jplus用作模板引擎

只要将数据打包成数组,jplus就会自动安排同等数量的元素对应;不够的clone出来,多余的remove掉

<div id="scope">
    <ul>
        <li data-bind="text:list">写一些默认内容,待会儿就被覆盖</li>
    </ul>
</div>
var list = []

for (var i = 0; i < 20; i += 1) {
    list[i] = '列表项目' + i
}

setInterval(function() {
    //随机长度
    var randomLen = Math.floor(Math.random() * list.length + 1)
    var curList = list.concat().sort(function() {
        //随机化排序
        return Math.random() - 0.5
    })
    
    curList.length = randomLen
    
    $('#scope').refresh({
        list: curList
    })
}, 800);

注意事项:

  • 只有数据类型一致的数组,才作为模板数据
  • 数据类型不同的数组,全部作为参数传入指令方法
  • 传入空数组,对应的dom元素将全部删除
  • 每次调用refresh方法,都会即时扫描视图,如果元素被删除,则无法收集指令
  • 可以通过故意为数组追加null、false等强行将数据类型不一致化,达到传多个参数的目的

渲染嵌套数据到视图

将refresh作为指令,即可渲染嵌套数据

<div id="scope">
    <ul>
        <li data-bind="refresh:classList">
            <h3 data-bind="text:classTitle"></h3>
            <ul>
                <li data-bind="text:content"></li>
            </ul>
        </li>
    </ul>
</div>
var data = {
    classList:[{
        classTitle:'类名1',
        content:[1, 2, 3, 4, 5]
    },{
        classTitle:'类名2',
        content:[6, 7, 8, 9, 10]
    },{
        classTitle:'类名3',
        content:[11, 12, 13, 14, 15]
    },{
        classTitle:'类名4',
        content:[16, 17, 18, 19, 20]
    },{
        classTitle:'类名5',
        content:[21, 22, 23, 24, 25]
    }]
}

$('#scope').refresh(data)

禁止父元素扫描自身的子元素

添加noscan属性后,只有该元素的jQuery实例调用refresh才能刷新视图

/*添加noscan属性,视图私有化*/
<div noscan>
	<span data-bind="text:text"></span>
</div>

禁止数组数据改变元素数量

添加norepeat属性后,遇到数据类型一致的数组,数据比元素多时,忽略多余数据;元素比数据多时,忽略多余元素

/*不论多少数据,都只更新现有的元素*/
<div norepeat>
	<li data-bind="text:text"></li>
</div>

从视图中获取数据

jQuery的API设计理念之一是:既是getter,也是setter

$('body').html() // get HTML
$('body').html(content) // set HTML
$('body').attr('id') // get ID
$('body').attr('id', newID) // set ID

对于这类指令。当需要刷新视图时,jplus传入数据;当需要从视图中获取数据时,jplus不传参数或者只传必要的参数。

在上一个例子中,只需要调用collect方法,就从视图中获取了所需的数据。

自定义指令

所谓指令,在jplus中指写在html的data-bind属性中,格式类似css语法的键值对

<ul id="scope">
    <li data-bind="text:msg; setTitle:title; setData-directive:directive"></li>
</ul>
//插件写法,为原型添加方法,属于全局指令
$.fn.setTitle = function(title) {
    if (typeof title === 'undefined') {
        return this.attr('title')
    } else {
        this.attr('title', title)
    }
}

var $scope = $('#scope')

//实例特有方法,属于局域指令
$scope.setData = function(name, val) {
    if (!name) {
        return
    }
    if (typeof val === 'undefined') {
        return this.attr('data-' + name)
    } else {
        this.attr('data-' + name, val)
    }
}

$scope.refresh({
    msg: '一点测试文本,没有别的意思',
    title: '啊,title',
    directive: 'css-color:theColor;css-fontSize:size;'
})

//自定义指令,如果也按照getter && setter设计,也能获取数据
$('body').append(JSON.stringify($scope.collect()))

setTimeout(function() {
    
    //directive不会刷新到视图中,因为新的实例不具备setData方法
    //但是,它会成为dom.setData的属性值,这是需要注意的点
    $('#scope').refresh({
        msg: '我是原型方法,所以全局通用,新实例也能调用我',
        directive: 'new directive'
    })
    
    //从视图中获取数据,也可以获取属性的,所以directive值还是能从dom.setData中得到
    $('body')
        .append('<br><br><br>')
        .append(JSON.stringify($('#scope').collect()))
}, 3000)

动态调用指令

jplus提供了invoke方法,提供动态用功能,有两种用法

//单个调用
$scope.invoke('html', '<p>some text</p>')

//多个调用
$scope.invoke({
	html: '<p>some word</p>',
	css: ['color', '#999'], //多个参数打包成数组形式
	attr: ['title', 'a title']
})
<div id="scope">
    <input type="text" data-bind="invoke:text" />
</div>
var count = 0
var timer = setInterval(function() {
    var data = [{
            text: {
                'val': count - 1,
                'attr': ['title', count - 1]
            }
        },{
            text: {
                'css': ['font-size', count]
            }
        }]
    $('#scope').refresh(data[count % 2])
   count++
   if (count === 100) {
       clearInterval(timer)
   }
}, 300)

将data-bind拆分为data-get和data-set

//jplus 源码如下。修改属性值即可
$.directive = {
	getter: 'data-bind', //对应获取数据
	setter: 'data-bind' //对应刷新视图
}

//修改
$.directive.getter = 'data-get'
$.directive.setter = 'data-set'

获取视图模型

在jplus中,视图模型是指从作用域扫描出来的特定结构的指令和dom元素,本质是一个object对象

//获取视图模型
$scope.scan()

//以特定的html属性作为指令来源,不会改变$.directive.getter || $.directive.setter
//从data-js属性中得到指令集
$scope.scan('data-js')

//第二个参数传true时,$scope本身的'data-js'属性将被忽略
$scope.scan('data-js', true)

指定视图中需要获取的数据

$.fn.collect接受两个参数,第一个参数为object对象,第二个参数为string类型,将作为第一个参数传入$.fn.scan

//只收集'dataName',并且指定'data-collect'为指令来源,而非扫描'data-bind'
$scope.collect({
    'dataName': 'dataName'
}, 'data-collect')


//只收集'dataName',并且改变数据结构,将值存储到新对象的data.name属性中,如:{data:{name:value}}
$scope.collect({
    'dataName': 'data.name'
})

//jplus所有支持字符串属性名的地方,都可以用点操作符
$scope.collect({
    'a.b.c.e.f': 'a.f'
})

指定html属性作为指令来源刷新视图或获取数据

$.fn.refresh与'$.fn.collect'的第二个参数,可以指定本次刷新视图或获取数据的指令来源

//指定data-a为指令来源,刷新视图
$scope.refresh(data, 'data-a')

//指定data-b为指令来源,获取数据
$scope.collect(null, 'data-b')

获取视图中的嵌套数据

渲染嵌套数据到视图的方法是,将refresh写在指令中,它只是setter;因此获取嵌套数据时,应用vm替代

vm方法是一个按照既是setter,也是getter设计的API。

//jplus源码
$.fn.vm = function(dataModel) {
    return isObj(dataModel) ? this.refresh(dataModel) : this.collect()
}

沿用渲染嵌套数据到视图的例子,稍作修改,就能改造成get/set模式

<div id="scope">
    <ul>
        <!--没有noscan属性的话,classTitle和content也会被抽取出来,跟classList平级-->
        <li data-bind="vm:classList" noscan>
            <h3 data-bind="text:classTitle"></h3>
            <ul>
                <li data-bind="text:content"></li>
            </ul>
        </li>
    </ul>
</div>
var data = {
    classList:[{
        classTitle:'类名1',
        content:[1, 2, 3, 4, 5]
    },{
        classTitle:'类名2',
        content:[6, 7, 8, 9, 10]
    },{
        classTitle:'类名3',
        content:[11, 12, 13, 14, 15]
    },{
        classTitle:'类名4',
        content:[16, 17, 18, 19, 20]
    },{
        classTitle:'类名5',
        content:[21, 22, 23, 24, 25]
    }]
}

$('#scope').refresh(data)

//只该了html属性,就可以直接用$.fn.collect获取数据了
$('body').append(JSON.stringify($('#scope').collect()))

console.log($('#scope').collect())