BUZ-自定义指令/渲染

自定义指令/渲染

在实际项目开发中，模板引擎默认提供的渲染逻辑肯定不会完全符合项目的设计需求，BUZ提供两种自定义功能，开发人员可以根据自身项目需求 自定义各种渲染方法。

两种扩展方式都要依赖于core/compile/order.js（路径请根据自身脚本所在位置调整，建议在app.js中注入全局指令/渲染）

1	import CompileOrder from 'core/compile/order.js';

自定义渲染（常用）

自定义渲染时比较常用的扩展，例如对时间格式化、读取字典数据、格式化金额等等操作， 如果没有自定义渲染的话，我们只能在页面中写重复的转换方法或者在每个视图组件中创建 相同的转换方法。有了自定义渲染我们既可以创建公共的渲染方法了。

使用方式：

1 2 3 4 5

import CompileOrder from 'core/compile/order.js';   CompileOrder.addHelp("reverse",function(value =""){     return value.split('').reverse().join(''); });

1	{{reverse("BUZ帮助文档")}}

多参数：

1 2 3 4 5 6 7 8 9 10 11

import CompileOrder from 'core/compile/order.js';   CompileOrder.addHelp("sum",function(...param){     let result=0;       param.forEach(function(i){         result+=i;     });       return result; });

1	{{sum(1,3,4,5,6,7)}}

addHelp方法提供两个参数，第一个参数为name值（必填）；第二个为执行方法(可带参数)

详细内容请详看模板语法中的计算属性

自定义指令

自定义指令一般适用于Attributes扩展，规则为b-指令名称，请看下面这个例子：

1 2 3 4 5 6 7 8

import CompileOrder from 'core/compile/order.js';   CompileOrder.addOrder({     name: "focus",     exec: function (target, value) {         target.node.focus();     } })

1	<input b-focus="" type="text">

通过上面的写法，我们就可以实现默认焦点功能，当然默认焦点可以使用autofocus属性，这个例子仅供学习参考。 注意：指令名称尽量避免与公共指令重名，除非你想替换掉它。

接下来我们来看一下addOrder具体的参数介绍：

参数	作用	类型	默认值	备注
name	指令名称	String		必填。指令名称尽量避免与公共指令重名，除非你想替换掉它。
exec	执行方法	Funtion		必填。在下面章节会详细介绍参数及参数属性。
isSkipChildren	是否跳过子集	Boolean	false	当Element渲染到该指令时，若该节点有子集，并且该属性为true时， 则跳过该节点的子集渲染，统一交给指令统一处理。例如：for 指令在循环时会跳过子集，交由for内部指令渲染子集。该属性为高级属性，一般用不到。
weight	权重	Int	0	该属性属于高级属性，一般用于对指令执行顺序调整时会使用到该属性。 目前for权重200，if/else if/else权重100， 请谨慎操作。
breforeExec	执行exec之前触发	Funtion		只会执行一次，可在该方法中设置前后节点等操作。
runExpress	自定义表达式解析	Funtion	默认执行tryRun方法	若指令解析后复杂度高，需要二次转换时，可通过该方法进行相应处理后再尝试运行。 默认执行tryRun方法
tryRun	自定义运行方法	Funtion	默认使用Expression解析	该方法返回实际值，用于exec第二个参数。 该属性为高级属性，不建议重写。
addWatchers	添加响应式监听	Funtion		内部方法，禁止重写，若该指令在实际编译时会创建出其他监听， 则可以通过该方法进行收集，并在节点销毁时手动对其清除，已防止内存泄漏；例如 for指令，在解析子集时会不断生成监听。
clearWatchers	清除响应式监听	Funtion		内部方法，禁止重写，例如for指令，若数组/对象发生改变时， 会移除原节点，并重新解析新的节点，这时我们可以在清除源节点时手动清除 废用的监听。

addWatchers/clearWatchers一般适用于高级指令的编写，建议合理使用该方法来管理动态生成 的响应式监听，当然你也不用担心，当视图组件卸载时会将该视图在展示期间所产生的所有监听全部移除。该方法 一般适用于动态编译子集或者对内存消耗极度关心优化时使用。

一般情况下，大部分扩展指令只需要设置name和exec即可。

exec （核心方法）

1 2 3 4 5 6

CompileOrder.addOrder({     name: "...",     exec: function (target, value, oldValue) {         //...     } })

exec是指令的执行入口，必须进行设置。参考上面例子中的参数， value/oldValue就不多说了，一个是新值，一个是旧值。接下来我们详细介绍下target参数

在指令进行执行时实际会产生两个属性操作把柄，分别是token、option。

此节内容比较长，请耐心看完。

token

指令相关信息

参数名	作用	类型	备注
node	Node节点	NODE
$node	Node节点	BET Selector	详见Api-BET
exp	指令值	String	可以理解为待处理的表达式
cause	是通过谁来触发的/触发依据	String
order	解析后的指令名	String
param	指令参数	Array	对于多文本混合的指令会解析出多个参数。
removeAttr	移除解析后的特性	Function	内部执行，禁用

option

当前Compile参数

参数名	作用	类型	备注
data	响应式数据	Object
refNode	Node节点	NODE	当前触发Compile的容器（可理解为当前视图根节点）
view	当前视图组件	View	参考Api/视图组件

总结

看完这两个属性后，我们接下来看下target的生成代码：

1 2 3 4 5 6 7 8

Object.assign({     //保留token/option把柄作为后期oder存放依据     $token: token,     $option: option,       isFirst: isFirst,     scope: scope }, token, option)

通过上面的语法，大家可以看出这一个对象的合并操作，他把token、option合并到了target中 接下来我们看下它本身自带的这些属性。

之所以进行合并操作是为了更方便的进行操作，大部分指令一般不会去操作原始token和option。

参数名	作用	类型	备注
$token	即token	Object	由于合并后无法操作token，保留$token，可以在token中存储临时值。
$option	即option	Object	同上
isFirst	是否是首次执行	Boolean	详见下面注意事项
scope	当前指令触发时实际的模型数据	Boolean	注意：该变量与option中的data不同，对于需要带入值的指令， 例如for指令在运行时会带入(value,key,index)等值，都会临时 存放到scope并向下个节点传递，不会污染传入的响应式数据。

exec一般在两种情况下触发执行：1.节点解析时默认执行一次；2.值发生改变时触发。 可通过isFrist区分是否是首次执行。

breforeExec

token Object 指令相关信息，参考上文介绍

option Object 当前Compile参数，参考上文介绍

scope Object 当前指令触发时实际的模型数据，参考上文介绍

runExpress

token Object 指令相关信息，参考上文介绍

option Object 当前Compile参数，参考上文介绍

scope Object 当前指令触发时实际的模型数据，参考上文介绍

tryRun

exp String 当前指令内容/表达式

scope Object 当前指令触发时实际的模型数据，参考上文介绍

option Object 当前Compile参数，参考上文介绍

clearWatchers

token Object 指令相关信息，参考上文介绍

addWatchers

token Object 指令相关信息，参考上文介绍

watchers Array 监听数组

https://github.com/ZhangChuanHui/BUZ