mirror of
https://github.com/vxcontrol/ncform.git
synced 2026-07-20 22:05:47 -04:00
daniel.xiao
306 lines
8.6 KiB
Markdown
306 lines
8.6 KiB
Markdown
[English Version](CONFIG.md)
|
||
|
||
- 目录
|
||
- [Schema](#ncform-schema)
|
||
- [Props](#ncform-props)
|
||
- [API](#ncform-API)
|
||
- [Event](#ncform-event)
|
||
|
||
## ncform schema
|
||
|
||
```js
|
||
{
|
||
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
|
||
|
||
value: '', // 字段值
|
||
default: '', // 字段默认值。value为空时取该值
|
||
valueTemplate: '', // 值模板。根据提供的 dx表达式 动态计算 value 的值
|
||
|
||
/* UI */
|
||
ui: {
|
||
|
||
columns: 6, // 占用列数，共12列。【支持dx表达式】
|
||
label: '', // 标签内容【支持dx表达式】
|
||
showLabel: true, // 是否显示标签（注意：当为 false 时，依然占着空间）
|
||
noLabelSpace: false, // 标签是否不占空间，优先级比showLabel高
|
||
legend: '', // 标题内容，当 widget 为 object，array 等布局时有效【支持dx表达式】
|
||
showLegend: true, // 是否显示标题。
|
||
description: '', // 描述信息【支持dx表达式】
|
||
placeholder: '', // 占位内容【支持dx表达式】
|
||
disabled: false, // 是否禁用【支持dx表达式】
|
||
readonly: false, // 是否只读【支持dx表达式】
|
||
hidden: false, // 是否隐藏【支持dx表达式】
|
||
help: { // 帮助信息
|
||
show: true, // 是否显示。默认不显示
|
||
content: '', // 帮助具体内容
|
||
iconCls: '', // 帮助图标样式名
|
||
text: '' // 帮助文本
|
||
},
|
||
itemClass: '', // 表单项样式名
|
||
preview: { // 预览
|
||
type: '', // 预览类型。可选值：video / audio / image / link
|
||
value: '', // 默认值: 'dx: {{$self}}'【支持dx表达式】
|
||
clearable: false, // 是否显示删除按钮
|
||
outward: { // 外观，仅 type=image 时有效
|
||
width: 0, // 宽度，0代表无限制
|
||
height: 0, // 高度，0代表无限制
|
||
shape: '', // 外观形状。可选值：空值 / rounded / circle / ，默认值为空
|
||
}
|
||
},
|
||
linkFields: [ // 关联字段。当值发生变化时，会触发关联字段的一些动作，比如校验
|
||
{
|
||
fieldPath: '', // 关联项字段路径。如：'user.name'，'user[i].name'
|
||
rules: [], // 校验规则名，如：['required']
|
||
}
|
||
],
|
||
|
||
/* 渲染组件 */
|
||
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: { // 可选项
|
||
delay: 300, // 延迟验证的时间（毫秒）
|
||
delayMsg: '异步验证中..' // 延迟验证时的提示
|
||
}
|
||
},
|
||
number, // value:boolean
|
||
ajax, // value：{ remoteUrl: '<url>', method: '<get or post>', paramName: '<请求参数名，值为控件的值>', otherParams: {} }
|
||
|
||
// for Numeric Instances
|
||
minimum, // value: number
|
||
maximum, // value: number
|
||
multipleOf, // value: number
|
||
exclusiveMaximum, // value: number
|
||
exclusiveMinimum, // value: number
|
||
|
||
// for Strings
|
||
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, // value: any
|
||
maxItems, // value: number
|
||
minItems, // value: number
|
||
uniqueItems, // value: boolean
|
||
|
||
// for Objects
|
||
maxProperties, // value: number
|
||
minProperties, // value: number
|
||
|
||
/* 自定义的验证规则 */
|
||
customRule: [{
|
||
script: '', // 【支持dx表达式】
|
||
errMsg: '', // 验证错误信息
|
||
linkItems: [ // 当触发校验时，同时触发这些关联项的 customRule 规则校验（ 建议使用 ui.linkFields 来替代 ）
|
||
{
|
||
fieldPath: '', // 关联项字段路径。如：'user.name'，'user[i].name'
|
||
customRuleIdx: 0 // 触发该项的 customRule 的索引项规则
|
||
}
|
||
]
|
||
}]
|
||
},
|
||
}
|
||
},
|
||
globalConfig: { // 全局配置
|
||
ignoreRulesWhenHidden: true, // 当控件隐藏时自动忽略掉其验证规则，即隐藏的控件验证规则不生效。默认为true
|
||
style: { // 全局样式配置
|
||
formCls: '', // 添加到 form 的样式
|
||
invalidFeedbackCls: '', // 错误提示消息的样式
|
||
},
|
||
constants: { // 全局常量配置，可在dx表达中通过{{$const.}}来访问，如{{$const.userName}}
|
||
userName: 'daniel'
|
||
},
|
||
scrollToFailField: { // 自动滚动到校验失败的字段
|
||
enabled: true, // 是否开启
|
||
container: 'body', // 滚动的容器。
|
||
duration: 500, // 滚动动画的持续时间(以毫秒为单位)
|
||
offset: -80, // 滚动时的偏移量
|
||
}
|
||
}
|
||
}
|
||
|
||
```
|
||
|
||
## ncform props
|
||
|
||
- form-schema
|
||
|
||
用于描述表单的schema配置数据，具体数据结构请参考[ncform schema](#ncform-schema)
|
||
|
||
```
|
||
// Demo code
|
||
<ncform :form-schema="formSchema"></ncform>
|
||
```
|
||
|
||
- form-name
|
||
|
||
表单名称，当使用部分 [ncform API](#ncform-api) 时需要提供该值
|
||
|
||
```
|
||
// Demo code
|
||
<ncform form-name="your-form-name"></ncform>
|
||
```
|
||
|
||
- v-model
|
||
|
||
表单的值
|
||
|
||
```
|
||
// Demo code
|
||
<ncform :form-schema="formSchema" v-model="formSchema.value" ></ncform>
|
||
```
|
||
|
||
- is-dirty.sync
|
||
|
||
用于标识表单的值是否dirty（即修改）
|
||
|
||
通常的使用场景是通过该值，来判断提交按钮是否可用
|
||
|
||
```
|
||
// Demo code
|
||
<ncform :form-schema="formSchema" v-model="formSchema.value" :is-dirty.sync="isFormDirty"></ncform>
|
||
<button :disabled="!isFormDirty">提交</button>
|
||
```
|
||
|
||
## ncform API
|
||
|
||
ncform API 都是Vue实例级别的方法。
|
||
|
||
- $ncformReset(formName)
|
||
|
||
重置表单。重置的值为最后一次外部更新 `ncform v-model` 的值
|
||
|
||
外部更新是指你直接用新value更新ncform的v-model值，而非操作表单控件发生的v-model的值的更新
|
||
|
||
注意：当你保存完表单，想以最后一次保存的值为reset的值，需要外部更新下ncform的v-model值
|
||
|
||
```
|
||
// Demo code:
|
||
this.$ncformReset('demoForm');
|
||
```
|
||
|
||
- $ncformValidate(formName)
|
||
|
||
校验表单的所有字段的规则。
|
||
|
||
```
|
||
// Demo code:
|
||
this.$ncformValidate('demoForm').then(data => {
|
||
if (data.result) { // 校验通过
|
||
// do whatever you like to do. e.g. save form
|
||
}
|
||
})
|
||
```
|
||
|
||
- $ncformAddWidget({name, widget})
|
||
|
||
增加自定义表单控件
|
||
|
||
```
|
||
// Demo code:
|
||
this.$ncformAddWidget({name: 'sayHi', widget: {
|
||
mixins: [ncformCommon.mixins.vue.controlMixin],
|
||
template: '<div>hi {{modelVal}}</div>',
|
||
props: {
|
||
value: {
|
||
type: [String]
|
||
},
|
||
},
|
||
}});
|
||
```
|
||
|
||
- $ncformAddRule({name, rule})
|
||
|
||
增加自定义验证规则
|
||
|
||
```
|
||
// Demo code:
|
||
class MyCustomRule extends ncformCommon.ValidationRule {
|
||
|
||
constructor(props) {
|
||
super(props);
|
||
this.name = 'myCustom';
|
||
this.defaultErrMsg = 'yeah, show my custom rule message';
|
||
}
|
||
|
||
validateLogic(val, ruleVal) {
|
||
this.errMsg = "must fill in 'daniel'"
|
||
return val === 'daniel';
|
||
}
|
||
}
|
||
|
||
this.$ncformAddRule({name: 'myCustom', rule: MyCustomRule});
|
||
```
|
||
|
||
- $ncformAllRules()
|
||
|
||
取得ncform所有注册的校验规则
|
||
|
||
```
|
||
// Demo code:
|
||
const allRules = this.$ncformAllRules();
|
||
```
|
||
|
||
- $ncformAllWidgets()
|
||
|
||
取得ncform所有注册的表单组件
|
||
|
||
```
|
||
// Demo code:
|
||
const allWidgets = this.$ncformAllWidgets();
|
||
```
|
||
|
||
## ncform event
|
||
|
||
- submit
|
||
|
||
提交表单事件。
|
||
|
||
```
|
||
// Demo code:
|
||
<ncform @submit="submit()"></ncform>
|
||
```
|
||
|
||
- change
|
||
|
||
表单项值更改事件
|
||
|
||
```
|
||
// Demo code:
|
||
<ncform @change="onChange"></ncform>
|
||
|
||
onChange({paths, itemValue, formValue}) {
|
||
// paths: 发生值变化的项的路径
|
||
// itemValue：发生值变化的项的最新值
|
||
// formVallue: 表单的最新值
|
||
}
|
||
```
|