文档...
这个文档只涉及到你实际需要知道的API，这些API中用到的其它函数的介绍都省略了，但我们在源代码中都做了注释。
内容
Validate (类) 顶部
Validate 类包含了很多用来执行各种类型校验的静态校验方法。它们独立于 LiveValidation 类，因此可以用在任何 javascript 代码中, 并不需要局限于表单域的校验。
每次当你往 LiveValidation 对象里添加校验类型，都是由于你需要它们去解决你的问题，所以应该尽量了解它们。如果你对 Ruby on Rails 的校验很熟悉，你也许会很容易记住我们这里的API，因为我们使用相似的命名规范，相似的参数名称(有一些参数的名称因为 javascript 保留字的原因有些不同)。
如果你不是在 LiveValidation 对象里使用它们, 当校验失败时会抛出一个自定义的错误，如果你需要这些错误信息就要自己去捕捉到它们。如果你只是想知道校验是否通过，不需要知道清楚的错误信息，你可以用 Validate.now 方法执行这个校验就可以了。
Presence (静态方法) 顶部
校验一个值是否存在(例如 not null, undefined, 或一个空字串)
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
failureMessage (可选) - {String} - 校验失败时输出的信息 (缺省: “Can’t be empty!”)
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
Validate.Presence( 'hello world', { failureMessage: "Supply a value!" } );Format (静态方法) 顶部
根据正则表达式校验一个值
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
failureMessage (可选) - {String} - 校验失败时输出的信息
(缺省: “Not valid!”)
pattern - {正则表达式} - 用来校验的正则表达式
(缺省: /./i)
negate - {Boolean} - 如果设置成true，则当数据不能匹配时表示校验成功
(缺省: false)
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
// check that 'validation' exists in the string, case insensitive...
Validate.Format( 'live validation', { pattern: /validation/i, failureMessage: "Failed!" } );Numericality (静态方法) 顶部
校验一个值是否是数字，并且还可以检查是否是整数，指定大小的数，高于某个数，低于某个数，在某个范围内，或者这前面这些校验的组合。
提示 - 数字用科学计数法表示时(例如 2e3, 表示 2000) 也能正确的处理, 包括负数和浮点数。
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
notANumberMessage (可选) - {String} - message to be used when validation fails because value is not a number (缺省: “Must be a number!”)
notAnIntegerMessage (可选) - {String} - message to be used when validation fails because value is not an integer (缺省: “Must be an integer!”)
wrongNumberMessage (可选) - {String} - message to be used when validation fails when ‘is’ param is used (缺省: “Must be {is}!”)
tooLowMessage (可选) - {String} - message to be used when validation fails when ‘minimum’} param is used (缺省: “Must not be less than {minimum}!”)
tooHighMessage (可选) - {String} - message to be used when validation fails when ‘maximum’} param is used (缺省: “Must not be more than {maximum}!”)
is (可选) - {mixed} - the value must be equal to this numeric value
minimum (可选) - {mixed} - the minimum numeric allowed
maximum (可选) - {mixed} - the maximum numeric allowed
onlyInteger (可选) - {Boolean} - if true will only allow integers to be valid (缺省: false)
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
// check that value is an integer between -5 and 2000 exists in the string, case insensitive...
Validate.Numericality( 2e3, { minimum: -5, maximum: 2000 } );Length (静态方法) Top
Validates the length of a value is a particular length, is more than a minimum, less than a maximum, or between a range of lengths
NB - to check if it is within a range, specify both a minimum and a maximum
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
wrongLengthMessage (可选) - {String} - message to be used when validation fails when ‘is’ param is used (缺省: “Must be {is} characters long!”)
tooShortMessage (可选) - {String} - message to be used when validation fails when ‘minimum’} param is used (缺省: “Must not be less than {minimum} characters long!”)
tooLongMessage (可选) - {String} - message to be used when validation fails when ‘maximum’} param is used (缺省: “Must not be more than {maximum} characters long!”)
is (可选) - {mixed} - the value must be this length
minimum (可选) - {mixed} - the minimum length allowed
maximum (可选) - {mixed} - the maximum length allowed
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
// check that value is between 3 and 255 characters long...
Validate.Length( 'cow', { minimum: 3, maximum: 255 } );Inclusion (静态方法) Top
Validates that a value falls within a given set of values
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
failureMessage (可选) - {String} - message to be used upon validation failure (缺省: “Must be included in the list!”)
within - {Array} - an array of values that the value should fall in (缺省: Empty array)
allowNull (可选) - {Boolean} - if true, and a null value is passed in, validates as true (缺省: false)
partialMatch (可选) - {Boolean}- if true, will not only validate against the whole value to check, but also if it is a substring of the value (缺省: false)
caseSensitive (可选) - {Boolean} - if false will compare strings case insensitively(缺省: true)
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
Validate.Inclusion( 'cat', { within: [ 'cow', 277, 'catdog' ], allowNull: true, partialMatch: true, caseSensitive: false } );Exclusion (静态方法) Top
Validates that a value does not fall within a given set of values
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
failureMessage (可选) - {String} - message to be used upon validation failure (缺省: “Must not be included in the list!”)
within - {Array} - an array of values that the given value should not fall in (缺省: Empty array)
allowNull (可选) - {Boolean} - if true, and a null value is passed in, validates as true (缺省: false)
partialMatch (可选) - {Boolean} - if true, will not only validate against the whole value to check, but also if it is a substring of the value (缺省: false)
caseSensitive (可选) - {Boolean} - if false will compare strings case insensitively(缺省: true)
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
Validate.Exclusion( 'pig', { within: [ 'cow', 277, 'catdog' ], allowNull: true, partialMatch: true, caseSensitive: false } );Acceptance (静态方法) Top
Validates that a value equates to true (for use primarily in detemining if a checkbox has been checked)
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
failureMessage (可选) - {String} - message to be used upon validation failure (缺省: “Must be accepted!”)
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
Validate.Acceptance( true, { failureMessage: "You must be true!" } );Confirmation (静态方法) Top
Validates that a value matches that of a given form field
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
failureMessage (可选) - {String} - message to be used upon validation failure
(缺省: “Does not match!”)
match -{mixed} - a reference to, or string id of the field that this should match
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
Validate.Confirmation( 'open sesame', { match: 'myPasswordField', failureMessage: "Your passwords don't match!" } );Email (静态方法) Top
Validates a value is a valid email address
This is an example of a custom validation method. This one is essentially just a Format validation, but one that is used often enough to merit its own method so that you don’t need to keep remembering the same crazy regular expression and failure message. You may want to mimic this to create your own re-useable validations, such as phone numbers, postcodes etc.
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
failureMessage (可选) - {String} - message to be used upon validation failure (缺省: “Must be a valid email address!”)
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
Validate.Email( 'live@validation.com', { failureMessage: "I am an overridden message!" } );Custom (静态方法) Top
Validates a value against a custom function that returns true when valid or false when not valid.
You can use this to easily wrap any special validations that are not covered by the core ones, in a way that the LiveValidation class can use to give the feedback, without having to worry about the details.
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
against - {Function} - a function that will take the value and an object of arguments and return true or false(缺省: function( value, args ){ return true; } )
args - {Object} - an object of named arguments that will be passed to the custom function so are accessible through this object (缺省: Empty object)
failureMessage (可选) - {String} - message to be used upon validation failure (缺省: “Not valid!”)
返回值:
如果校验通过就返回true，失败则抛出包含失败提示信息的 Validate.Error 对象
例子:
// Pass a function that checks if a number is divisible by one that you pass it in args object
// In this case, 5 is passed, so should return true and validation will pass
Validate.Custom( 55, { against: function(value,args){ return !(value % args.divisibleBy) }, args: {divisibleBy: 5} } );now (静态方法) Top
Validates a passed in value using the passed in validation function, and handles the validation error for you so it gives a nice true or false reply
参数：
validationFunction - {Function} - reference to the validation function to be used (ie Validate.Presence )
value - {mixed} - value to be checked
validationParamsObj - {Object} - object containing parameters to be used for the validation (optional depends upon the validation function)
返回值：
true if valid or false if not valid
例子：
Validate.now( Validate.Numericality, '2007', { is: 2007 } );LiveValidation (class)
The LiveValidation class sets up a text, checkbox, file, or password input, or a textarea to allow its value to be validated in real-time based upon the validations you assign to it.
constructor 顶部
The constructor of the LiveValidation class to set up the form field as a LiveValidation object allows you to pass in any parameters you want to override.
参数:
value - {混合类型} - 需要校验的值
paramsObj (可选) - {对象} - 这个校验中需要用到的包含着各种参数的对象
paramsObj里的参数:
validMessage (可选) - {String} - 校验通过时输出的信息 (缺省: “Thankyou!”)
onValid (可选) - {Function} - 校验通过时执行的函数 (缺省: function(){ this.insertMessage( this.createMessageSpan() ); this.addFieldClass(); } )
onInvalid (可选) - {Function} - 校验失败时执行的函数 (缺省: function(){ this.insertMessage( this.createMessageSpan() ); this.addFieldClass(); })
insertAfterWhatNode (可选) - {mixed} - 页面上HTML节点的id，或对它的引用，用于将校验信息插入这个节点的后面来显示 (缺省: 这个被校验的表单域)
onlyOnBlur (可选) - {Boolean} - 确定是否当你的输入字符时就执行校验，还是当页面焦点转移时才执行校验 (缺省: false)
wait (可选) - {Integer} - 从你最后一次按键到开始校验之前延迟的时间 (毫秒) (缺省: 0)
onlyOnSubmit (可选) - {Boolean} - 校验的对象如果是个表单的域, 则这个用来标识是否只是当表单提交时才执行校验 (缺省: false)
返回值：
返回 LiveValidation 对象自己，这样可以用来执行连环调用
例子：
var myField = new LiveValidation('myField', { validMessage: "I am valid!", onlyOnBlur: true });add (方法) 顶部
使用传入的校验方法来校验传入的值，并且设置校验输出的信息
参数：
validationFunction - {Function} - 对用来进行校验的方法的引用 (例如 Validate.Presence )
validationParamsObj - {Object} - 校验时使用的包含有校验参数的对象 (可选项依赖于校验的函数)
返回值：
返回 LiveValidation 对象自己，这样可以用来执行连环调用
例子：
var myField = new LiveValidation('myField', { validMessage: "I am valid!" });
myField.add(Validate.Format, { pattern: /^hello$/i });remove (方法) 顶部
从添加了校验对象的堆栈里删除指定的校验
注意 - 你必须传进去一个跟你添加时绝对相同的参数
这个可以用于在页面上自己写代码来替换校验规则
参数：
validationFunction - {Function} - 对用来进行校验的方法的引用 (例如 Validate.Presence )
validationParamsObj - {Object} - 校验时使用的包含有校验参数的对象 (其中的可选项依赖于这些你添加校验时的情况)
返回值：
返回 LiveValidation 对象自己，这样可以用来执行连环调用
例子：
var myField = new LiveValidation('myField');
// add a Format and Length validation
myField.add(Validate.Format, { minimum: /^woohoo+$/ }).add(Validate.Length, {maximum: 20});
// now remove only the Format validation
myField.remove(Validate.Format, { minimum: /^woohoo+$/ });disable (方法) Top
用来使一个域失效，这样校验就不会在这个域上执行，如果它在一个表单中，那它也不会被当作表单域提交，以前加入的校验信息和css样式也会被去除掉。
这个可以用在当一个表单中的域要根据用户的选择而动态出现时使用。
返回值：
返回 LiveValidation 对象自己，这样可以用来执行连环调用
例子：
var myField = new LiveValidation('myField');
// disable the field - validations will not be run on this field, and its contents not submitted
myfield.disable();enable (方法) Top
使一个失效的表单域重新生效。
之前被禁止停用的域重新生效，使校验规则重新在这个域上发生作用。
返回值：
返回 LiveValidation 对象自己，这样可以用来执行连环调用
例子：
var myField = new LiveValidation('myField');
// disable the field - validations will not be run on this field
myfield.disable();
// enable the field again - validations will now be run again
myField.enable();destroy (方法) 顶部
注销 LiveValidation 对象上注册过的所有事件(preserving previously defined events)并且从所有拥有这个对象的 LiveValidationForm 中移除掉。
这个可以用在你不想某个域再被校验，或需要使用新的参数重新定义一个 LiveValidation 对象时使用。
例子：
var myField = new LiveValidation('myField');
myfield.destroy();massValidate (静态方法) Top
传入一个LiveValidation 对象队列，作为一个集合一起校验并返回是否校验通过
注意 - 在 1.2版本之后你永远都不需要用到这个方法了，因为全表单校验会在表单提交时自动执行。
参数：
validations - {Array} - 一个 LiveValidation 对象队列
返回值：
如果全部校验通过返回true, 只要有一个失败就返回false
例子：
// pass in an array of LiveValidation objects...
var areAllValid = LiveValidation.massValidate( [ obj1, obj2 ] );LiveValidationForm (类)
如果 LiveValidation 域属于一个表单form, 则这个表单会自动被转化成一个LiveValidationForm对象。这样可以控制在表单提交时校验这个Live, 当任何校验失败是立即终止表单的提交。
destroy (方法) 顶部
将会注销LiveValidationForm对象上的所有事件(preserving previously defined events), 但当有属于它的子LiveValidation对象存在时不会执行 (除非强制执行)
你几乎很少会用到这个方法，因为当LiveValidation对象被销毁时LiveValidationForm也自动被销毁, 只有在做测试时可能会有用处。
参数：
force - {Boolean} - 是否强制解构，即使和它关联的有子LiveValidation 对象
例子：
var myField = new LiveValidation('myField');
// access the LiveValidationForm object through one of its child LiveValidation objects form property
myfield.form.destroy(true);