Hyb-Naive

深浅模式

HForm ​

这是一个对NaiveUI表单组件Form，进行JSON配置化处理，简化其复杂的实现过程，主要包含两种模式：FORM（表单录入），FILTER（筛选器）两种模式

筛选器 ​

自定义搜索按钮 ​

可以通过插槽slot(search)完全自定义搜索区，或通过props(searchBtn)属性更改按钮的文案

vue
<template>
  <HForm type="FILTER"  :rules="filterRules" @search="search" @reset="reset"> 
    <template #search>
      <div>
        <button>1</button>
        <button>2</button>
        <button>3</button>
        <button>4</button>
      </div>
    </template>
  </HForm>
</template>
vue
<template>
  <HForm 
    type="FILTER" 
    :rules="filterRules"
    @search="search" 
    @reset="reset"
    :search-btn="{
      search: { text: '查询', loading: searchLoading },
      reset: { text: '更多' },
    }"/> 
</template>

表单录入 ​

动态数据 ​

需要对表单设置为响应式数据，使用reactive或ref修饰,然后使用onLoad钩子函数(只加载一次)，进行数据的远程加载,最后通过HFormApi的setOptionsAPI，进行表单数据的绑定操作

ts
const HFormRules = reactive<HFormRule[]>([
  {
    field: 'grade',
    compType: 'Select',
    label: '年级',
    required: true,
    onLoad(fApi:HFormApi){
      setTimeout(()=>{
        fApi.setOptions('grade',[
          { label: '1年级', value: '1' },
          { label: '2年级', value: '2' },
        ])
      },1000)
    }
  },
])

详细示例如下

表单项联动操作 ​

表单项之间若存在依赖关系，可以通过暴漏的HFormApi对象，进行表单项间的动态联动操作

根据年龄联动年级

当年龄小于18岁时，年级为1年级；大于等于18岁为2年级

ts
{
  field: 'age',
  compType: 'InputNumber',
  label: '年龄',
  required: true,
  props(formApi: HFormApi) { 
    return {
      onChange(value: number) {
        //设置年级可选数据
        if (value < 16) {
          formApi.setOptions('grade', [{ label: '1年级', value: '1' },])
        } else {
          formApi.setOptions('grade', [ { label: '2年级', value: '3' },])
        }
      },
    }
  },
}

示例效果如下：

自定义表单项 ​

在某些场景下，有些组件不满足需求，可以通过自定表单项的方式进行实现。

vue
<template>
  <HForm type="FORM" card :rules="HFormRules" @confirm="commit" >
    <template #grade>
      <!-- TODO 自定义表单项 -->
    </template>
  </HForm>
</template>
<script lang="ts" setup>
import { HFormRule, HForm, HFormApi} from 'hyb-naive'
import { reactive,ref } from 'vue'

const HFormRules = reactive<HFormRule[]>([
  {
    field: 'grade',
    compType: 'Slot', 
    label: '年级',
    span:24,
    required: true,
  },
])

const formData = ref({})

function commit(data: object) {
  console.log('formData=', data)
  formData.value=data
}
</script>

示例：自定义性格标签

通过自定义项和validator校验器，实现表单的数据验证，validator具体使用，请查看naive-ui/lib/form/src/interface下的FormItemRuleValidator，自定义组件中对外暴露出了HFormApi中的功能和对象，这里使用了#character={formData} 通过标签的数据变化时间，绑定到表单数据中@update:value="($event)=>formData.character=$event"

具体效果和完整代码如下：

组件示例 ​

HFormApi ​

前面多次提到了HFormApi，很多的一些操作都是通过他

具体Api内容如下 ​

字段说明类型默认值
formData表单数据-{}
setFormData设置整个表单数据(formData: object) => void-
setValue设置表单项数据, 并返回表单值(field: string, value: any) => Promise<any>-
setValues设置多个表单项数据, 并返回表单值(values: object) => Promise<any>-
setRule设置表单规则(field: string, rule: HFormRule) => HFormRule-
getRule获取表单规则(field: string) => HFormRule | undefined-
mergeRule合并表单规则(field: string, rule: HFormRule) => HFormRule-
setOptions设置表单数据选择项(field: string, options: Array<{ label?: string; value?: any; [key: string]: any }>) => Promise<any>-
validate校验表单() => Promise<object>-
search触发搜索(formData?: object) => void-
reset重置表单() => void-
rules表单规则--
value当前表单项的值（可选）--
rule表单规则（可选）--

