vxcontrol/ncform
1
0
Fork 0
mirror of https://github.com/vxcontrol/ncform.git synced 2026-07-19 18:23:32 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve docs

Browse Source
This commit is contained in:
daniel.xiao
2019-03-19 17:20:36 +08:00
parent c248887f8f
commit ca4825084d
4 changed files with 132 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONFIG.md
+63 -58
View File
@@ -9,31 +9,31 @@
## ncform schema
```js
{
type: 'object', // Root node: can only be object
properties: { // Root node: form fields
firstName: {
type: 'object', // Root node. object type only
properties: {
<field name>: {
/* Data */
type: 'string', // Data type: string / number / integer / boolean / object / array / HTML / COMP
// Note: The type of uppercase is a special read-only type, and the general scenario is to display a separator bar. This data will be automatically filtered out
// HTML: configure "value" field, the value is a piece of HTML [support dx expression];
// COMP: configure ui.widget and ui.widgetConfig
type: 'string', // Data type. options: string / number / integer / boolean / object / array / HTML / COMP
// Note: The type of uppercase is a special read-only type, and the common use case is to display a separator bar. The data will be auto filtered out when the form is submitted.
// HTML: set "value", the value is a piece of HTML [support dx expression];
// COMP: set ui.widget and ui.widgetConfig
value: '', // Value of the data
default: '', // The default value of the data. When the "value" is empty, take this one.
valueTemplate: '', // Value template. note: when there is a "dx expression" inside, the expression value changes, it will overwrite the value filled by the user
value: '', // Value of the field
default: '', // The default value of the field. Take this one when the "value" is empty.
valueTemplate: '', // Value template. Dynamically calculate the "value" based on the supplied dx expression [support dx expression]
/* UI */
ui: {
columns: 6, // The number of columns, total is 12. 6 represents half
label: 'First Name', // Label display content [support dx expression]
columns: 6, // Total are 12 columns.
label: '', // Label display [support dx expression]
showLabel: true, // Whether to show the label (when it is false, it still takes up space)
noLabelSpace: false, // Whether the label does not occupy space, the priority is higher than showLabel
legend: '', // Legend content, valid when the type is object or array [support dx expression]
showLegend: true, // Whether to display the legend. When the type is object or array, showLegend takes precedence over showLabel, so the label takes effect when showLegend is set to false.
description: 'Fill in the first name', // Field description information [support dx expression]
placeholder: 'first name', // Placeholder content [support dx expression]
showLegend: true, // Whether to display the legend. (Note: when it is an object widget, only one of legend and label can be valid, and legend takes precedence over label)
description: '', // Description information [support dx expression]
placeholder: '', // Placeholder content [support dx expression]
disabled: false, // Whether to disable [support dx expression]
readonly: false, // Whether read-only [support dx expression]
hidden: false, // Whether to hide [support dx expression]
@@ -43,93 +43,98 @@
iconCls: '', // Help icon class name
text: '' // Help text
},
itemClass: '', // The class name added to the form item
itemClass: '', // The form item class name
preview: { // Preview
type: '', // Preview type, optional values: video / audio / image / link
type: '', // Preview type. Options: video / audio / image / link
value: '', // Default: 'dx: {{$self}}' [supports dx expressions]
clearable: false, // Whether it can be cleared
outward: { // outward appearance
clearable: false, // Whether to display the clear button
outward: { // outward appearance. Valid only if type=image
width: 0, // Width, 0 means unlimited
height: 0, // Height, 0 means unlimited
shape: '', // Appearance shape, optional values: '' / rounded / circle. default is ''
shape: '', // Appearance shape. Options: '' / rounded / circle. default is ''
}
},
linkFields: [ // Associated fields, when the value changes, it will trigger some actions of the associated field, such as rules check
linkFields: [ // Associated fields. when the value changes, it will trigger some actions of the associated field, such as rules check
{
fieldPath: '', // The associated item field path. When it is an array item, use [i], such as a.b[i].c
rules: [], // the rules, such as required, number
fieldPath: '', // The associated item field path. such as 'user.name'，'user[i].name'
rules: [], // The rules, such as ['required']
}
],
/* Rendering Widget */
widget: 'textarea', // Widget component name
widget: '', // Widget component name
widgetConfig: {}, // widget component config
},
/* Verification rules */
rules: {
// All validation rules have two forms of assignment:
        // Simple version: <rule name>: <rule value>. Such as required: true, minimum: 10
        // Detailed version: <rule name>: { value: <rule value>, errMsg: '', options: { deplay: xxx, delayMsg: '' } }. Such as the following required example
// for Any Instance Type
required: {
value: true, // The value passed to the validation rule
errMsg: 'it is required!', // Error message
options: { // Validation rule options
options: { // Rule options
delay: 300, // Delayed verification time (ms)
delayMsg: 'Checking...' // Prompt for delayed verification
}
},
number,
number, // value:boolean
ajax, // Value: { remoteUrl: 'remote api url', method: 'get or post', paramName: 'request parameter name, the value is the control\'s value', otherParams: {} }
// for Numeric Instances
minimum,
maximum,
multipleOf,
exclusiveMaximum,
exclusiveMinimum,
minimum, // value: number
maximum, // value: number
multipleOf, // value: number
exclusiveMaximum, // value: number
exclusiveMinimum, // value: number
// for Strings
url,
tel,
ipv4,
ipv6,
email,
pattern,
hostname,
dateTime,
maxLength,
minLength,
url, // value: boolean
tel, // value: boolean
ipv4, // value: boolean
ipv6, // value: boolean
email, // value: boolean
pattern, // value: string。 such as "\\d+"
hostname, // value: boolean
dateTime, // value: boolean
maxLength, // value: number
minLength, // value: number
// for Arrays
contains,
maxItems,
minItems,
uniqueItems,
contains, // value: any
maxItems, // value: number
minItems, // value: number
uniqueItems, // value: boolean
// for Objects
maxProperties,
minProperties,
maxProperties, // value: number
minProperties, // value: number
/* Custom Validation Rules */
customRule: [{
script: '', // [Support dx expression]
errMsg: '', // Error message
linkItems: [ // When the check is triggered, these associated items are also triggered for verification (recommended to use ui.linkFields instead of this feature)
linkItems: [ // When the check is triggered, the customRule rule validation of these associated items is also triggered (recommended using ui.linkFields instead)
{
fieldPath: '', // The associated item field path. When it is an array item, use [i], such as a.b[i].c
customRuleIdx: 0 // The index of the triggered item's custom validation rules
fieldPath: '', // The associated item field path. such as 'user.name'，'user[i].name'
customRuleIdx: 0 // The index of the customRule of the link item
}
]
}]
},
}
},
globalConfig: { // Root node: global configuration
ignoreRulesWhenHidden: true, // When the control is hidden, its validation rules are automatically ignored, Default is true
globalConfig: { // Global configuration
ignoreRulesWhenHidden: true, // When the controls are hidden, its validation rules are automatically ignored. Default is true
style: { // Global style configuration
formCls: '', // form class
invalidFeedbackCls: '', // invalid feedback class
formCls: '', // Form class
invalidFeedbackCls: '', // Invalid feedback class
},
constants: { // Global constant configuration, accessible via {{$const.}} in dx expressions, such as {{$const.userName}}
constants: { // Global constant configuration, can be accessed by {{$const.userName}}
userName: 'daniel'
}
}
@@ -141,7 +146,7 @@
- form-schema
Used to describe the schema configuration data of the form. For the specific data structure, please refer to [ncform schema](#ncform-schema)
Used to describe the schema configuration of the form. For the specific data structure, please refer to [ncform schema](#ncform-schema)
```
// Demo code
@@ -170,7 +175,7 @@ Form value
Is used to identify whether the value of the form is dirty (ie modified)
The usual usage scenario is to use this value to determine if the submit button is available.
The common use case is to determine if the submit button is available.
```
// Demo code
@@ -203,7 +208,7 @@ Verify all fields of the form.
// Demo code:
this.$ncformValidate('demoForm').then(data => {
if (data.result) { // Verification pass
// do whatever you like to do. e.g. save form
// do whatever you like to do. e.g. save data
}
})
```
CONFIG_CN.md
+67 -62
View File
@@ -10,125 +10,130 @@
```js
{
type: 'object', // 根节点：只能是object
properties: { // 根节点：表单字段
firstName: {
type: 'object', // 根节点。只能是 object
properties: {
<filed name>: {
/* 数据 */
type: 'string', // 数据类型 string / number / integer / boolean / object / array / HTML / COMP
// 注意：大写的类型为特殊只读类型，一般应用场景为显示一个分隔栏。该数据会自动过滤掉
// HTML: 配置value，值为一段HTML【支持dx表达式】;
// COMP: 配置ui.widget和ui.widgetConfig
type: 'string', // 数据类型。可选：string / number / integer / boolean / object / array / HTML / COMP
// 注意：大写的类型为特殊只读类型，一般使用场景为显示一个分隔栏。该数据在提交表单时会自动过滤掉
// HTML: 配置 value，值为一段HTML【支持dx表达式】;
// COMP: 配置 ui.widget 和 ui.widgetConfig
value: '', // 数据的值
default: '', // 数据的默认值，value为空的时候取该值
valueTemplate: '', // 值模板，当里面有dx表达式时，表达式值发生改变，会优化取该值作为value（即会覆盖用户所填的值）
value: '', // 字段值
default: '', // 字段默认值。value为空时取该值
valueTemplate: '', // 值模板。根据提供的 dx表达式 动态计算 value 的值
/* UI */
ui: {
columns: 6, // 占用列数，一共12列。6代表占一半
label: 'First Name', // 标签内容【支持dx表达式】
showLabel: true, // 是否显示标签（当为false不显示时，依然占着空间）
columns: 6, // 占用列数，共12列。
label: '', // 标签内容【支持dx表达式】
showLabel: true, // 是否显示标签（注意：当为 false 时，依然占着空间）
noLabelSpace: false, // 标签是否不占空间，优先级比showLabel高
legend: '', // 标题内容，当对象，数组布局数据类型时有效【支持dx表达式】
showLegend: true, // 是否显示标题。当为object类型时，showLegend优先于showLabel，所以需要设置showLegend为false时label才生效
description: 'Fill in the first name', // 字段描述信息【支持dx表达式】
placeholder: 'first name', // 占位内容【支持dx表达式】
legend: '', // 标题内容，当 widget 为 object，array 等布局时有效【支持dx表达式】
showLegend: true, // 是否显示标题。（注意：当为 object widget 时，legend 和 label 二选一，且 legend 优先于 label）
description: '', // 描述信息【支持dx表达式】
placeholder: '', // 占位内容【支持dx表达式】
disabled: false, // 是否禁用【支持dx表达式】
readonly: false, // 是否只读【支持dx表达式】
hidden: false, // 是否隐藏【支持dx表达式】
help: { // 帮助信息
show: true, // 是否显示，默认不显示
content: '', // 帮助信息
show: true, // 是否显示。默认不显示
content: '', // 帮助具体内容
iconCls: '', // 帮助图标样式名
text: '' // 帮助文字
text: '' // 帮助文本
},
itemClass: '', // 给表单项添加的样式名
itemClass: '', // 表单项样式名
preview: { // 预览
type: '', // 预览类型，可选值：video / audio / image / link
type: '', // 预览类型。可选值：video / audio / image / link
value: '', // 默认值: 'dx: {{$self}}'【支持dx表达式】
clearable: false, // 是否可删除
outward: { // 外观
clearable: false, // 是否显示删除按钮
outward: { // 外观，仅 type=image 时有效
width: 0, // 宽度，0代表无限制
height: 0, // 高度，0代表无限制
shape: '', // 外观形状，可选值：空值 / rounded / circle / ，默认值为空
shape: '', // 外观形状。可选值：空值 / rounded / circle / ，默认值为空
}
},
linkFields: [ // 关联字段，当值发生变化时，会触发关联字段的一些动作，比如校验
linkFields: [ // 关联字段。当值发生变化时，会触发关联字段的一些动作，比如校验
{
fieldPath: '', // 关联项字段路径。当为数组项时，则用[i]，如a.b[i].c
rules: [], // 校验规则名，如required, number
fieldPath: '', // 关联项字段路径。如：'user.name'，'user[i].name'
rules: [], // 校验规则名，如：['required']
}
],
/* 渲染组件 */
widget: 'textarea', // 渲染的组件名
widget: '', // 渲染组件名
widgetConfig: {}, // 组件配置
},
/* 验证规则 */
rules: {
// 所有验证规则都有两种赋值形式：
// 简单版：<rule name>: <rule value>。如 required: true，minimum: 10
// 详细版：<rule name>: { value: <rule value>, errMsg: '', options: { deplay: xxx, delayMsg: '' } }。如以下 required 示例
// for Any Instance Type
required: {
value: true, // 传给验证规则的配置值
errMsg: 'it is required!', // 错误信息
options: { // 验证规则选项
value: true, // 规则配置值
errMsg: 'it is required!', // 错误提示信息
options: { // 可选项
delay: 300, // 延迟验证的时间（毫秒）
delayMsg: '异步验证中..' // 延迟验证时的提示
}
},
number,
ajax, // value值：{ remoteUrl: '远程接口Url', method: 'get or post', paramName: '请求参数名，值为控件的值', otherParams: {} }
number, // value:boolean
ajax, // value：{ remoteUrl: '<url>', method: '<get or post>', paramName: '<请求参数名，值为控件的值>', otherParams: {} }
// for Numeric Instances
minimum,
maximum,
multipleOf,
exclusiveMaximum,
exclusiveMinimum,
minimum, // value: number
maximum, // value: number
multipleOf, // value: number
exclusiveMaximum, // value: number
exclusiveMinimum, // value: number
// for Strings
url,
tel,
ipv4,
ipv6,
email,
pattern,
hostname,
dateTime,
maxLength,
minLength,
url, // value: boolean
tel, // value: boolean
ipv4, // value: boolean
ipv6, // value: boolean
email, // value: boolean
pattern, // value: string。 如 "\\d+"
hostname, // value: boolean
dateTime, // value: boolean
maxLength, // value: number
minLength, // value: number
// for Arrays
contains,
maxItems,
minItems,
uniqueItems,
contains, // value: any
maxItems, // value: number
minItems, // value: number
uniqueItems, // value: boolean
// for Objects
maxProperties,
minProperties,
maxProperties, // value: number
minProperties, // value: number
/* 自定义的验证规则 */
customRule: [{
script: '', // 【支持dx表达式】
errMsg: '', // 验证错误信息
linkItems: [ // 当触发校验时，同时触发这些关联的项进行校验（ 建议使用ui.linkFields来替代这里的功能 ）
linkItems: [ // 当触发校验时，同时触发这些关联项的 customRule 规则校验（ 建议使用 ui.linkFields 来替代 ）
{
fieldPath: '', // 关联项字段路径。当为数组项时，则用[i]，如a.b[i].c
customRuleIdx: 0 // 触发该项的自定义验证规则的索引
fieldPath: '', // 关联项字段路径。如：'user.name'，'user[i].name'
customRuleIdx: 0 // 触发该项的 customRule 的索引项规则
}
]
}]
},
}
},
globalConfig: { // 根节点：全局配置
globalConfig: { // 全局配置
ignoreRulesWhenHidden: true, // 当控件隐藏时自动忽略掉其验证规则，即隐藏的控件验证规则不生效。默认为true
style: { // 全局样式配置
formCls: '', // form class
invalidFeedbackCls: '', // invalid feedback class
formCls: '', // 添加到 form 的样式
invalidFeedbackCls: '', // 错误提示消息的样式
},
constants: { // 全局常量配置，可在dx表达中通过{{$const.}}来访问，如{{$const.userName}}
userName: 'daniel'
@@ -151,7 +156,7 @@
- form-name
表单名称，当使用部分[ncform API](#ncform-api)时需要提供该值
表单名称，当使用部分 [ncform API](#ncform-api) 时需要提供该值
```
// Demo code
README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# ncform
[![CircleCI](https://circleci.com/gh/ncform/ncform/tree/e2e.svg?style=svg)](https://circleci.com/gh/ncform/ncform/tree/e2e)
[![CircleCI](https://img.shields.io/circleci/project/github/ncform/ncform/master.svg)](https://circleci.com/gh/ncform/ncform/tree/master)
![vue 2.x](https://img.shields.io/badge/vue-2.x-green.svg)
![license MIT](https://img.shields.io/npm/l/vue.svg)
[![Cypress.io tests](https://img.shields.io/badge/cypress.io-tests-green.svg?style=flat-square)](https://dashboard.cypress.io/#/projects/enxoqt/runs)
README_CN.md
+1 -1
View File
@@ -1,6 +1,6 @@
# ncform
[![CircleCI](https://circleci.com/gh/ncform/ncform/tree/e2e.svg?style=svg)](https://circleci.com/gh/ncform/ncform/tree/e2e)
[![CircleCI](https://img.shields.io/circleci/project/github/ncform/ncform/master.svg)](https://circleci.com/gh/ncform/ncform/tree/master)
![vue 2.x](https://img.shields.io/badge/vue-2.x-green.svg)
![license MIT](https://img.shields.io/npm/l/vue.svg)
[![Cypress.io tests](https://img.shields.io/badge/cypress.io-tests-green.svg?style=flat-square)](https://dashboard.cypress.io/#/projects/enxoqt/runs)