@blueking/bkui-form 0.0.4

package/readme.md

@@ -0,0 +1,410 @@
+# README
+
+### schema 协议
+
+```js
+{
+    "schema": {
+        "title": String, // 必需，整个表单的title说明
+        "description": String, // 可选，整个表单描述信息
+        "type": Object, // 固定值为对象类型
+        "properties": { // 必需
+            "fieldKey": { // 必需， 单个表单组件的key，根据业务需求自定义
+                "type": String | Number | Boolean | Array | Object, // 必需，表单组件value的数据类型
+                "title": String, // 必需，表单组件的label
+                "default": String | Number | Boolean | Array | Object, // 可选，表单组件的默认值
+                "required": Boolean, // 可选，是否为必填项，默认为false
+                "ui:field": {},
+                "ui:component": { // 可选，单个表单所需要渲染的目标组件元素，若不配置则默认为magicbox组件的input组件
+                    "name": String, // 必需，所需渲染组件的名称，例如组件库里的bk-input、bk-table，也可以是通过插件注册的自定义组件
+                    "props": { // 可选，透传到组件的属性，可传入的属性由渲染的组件决定，组件支持的属性都可传入
+                        "dataSource": Array < Object: {
+                            label: String,
+                            value: String | Numnber | Boolean
+                        } > , // 可选，用户可枚举选项的表单类型比如：下拉框、复选框、表格等组件，配置选项
+                        "remoteConfig": { // 可选，可枚举选项类型表单加载远程数据源时，用来配置请求参数，参数会默认传到内置的$loadSourceData方法里, 如果需要加载远程数据需要在reactions里实现
+                            "url": String,
+                            "method": String,
+                            "headers": Object,
+                            "params": Object,
+                            "data": Object
+                        },
+                        "value": String | Number | Boolean | Array | Object, // 可选
+                        "disabled": Boolean, // 可选
+                        "readonly": Boolean, // 可选
+                        "placeholder": String, // 可选
+                        ... // 目标组件支持的其他props选项
+                    },
+                    "slot": {}, // 可选，组件原生支持的slot
+                    "event": {}, // 可选，组件原生支持的事件
+                },
+                "ui:reactions": [{
+                    "target": String, // 可选，目标表单的 path
+                    "source": String | String[], // 可选，依赖表单的 path，如果依赖多个，则需要用数组描述
+                    "lifetime": String, // 可选，由当前表单组件的生命周期触发，init、change、destroy
+                    "effect": String, // 可选，由依赖表单的事件触发，比如button组件的 click 事件
+                    "if": String | Soolean, // 可选，联动是否生效，支持写表达式字符串和布尔值，表达式的返回值需要为布尔值
+                    "then": { // 可选，条件满足或者默认触发后执行
+                        "state": IFormState // 可选，修改表单项的状态，比如visible、value、disabled等
+                        "actions": Array < IBaseFunction > // 可选，调用内置方法，比如loadSourceData，validate
+                    },
+                    "else": { // 不满足条件时执行
+                        "state": IFormState,
+                        "actions": Array < IBaseFunction >
+                    }
+                }],
+                "ui:validator": [{ // 可选，表单项的校验配置，可以单独定义校验规则，也可以引用全局的定义的rules
+                    "rule": String, // 必需，校验表达式字符串
+                    "message": String // 必需，校验失败错误提示信息
+                } | String], // 通过"{{ $rules.rule_name }}"的方式引用全局定义的校验规则
+                "ui:props": { // 可选，单个表单项的属性配置，按需传入
+                    "tips": String, // 可选，表单项label的tips说明
+                    "visible": Boolean | Function, // 可选，表单项是否可见，支持函数通过返回值动态设置，函数context注入整个表单项的value，默认为 true
+                    "disabled": Boolean | Function, // 可选，表单项是否禁用，默认为false
+                    "className": String, // 表单项外层容器元素的class名称
+                    ... // 后续扩展
+                },
+            }
+        }
+    },
+    "layout": [], // 可选，定义各表单元素的位置信息，整体表单按照grid布局方式提供配置，默认按照从上往下单列表单项的布局方式排列
+    "rules": { // 可选，定义全局通用的校验规则，可以在单个表单的校验配置项里引用
+        "rule_name": { // rule_name 为自定义的校验规则名称
+            "validator": String, // 自定义校验表达式，eg: "{{ $self.value.length > 20 && $getValue('a.b.c').value !== '' }}"
+            "message": String, // 校验失败错误提示信息
+        },
+    }
+}
+```
+
+### demo
+
+```js
+{
+    "schema": {
+        "title": "job_execute_task",
+        "description": "作业平台(JOB)-执行作业",
+        "type": "object",
+        "properties": {
+            "biz_cc_id": {
+                "type": "number",
+                "title": "业务id",
+                "default": 3,
+                "ui:component": {
+                    "name": "select",
+                    "props": {
+                        "disabled": true,
+                        "dataSource": [{
+                            "label": "蓝鲸",
+                            "value": 3
+                        }]
+                    }
+                },
+                "ui:props": {
+                    "required": true
+                },
+                "ui:reactions": [{
+                    "lifetime": "init",
+                    "if": "{{ $self.value !== '' }}",
+                    "else": {
+                        "state": "{{ $context.bizId }}"
+                    }
+                }],
+                "extend": {
+                    "can_hook": true
+                }
+            },
+            "job_task_id": {
+                "type": "string",
+                "title": "执行方案",
+                "default": "",
+                "ui:component": {
+                    "name": "select",
+                    "props": {
+                        "datasource": {
+                            "url": "{{ $context.bizId ? '' : $context.site_url + 'pipeline/job_get_job_tasks_by_biz/' + $context.bizId + '/' }}",
+                            "header": {},
+                            "params": {},
+                            "data": {}
+                        }
+                    }
+                },
+                "ui:reactions": [{
+                        "lifetime": "init",
+                        "then": {
+                            "actions": ["{{ $loadDataSource }}"]
+                        }
+                    },
+                    {
+                        "source": ["biz_cc_id"],
+                        "then": {
+                            "actions": ["{{ $loadDataSource }}"]
+                        }
+                    },
+                    {
+                        "source": ["button_refresh"],
+                        "effect": "click",
+                        "then": {
+                            "actions": ["{{ $loadDataSource }}"]
+                        }
+                    }
+                ],
+                "ui:validator": [
+                    "{{ $rules.max20 }}",
+                    {
+                        "rule": "{{ $self.value.length > 0 && $getValue('biz_cc_id') }}",
+                        "message": "执行方案不能为空"
+                    }
+                ],
+                "ui:props": {
+                    "required": true
+                }
+            },
+            "button_refresh": {
+                "type": "string",
+                "title": "",
+                "ui:component": {
+                    "name": "button",
+                    "props": {
+                        "theme": "primary",
+                        "word": "刷新"
+                    }
+                }
+            },
+            "job_global_var": {
+                "type": "array",
+                "title": "全局变量",
+                "default": "",
+                "ui:component": {
+                    "name": "table",
+                    "props": {
+                        "dataSource": []
+                    }
+                },
+                "extend": {
+                    "can_hook": true
+                }
+            },
+            "ip_is_exist": {
+                "type": "boolean",
+                "title": "IP 存在性校验",
+                "default": true,
+                "ui:component": {
+                    "name": "radio",
+                    "props": {
+                        "dataSource": [{
+                                "label": "是",
+                                "value": true
+                            },
+                            {
+                                "label": "否",
+                                "value": false
+                            }
+                        ]
+                    }
+                },
+                "extend": {
+                    "can_hook": true
+                }
+            },
+            "biz_across": {
+                "type": "boolean",
+                "title": "IP 允许跨业务",
+                "default": false,
+                "ui:component": {
+                    "name": "radio",
+                    "props": {
+                        "dataSource": [{
+                                "label": "是",
+                                "value": true
+                            },
+                            {
+                                "label": "否",
+                                "value": false
+                            }
+                        ]
+                    }
+                },
+                "extend": {
+                    "can_hook": true
+                }
+            },
+            "is_tagged_ip": {
+                "type": "boolean",
+                "title": "IP Tag 分组",
+                "default": true,
+                "ui:component": {
+                    "name": "radio",
+                    "props": {
+                        "dataSource": [{
+                                "label": "是",
+                                "value": true
+                            },
+                            {
+                                "label": "否",
+                                "value": false
+                            }
+                        ]
+                    }
+                },
+                "extend": {
+                    "can_hook": true
+                }
+            },
+            "job_success_id": {
+                "type": "string",
+                "title": "JOB成功历史",
+                "default": "",
+                "ui:component": {
+                    "name": "select",
+                    "props": {
+                        "remoteConfig": {
+                            "url": "{{ $context.bizId ? '' : $context.site_url + 'pipeline/job_get_job_tasks_by_biz/' + $context.bizId + '/' }}",
+                            "header": {},
+                            "params": {},
+                            "data": {}
+                        }
+                    }
+                },
+                "ui:reactions": [{
+                        "lifetime": "init",
+                        "then": {
+                            "actions": ["{{ $loadDataSource }}"]
+                        }
+                    },
+                    {
+                        "source": ["biz_cc_id"],
+                        "then": {
+                            "actions": ["{{ $loadDataSource }}"]
+                        }
+                    },
+                    {
+                        "source": ["button_refresh_2"],
+                        "effect": "click",
+                        "then": {
+                            "actions": ["{{ $loadDataSource }}"]
+                        }
+                    }
+                ]
+            },
+            "button_refresh_2": {
+                "type": "string",
+                "title": "",
+                "ui:component": {
+                    "name": "button",
+                    "props": {
+                        "word": "刷新"
+                    }
+                }
+            },
+            "job_success_id_static": {
+                "type": "string",
+                "title": "JOB成功历史(静态)",
+                "default": "official",
+                "ui:component": {
+                    "name": "select",
+                    "props": {
+                        "datasource": [{
+                                "value": "official",
+                                "label": "官方插件"
+                            },
+                            {
+                                "value": "external",
+                                "label": "第三方插件"
+                            },
+                            {
+                                "value": "scripts",
+                                "label": "脚本插件"
+                            }
+                        ]
+                    }
+                }
+            }
+        }
+    },
+    "layout": [
+        ["biz_cc_id"],
+        ["job_task_id", "button_refresh"],
+        ["job_global_var"],
+        ["ip_is_exist"],
+        ["biz_across"],
+        ["is_tagged_ip"],
+        ["job_success_id", "button_refresh_2"],
+        ["job_success_id_static"]
+    ],
+    "rules": [{
+        "max20": {
+            "validator": "{{ $self.value.length <= 20 }}",
+            "message": "方案名称的长度不能超过20个字符"
+        }
+    }]
+}
+```
+
+### schema 中内置的对象和方法
+
+表单插件提供了一些内置对象和内置方法，可以在schema中支持表达式的地方使用，可以满足一些动态获取值的场景，例如在单个组件初始化的时候调用远程数据源，则可以在定义的 reactions 里使用 `$loadDataSource` 方法。
+
+- 内置对象
+
+  - $self 当前表单 widget 的 vue 组件实例
+  - $context 具体业务使用方传入的全局上下文
+  - $dep reactions 中源（由source定义）表单 vue 组件实例，数组类型，按照source中定义的顺序访问对应的表单实例
+  - $rules schema 里定义的全局通用的校验规则
+  - $schema 当前表单组件的 schema 配置
+
+- 内置方法
+  - $getValue 获取表单组件实例的值，参数为表单路径，eg: 'a.b.c'
+  - $loadSourceData 可枚举选项类型表单加载远程数据源的方法，通过 remote_config 配置请求参数
+  - $validate 表单项的校验方法
+
+### 表单联动
+
+各表单组件之间的联动是通过`ui:reactions`定义的，插件支持主动联动和被动联动两种方式。主动联动是指当前的表单满足特定条件时，目标表单(target属性定义)执行对应的行为，被动联动是指源表单(source属性定义)满足特定条件时，当前的表单执行对应的行为。
+
+主动联动示例，key为spec的表单下的子表单的值发生变化，当值为a时，当前表单显示，不为a时当前表单隐藏：
+```js
+  {
+    "ui:reactions": [
+      {
+        "target": "spec.node",
+        "if": "{{ $self.value === 'a' }}",
+        "then": {
+          "state": {
+            "visible": true
+          }
+        },
+        "else": {
+          "state": {
+            "visible": false
+          }
+        }
+      }
+    ]
+  }
+```
+
+被动联动示例，key为biz_cc_id的表单初始化时，当前表单执行加载远程数据源方法：
+```js
+  {
+    "ui:reactions": [
+      {
+        "source": ["biz_cc_id"],
+        "lifetime": "init",
+        "then": {
+          "actions": ["{{ $loadDataSource }}"]
+        }
+      }
+    ]
+  }
+```
+
+### 表单校验
+
+1. 内置校验，比如当前表单值是否为空，正整数，最大值，最小值，最大长度，最小长度，正则校验
+2. 依赖校验，当前表单值的校验依赖其他表单的值，**需要提供 schema 中获取其他整个表单值的对象，并且能够按照一定的 path 规则获取到目标表单的值**
+3. 自定义校验，对于相对复杂的场景，支持写自定义校验函数，返回 result 和 message
+
+### 表单生命周期
+
+目前只提供了表单组件初始化的声明周期( `init`)