补充说明 ​

  • formData：用于存储表单的数据，默认是一个空对象。
  • setFormData：用于设置整个表单的数据，参数为一个对象。
  • setValue 和 setValues：分别用于设置单个表单项和多个表单项的数据，返回更新后的表单数据。
  • setRule 和 getRule：用于设置和获取表单规则，参数为字段名和规则对象。
  • mergeRule：与 setRule 不同，它只更新指定字段的规则，而不是替换整个规则。
  • setOptions：用于设置表单项的选项，参数为字段名和选项数组，返回更新后的选项列表。
  • validate：用于校验表单，返回校验结果。
  • search：触发搜索操作，可以传递表单数据作为参数。
  • reset：重置表单，清除所有表单数据。
  • rules：定义表单的规则集合。
  • value 和 rule：可选字段，用于存储表单数据和规则。只有在表单项钩子函数中才有值

怎样获取HFormApi？ ​

  1. 通过组件实例获取HFormApi
vue
<template>
  <HForm type="FORM" card :rules="HFormRules" @confirm="commit" :cols="2" ref="formRef"/>
</template>

<script lang="ts" setup>
  import { HFormRule, HForm, HFormApi} from 'hyb-naive'
  import { reactive,ref } from 'vue'

  //通过HForm实例获取
  const formRef= ref<InstanceType<typeof HForm>>()
  //然后通过
  formRef.value?.setFormData({
    age:18,
    sex:1
  })
</script>

注意

formRef 可以直接调用上述的Api函数和对象，HForm组件defineExpose对外暴漏了这些Api，方便开发者使用。而这个时候获取不到value和rule的值, 就是上述所说的只有在表单项钩子函数中才有值，因为这里获取的是整个表单组件的实例，而这两个值都是和表单项绑定在一起的。

  1. 通过表单项的钩子函数获取HFormApi。如 props中获取HFormApi, 在表单配置中，props可以是一个object也可以是一个Function,如果不需要通过FormApi对表单进行操作，就可以直接定义成一个对象，否则就只能通过函数来获取。
ts
{
    field: 'age',
    compType: 'InputNumber',
    label: '年龄',
    fullWidth: true,
    required: true,
    validateType: 'number',
    props(formApi: HFormApi) {
      return {
        onChange(value: number) {
          //设置班级数据
          if (value < 18) {
            formApi.setOptions('grade', [
              { label: '1年级', value: '1' },
            ])
          } else {
            formApi.setOptions('grade', [
              { label: '2年级', value: '4' },
            ])
          }
        },
      }
    },
  },

props都有哪些配置信息，如何配置？

这里解释一下，props是根据你配置组件的类型（compType），具体有哪些参数，参考naive-ui中对应的组件的props进行一一对应； 注意：这里是可以取到HFormApi中的value（当前表单项的值）和rule（当前表单项的规则）字段的值

HFormApi操作无效果？ ​

注意,注意,注意

要想使用HFormApi进行对表单操作，最重要的前提是，必须对表单数据设置为响应式数据，否则没有效果

ts
//错误示例
const formRules = [{
    field: 'age',
    compType: 'InputNumber',
    label: '年龄',
    fullWidth: true,
    required: true,
    validateType: 'number',
    props(formApi: HFormApi) {
      return {
        onChange(value: number) {
          //设置班级数据
          if (value < 18) {
            formApi.setOptions('grade', [
              { label: '1年级', value: '1' },
            ])
          } else {
            formApi.setOptions('grade', [
              { label: '2年级', value: '4' },
            ])
          }
        },
      }
    },
  }]

  // 正确的写法
  const formRules = reactive([{
      field: 'age',
      compType: 'InputNumber',
      label: '年龄',
      fullWidth: true,
      required: true,
      validateType: 'number',
      props(formApi: HFormApi) {
        return {
          onChange(value: number) {
            //设置班级数据
            if (value < 18) {
              formApi.setOptions('grade', [
                { label: '1年级', value: '1' },
              ])
            } else {
              formApi.setOptions('grade', [
                { label: '2年级', value: '4' },
              ])
            }
          },
        }
      },
    },
   // ...others
  ])

HForm ​

Props ​

