LVT4JS Document

Tform：复杂对象收集
市面常见的表单收集工具一般仅处理了只有一个层级的表单的数据收集与校验，对于复杂对象，如对象套数组、数组套对象等的收集功能略有欠缺。
LVT4JS的Tform功能处理了复杂对象与html标签的映射与数据收集&设置的问题。
先看一个简单的例子

简单复合嵌套数组

普通文本

普通文本，textarea

普通文本，text()方法

HelloWorld div

普通文本，html()方法

HelloWorld contenteditable div

复杂数组

数组元素1：对象

普通文本

普通数字

数组元素2：普通浮点数

浮点数字

数组元素3：日期

日期

复杂对象

对象元素1：Checkbox勾选框

Checkbox

对象元素2：Radio勾选框

Radio

对象元素3：Select式勾选，可以有不选态

Select

对象元素4：文本格式的值表示勾选，空字符串为不选态，'true'为true，其他为false

Text

对象元素5：链接

Url

上述展示了一个基本的符合嵌套数据收集，表单里包含数组，而数组里又包含对象、数值等。
使用$('#id').formData()即可直接收集数据，使用$('#id').formData(json)即可直接将json对象回写入id指定元素
可尝试修改页面元素的值，点击‘数据收集’来收集修改后的数据，也可修改json数据，点击'数据回写'来回写到页面元素上
按F12观察其原代码，注意观察使用html属性'name'标记的标签。Tform使用html的属性'name'来标识该html标签是需要收集数据的对象，使用'data-type'来标识要收集数据类型是什么。利用html的层级关系来对应复合json对象的层级嵌套关系。

Tform使用的html属性

name

表示所在元素的数据是否会被Tform所收集。若父级数据类型为对象，则值为所在元素在所收集的对象中的键。若父级数据类型为数组，则值无含义

data-type

表示所在元素的数据类型，包括

text(默认)

普通文本，若数据类型为此时，可忽略不用为html标签配data-type属性

int

整数类型

float

浮点数类型

bit

布尔型，注意布尔型数据收集利用的是jQuery在input:checkbox上的prop('checked')方法，因此只适用于input:checkbox

date

日期类型，仅支持收集yyyy-MM-dd HH:mm:ss格式的日期，收集后会转为ISO-8601的时间戳(整型数值)

time

时长类型，仅支持收集HH:mm/HH:mm:ss格式的时长，收集后会转为毫秒单位时长(整型数值)

url

url类型，收集后会以文本形式体现

obj

嵌套类型的支持：对象类型，收集后是一个对象，一般应用在box型标签如div等

arr

嵌套类型的支持：数组类型，收集后是一个数组，一般应用在列表box型标签如ul,tbody等

data-func

收集/设置元素值时调用的元素jQuery对象的方法，如一般默认值是'val'，表示收集元素值时执行ele.val()，设置值时执行ele.val(val)。不同的data-type默认值不同

text/int/float/date/time/url

val

bit

valAsBit，这是一个对jQuery扩展的函数，处理checkbox，radio的checked属性的读取，或一般文本元素的值与'true'字符串比较

arr/obj

无意义

data-required

表示所在元素的数据是否必须，若被该属性标记，不填时Tform不收集数据并进行异常处理
注意Tform采用的是最省空间策略，意即当数组/对象中要收集的标签数据未填时，并不会收集该元素。
数组中收集到的元素的值和对象中收集到的键的值永远不会为null。此属性用在data-type为arr/obj的元素上表示其下所有数据都至少有一个要填写

data-range

表示需要校验填写数据的范围，若无则不校验。格式如[floor~ceiling]，前后阈值可为浮点数，前后阈值包含关系，可省略，如'1~10'，'1'，'~20'等，不同的data-type有不同的含义

text/url

文本长度范围

int/float/date/time

数值大小范围

bit

无意义

obj

对象的键的数量范围

arr

数值的长度范围

data-regex

表示是否需要使用正则校验填写的内容，bit、obj、arr忽略该属性

data-err

数据校验不合法时自定义的报错文案，不填遇到错误时会生成个包含元素name值的错误文案

错误校验处理

默认情况下在调用$('#id').formData()进行数据收集时，若数据不符合要求(如违反data-required,data-range,data-regex)等，方法会返回null并在$('#id')下寻找class为'valid-err'的元素并将其内容修改为错误信息(可以是自定义的出错元素的data-err)
若要自定义错误信息的展示方式，调用formData()时传入一个errMsgHolder(空对象等)，如var errMsg = {};$('#id').formData(null, errMsg);alert(errMsg.msg);如果出错会在errMsgHolder的键'msg'上传入错误信息，拿到该信息后业务代码可自定义展示形式(如alert出来)

文本长度范围限制小于3，必填

FAQ

无错误但返回null

注意Tform采用的是最省空间策略，如果form下所有数据都是可省略的，那么理论上讲应返回空对象{}，此时空对象会被换成null返回

直接范围指定data-type

调用$('#id').formData()时，如果$('#id')的data-type标记的不是obj而是arr或者int等，会返回具体data-type标记的数据类型。即调用formData()实际上是把$('#id')作为默认data-type标记为obj的元素来收集数据，而当显式声明了data-type后，默认的obj就失效了。

回写时数组元素不够

数组类型元素一个很大的特性是其内容数量是不固定的，Tform并不能做到直接增删页面元素。因此遇到数组类型需要回写时，建议先用业务代码来生成需要数量的页面元素。