字段说明类型默认值必填
cols表单列数numbertype为FILTER时默认为4,FORM默认为1否
labelWidth标签宽度number80否
labelPlacement标签位置，可选值为 left 或 top'left' | 'top'left否
size表单大小，可选值为 small、medium 或 large'small' | 'medium' | 'large'small否
labelAlign标签对齐方式，可选值为 left、right 或 center'left' | 'right' | 'center'right否
disabled是否禁用表单booleanfalse否
title表单标题string空否
rules表单规则数组HFormRule[]-是
formData表单数据Record<string, any>{}否
filterNullValue点击搜索时是否过滤空值提交，且仅在筛选模式（FILTER）时有效booleantrue否
type表单类型，可选值为 FORM 或 FILTER'FORM' | 'FILTER'FORM是
card是否启用卡片模式booleanfalse否
immediateUpdate是否立即回调 formData 数据变化booleanfalse否
borderRadius表单边框圆角number7否
searchFirstRow是否将搜索和重置按钮显示在第一行的末尾booleantrue否
searchBtn搜索按钮配置{ searchSpan?: number; search?: ButtonProps | boolean; reset?: ButtonProps | boolean }-否
showFormBtn是否显示表单的取消和确认按钮, FORM模式有效booleantrue否
formBtn表单的取消和确认按钮配置{ cancel?: ButtonProps; confirm?: ButtonProps }-否
initSearch初始化搜索时是否回调 search 事件booleantrue否

ButtonProps ​

字段说明类型默认值
text按钮文本string-
show是否显示按钮booleantrue
disabled是否禁用按钮booleanfalse
loading是否显示加载状态booleanfalse
interceptEvent是否拦截事件, 目前只有重置事件做了拦截, 其他按钮未做处理；后续优化处理booleanfalse

HFormRule 表单配置 ​

属性 ​
字段说明类型默认值必填
field表单字段名string-是
label标签名称string-是
labelAlign标签对齐方式'left' | 'center' | 'right'right否
required是否必填项boolean | ((fApi: HFormApi) => boolean)false否
compType组件类型HFormCompType | ((fApi: HFormApi) => HFormCompType)-是
trigger校验事件string | string[]FORM模式且required为true时默认[blur, change, input]否
message验证错误提示消息stringFORM模式且required为true时默认${label}不能为空否
span24栅格暂用的空间大小number | (() => number)FORM默认24，FILTER默认6否
defaultValue默认值any-否
labelWidth标签的宽度number | string默认取HForm的labelWidth否
validateType数据类型校验HValidateTypestring否
validator表单校验器，自定义校验规则FormRuleValidator-否
fullWidth是否填充整个宽度booleanfalse否
ignoreCommitFORM模式下是否忽略表单提交booleanfalse否
restValue是否重置数据,某些情况下有些数据不需要重置booleanfalse否
show是否显示boolean | ((fApi: HFormApi) => boolean)true否
props组件参数object | ((fApi: HFormApi) => object)-否
options当组件类型为 RadioGroup、RadioButtonGroup、Select 的选项内容Array<{ label?: string; value?: any; [key: string]: any }> | ((fApi: HFormApi) => Array<{ label?: string; value?: any; [key: string]: any }>)-否
onLoad组件加载钩子函数(fApi: HFormApi) => void-否
disabled是否禁用表单项boolean | ((fApi: HFormApi) => boolean)false否
HFormCompType组件类型 ​
组件名称说明
Input输入框
InputNumber数字输入框
Select下拉选择框
TreeSelect树形选择框
RadioButtonGroup单选按钮组
RadioGroup单选按钮组
Radio单选按钮
Checkbox复选框
CheckboxGroup复选框组
AutoComplete自动补全输入框
Cascader级联选择器
DatePicker日期选择器
Switch开关
Upload文件上传 目前还有问题暂不支持
Slider滑块
Rate评分组件
Tree树形组件
Transfer穿梭框
Slot插槽
TimePicker时间选择器

Events ​

事件名称说明参数
dataChange表单数据变化时触发formData: Record<string, any>
search搜索时触发formData: Record<string, any>
reset重置表单时触发formData: Record<string, any>
cancelFORM模式下使用，取消操作时触发无
confirmFORM模式下使用，确认操作时触发formData: Record<string, any>

Slot ​

名称说明
search搜索和重置按钮的插槽控制
动态插槽，根据表单配置的项进行动态化配置[field]当表单项的compType为Slot时，会触发该插槽, 以满足特殊场景的组件需求,定制化、特殊化

Released under the MIT License.

Copyright © 2023-present China Carlos