Checkbox联动
主checkbox添加forgroup参数子checkbox添加group参数
需要在页面载入完成后调用LVT.cbxRely.init()
页面动态生成子checkbox后也需要调用LVT.cbxRely.init()

	学生
	小红
	小明

	教师
	张三
	李四

异步提交时，为防止用户进行重复提交，一个简单粗暴的做法是使用loading态。
本工具提供一个简单的loading态实现，LVT.loader.show('等待中')展示loading态，LVT.loader.hide('等待中')隐藏loading态，简化写法Tloader.show()/hide()

属性与方法

gif	展示loading时的图片资源地址，在第一调用show()之前，可替换成其他资源
threshold	出现loading信息的延迟时间(ms)
show(msg)	默认的延迟出现loading信息。一般情况下，点击要执行异步任务的按钮后，不必立刻出现loading态，尤其在异步任务耗时较短时，会造成屏幕闪烁本方法在调用后延迟`threshold`后再出现loading信息，在此期间如果调用了`hide()`则不会再出现loading信息接收一个文本参数为loading时展示的文本信息，多次调用两个相同的文本信息视为不同的loading态信息
immediateShow(msg)	无延时等待直接展示loading态
hide(msg)	消除一个指定的loading信息，接收一个文本信息，对应show/immediateShow
change(origMsg, msg)	异步任务在执行期间，有时可能会需要变换loading文案，本方法接收两个文本参数，将第一个文本的loading态文案转成第二个文本。变换后若要`hide()`，需要传参变换后的文案

出现一个短暂的toast浮条，提示一些信息。用法LVT.toast.show(msg)简化写法Ttoast.show(msg)

属性与方法

threshold	toast信息的持续时间(ms),默认1500
show(msg)	弹出toast，提示msg信息

dateRegex　日期格式正则表达式

yyyy-MM-dd HH:mm:ss格式的日期时间正则表达式

timestampFormat(timestamp)　时间戳日期格式化

接收一个时间戳参数，格式化为yyyy-MM-dd HH:mm:ss格式的日期时间

date(str[, def])　日期时间解析

new Date(str)的替代品，避免其不同浏览器的不兼容
满足
yyyy
yyyy-MM
yyyy-MM-dd
yyyy-MM-dd HH
yyyy-MM-dd HH:mm
yyyy-MM-dd HH:mm:ss
yyyy-MM-dd HH:mm:ss:sss
yyyy-MM-dd HH:mm:ss:sss+08:00
yyyy-MM-dd HH:mm:ss:sssZ
(日期分割符'-'可以是'/',' '可以是'T',':'可以是',',时区部分忽略不处理)
等日期格式转化为时间戳
str参数为null或遇到异常返回def

timeRegex　时长格式正则表达式

HH/HH:mm/HH:mm:ss格式的时长正则表达式

time(str[, def])　时长解析

接收一个HH/HH:mm/HH:mm:ss格式的时长字符串，解析为毫秒级时长整数值，若格式异常等返回def

timeFormat(time)　时长格式化

接收一个毫秒单位时间长度参数，格式化为HH:mm:ss格式的时长

GMKB(size)　文件数据大小格式化

接收一个整形文件/数据大小值，格式化为G/M/K/B的格式

ig(obj)　ig即ignore，'null','undefined','NaN'等字符忽略

传入obj转为字符串，若obj为null,undefined等字符时，返回''，用于在js代码中拼接html时，产生'null','undefined'等字符

igh(obj)　ig进阶，增加html字符转义

相比ig方法，如果obj中有html字符如'<','>'等，进行html字符转义，可用于规避XSS攻击等

json(jsonStr)　json对象解析

json形式字符串解析为json对象，异常返回null

jsf(value[, replacer [, space]])　JSON.stringify简化写法

json对象序列化

fnn(args)　即firstNonNull

返回参数中第一个非null的，与||写法相比可避免中间遇到0/''时就应该返回的情况，毕竟0/''!=null

int(str, def)　parseInt的包装

原始的parseInt会返回NaN,封装一下,遇到NaN时返回def

float(str, def)　parseFloat的包装

原始的parseFloat会返回NaN,封装一下,遇到NaN时返回def

params([url])　解析url后缀的参数

url后缀的参数封为一个obj返回，若不填，返回当前页的url的解析

uuid()　返回一个UUID

纯靠随机生成的uuid格式的uuid，事实上是个伪uuid，但在前端基本够用

arr　数组工具集

LVT.arr是一个数组方法工具集，提供以下关于数组操作的方法

contains(arr, ele)	利用`==`判断数组中是否包含元素ele
add(arr, ele)	向数组添加一个元素，若已有该元素则忽略，采用浅克隆的方法，返回添加过元素的数组，原数组不变
remove(arr, ele)	从数组删除一个元素，若没该元素则忽略，采用浅克隆的方法，返回删除过元素的数组，原数组不变
clone(arr)	浅克隆数组

obj　对象工具集

LVT.obj是一个对象方法工具集，提供以下关于对象操作的方法

isEmpty(obj)	判断是否空对象，即一个键值对都没有
size(obj)	计算object中键值对的个数
clone(obj)	浅克隆对象
remove(obj, key2Del)	从object删除指定key，返回删除key后的浅克隆对象
add(obj, obj2Add)	将一个obj加入另一个obj，若原对象已有key，则覆盖，返回添加后的浅克隆对象
hashCode(obj)	计算一个对象的哈希值