@pqcqcqc/qc-components v1.1.2

QC-Components

一款基于AntdV的 高效开发组件库

• 引入：@pqcqcqc/qc-components - npm
• 使用
  • 组件：DynamicForm
  • 函数式调用：useFullScreenDyForm(config: FormConfig)
  • 示例站点：Study Demos (prod) (zust.online)

更多文档待完善..........

组件结构

• 重要，这是下面配置的基础

• 

• 红色部分：

  • 表单Form组件

• 绿色部分：

  • 表单标题
  • 按钮或自定义按钮

• 黄色部分：

  • 表单项Form.Item组件

• 蓝色部分：

  • 真实输入框或者内容展示Component组件

Schema

一个表单的所有配置，称为Schema。

Schema的不同对应了不同的表单内容。

• 类型信息

  • title（可选）表单的标题，显示在表单组件的最上方。

  • items：（必须） 表单内的组件，比如输入框等，下面有详细说明。

  • onSubmit：（可选）表单提交事件。

    • 入参：表单的输入结果对象（响应式）

    • 返回值：void

  • onReset：（可选）表单点击重置事件。

    • 入参：无
    • 返回值：void

  • formProps：表单整体属性

    • 常用属性：

      • labelCol
      • wrapperCol

    • 其他属性：

      • Form #

        Property	Description	Type	Default Value	Version
        colon	change default props colon value of Form.Item (only effective when prop layout is horizontal)	boolean	true
        disabled	Set form component disable, only available for antdv components	boolean	false	4.0
        hideRequiredMark	Hide required mark of all form items	Boolean	false
        labelAlign	text align of label of all items	'left' | 'right'	'right'
        labelCol	The layout of label. You can set span offset to something like {span: 3, offset: 12} or sm: {span: 3, offset: 12} same as with <Col>	object
        labelWrap	whether label can be wrap	boolean	false	3.0
        layout	Define form layout	'horizontal'|'vertical'|'inline'	'horizontal'
        model	data of form component	object
        name	Form name. Will be the prefix of Field id	string	-	2.0.0
        noStyle	No style for true, used as a pure field control	boolean	false	3.0
        rules	validation rules of form	object
        scrollToFirstError	Auto scroll to first failed field when submit	boolean | options	false	2.0.0
        validateOnRuleChange	whether to trigger validation when the rules prop is changed	boolean	true
        validateTrigger	Config field validate trigger	string | string[]	change	2.0.0
        wrapperCol	The layout for input controls, same as labelCol	object

  • formEvent：表单事件

    • Methods #

      Method	Description	Parameters	Version
      clearValidate	clear validation message for certain fields. The parameter is name or an array of names of the form items whose validation messages will be removed. When omitted, all fields' validation messages will be cleared	(nameList?: NamePath[]) => void
      resetFields	reset all the fields and remove validation result	(nameList?: NamePath[]) => void
      scrollToField	Scroll to field position	(name: NamePath, options: [ScrollOptions]) => void
      validate	Validate fields, it is same as validateFields	(nameList?: NamePath[]) => Promise
      validateFields	Validate fields	(nameList?: NamePath[]) => Promise

  • className：Form组件的类名

  • customBtns：自定义按钮

    • 

    • 红色部分

      • 自定义按钮最外层div

    • 黄色部分：

      • 按钮外围div

    • 绿色部分：

      • 按钮主体

    • 自定义按钮的类型信息：

      • text：按钮文本（同时作为黄色部分div的key，尽量不要重复）

      • onClick：点击事件

        • 入参：
          • model：表单的数据
          • event？可选：点击事件
        • 返回值：
          • void

      • props：按钮参数

        • Different button styles can be generated by setting Button properties. The recommended order is: type -> shape -> size -> loading -> disabled.

          Property	Description	Type	Default	Version
          block	option to fit button width to its parent width	boolean	false
          danger	set the danger status of button	boolean	false	2.2.0
          disabled	disabled state of button	boolean	false
          ghost	make background transparent and invert text and border colors	boolean	false
          href	redirect url of link button	string	-
          htmlType	set the original html type of button, see: MDN	string	button
          icon	set the icon of button, see: Icon component	v-slot	-
          loading	set the loading status of button	boolean | { delay: number }	false
          shape	Can be set button shape	default	circle	round	default
          size	set the size of button	large	middle	small	middle
          target	same as target attribute of a, works when href is specified	string	-
          type	can be set button type	primary	ghost	dashed	link	text	default	default

      • outterStyle：黄色部分Style参数

      • style：按钮本体上Style参数

  • customBtnsStyle：自定义按钮最外层div样式（红色部分）

• 表单项参数

• 

  • label：表单项显示名称

  • field：表单项字段，在表单数据对象中的字段名

  • component：表单项内组件，支持已经有的内置组件或者自定义组件

  • componentProps：表单项内（蓝色部分）组件的参数，根据不同的component，可以传入不同的参数

  • componentEvent：表单项内（蓝色部分）组件的事件参数，如click：() =>{}

  • formItemProps：表单项（黄色部分）参数

    • Form.Item #

      Property	Description	Type	Default Value	Version
      autoLink	Whether to automatically associate form fields. In most cases, you can use automatic association. If the conditions for automatic association are not met, you can manually associate them. See the notes below.	boolean	true
      colon	Used with label, whether to display : after label text.	boolean	true
      extra	The extra prompt message. It is similar to help. Usage example: to display error message and prompt message at the same time.	string|slot
      hasFeedback	Used with validateStatus, this option specifies the validation status icon. Recommended to be used only with Input.	boolean	false
      help	The prompt message. If not provided, the prompt message will be generated by the validation rule.	string|slot
      htmlFor	Set sub label htmlFor.	string
      label	Label text	string|slot
      labelAlign	text align of label	'left' | 'right'	'right'
      labelCol	The layout of label. You can set span offset to something like {span: 3, offset: 12} or sm: {span: 3, offset: 12} same as with <Col>	object
      name	a key of model. In the use of validate and resetFields method, the attribute is required	NamePath		2.0.0
      required	Whether provided or not, it will be generated by the validation rule.	boolean	false
      rules	validation rules of form	object | array
      tooltip	Config tooltip info	string | slot		4.0.4
      validateFirst	Whether stop validate on first rule of error for this field.	boolean	false
      validateStatus	The validation status. If not provided, it will be generated by validation rule. options: 'success' 'warning' 'error' 'validating'	string
      validateTrigger	When to validate the value of children node	string | string[]	change
      wrapperCol	The layout for input controls, same as labelCol	object

  • value：表单初始化参数，重置时默认将表单组件设置为这个值

  • next：下一级表单

    • 入参：
      • model ：当前表单项的输入内容
    • 返回值：DyForm动态表单 | undefined | null

  • nextFormStyle：下一级表单的外围div样式

  • onShow：是否显示这个表单项

    • 入参：
      • modelValue：当前表单的完整输入参数
    • 返回值：
      • boolean：为true时显示该表单项，false时不显示该项

当前支持的组件

export type InnerComponent =
	| "Text"
	| "Password"
	| "Textarea"
	| "Number"
	| "Select"
	| "Radio"
	| "Checkbox"
	| "DatePicker"
	| "Rate"
	| "Slider"
	| "Switch"
	| "Upload"
	| "TreeSelect"
	| "TimePicker"
	| "AutoComplete"
	| "Tag"
	| "Mentions"
	| "Divider"
	| "AvatarGroup"
	| "Corn";

Text组件

<<<<<<< HEAD

=======

示例

•   		// input
        		{
        			label: "姓名",
        			field: "name",
        			component: "Text",
        			componentProps: {
        				allowClear: true,
        				showCount: true,
        				maxlength: 20,
        				style: {
        					width: "400px",
        				},
        			},
        			formItemProps: {
        				rules: [
        					{
        						required: true,
        						message: "请输入姓名",
        						trigger: "blur",
        					},
        				],
        				colon: false,
        				tooltip: "在这里输入姓名",
        			},
        			value: "百里守约",
                // 动态下一级表单
        			next: (model: any): DyForm | undefined => {
        				if (model == "百里守约") {
        					return {
        						items: [
        							{
        								label: "武器",
        								field: "weapon",
        								component: "Text",
        								componentProps: {
        									allowClear: true,
        									showCount: true,
        									maxlength: 80,
        									style: {
        										width: "350px",
        									},
        								},
        								formItemProps: {
        									rules: [
        										{
        											required: true,
        											message: "武器只能是ABCDE中的一个",
        											trigger: "blur",
        											type: "enum",
        											enum: ["A", "B", "C", "D", "E"],
        										},
        									],
        									style: {
        										marginTop: "10px",
        									},
        									labelCol: { span: 3 },
        								},
        							},
        						],
        					};
        				}
        			},
        		},

204bb0431fa9333f31e8136e4e5f80ade0f3f556

​ Input #

Input Events #

When Input is used in a Form.Item context, if the Form.Item has the id and options props defined then value, defaultValue, and id props of Input are automatically set.

Password组件

• 与Text组件相同，但指定了type一定为password

• 示例

  •   let qspassword = ""
      
      const commonComponentProps = {
        allowClear: true,
        showCount: true,
        maxlength: 30
      }
      
      const passwordAndConfirmPassword: DyFormItem[] = [
        {
          label: "密码",
          field: "password",
          component: "Password",
          formItemProps: {
            rules: [
              { required: true, message: "请输入密码" },
              {
                min: 5,
                max: 30,
                message: "密码长度为5-30位"
              },
              {
                validator: (_rule: any, value: any) => {
                  qspassword = value
                  return Promise.resolve()
                }
              }
            ]
          },
          componentProps: commonComponentProps
        },
        {
          label: "确认密码",
          field: "confirmPassword",
          component: "Password",
          formItemProps: {
            rules: [
              { required: true, message: "请输入确认密码" },
              {
                min: 5,
                max: 30,
                message: "密码长度为5-30位"
              },
              {
                validator: (_rule: any, value: any) => {
                  if (value !== qspassword) {
                    return Promise.reject("两次输入密码不一致")
                  }
                  return Promise.resolve()
                }
              }
            ]
          },
          componentProps: commonComponentProps
        }
      ]

Textarea组件

示例

•   {
    			label: "简介",
    			field: "desc",
    			component: "Textarea",
    			componentProps: {
    				allowClear: true,
    				autoSize: {
    					minRows: 4,
    					maxRows: 4,
    				},
    				maxlength: 200,
    				showCount: true,
    			},
    			formItemProps: {
    				rules: [
    					{
    						required: true,
    						message: "请输入简介",
    						trigger: "blur",
    					},
    				],
    			},
    		},

TextArea #

TextArea Events #

Number组件

示例

•   // number 
    		{
    			label: "年龄",
    			field: "age",
    			component: "Number",
    			componentProps: {
    				allowClear: true,
    				style: {
    					width: "400px",
    				},
    			},
    			formItemProps: {
    				rules: [
    					{
    						required: true,
    						message: "请输入年龄",
    						trigger: "blur",
    					},
    				],
    			},
    		},

API#

#

events #

Select

• 注意，下面的文档来自Antd，在本项目中，options可以传入一个异步函数，返回值为选项列表，在组件加载时将会自动调用该函数获取参数

• 示例

  •   		// select
          		{
          			label: "固定国家选择",
          			field: "country",
          			component: "Select",
          			componentProps: {
          				allowClear: true,
          				options: [
          					{ value: "中国", label: "中国" },
          					{ value: "美国", label: "美国" },
          					{ value: "日本", label: "日本" },
          					{ value: "韩国", label: "韩国" },
          				],
          			},
          		},
          		// async select 
          		{
          			label: "异步国家选择",
          			field: "async-country",
          			component: "Select",
          			componentProps: {
          				allowClear: true,
          				options: () => {
          					return new Promise<Options>((resolve) => {
          						setTimeout(() => {
          							resolve([
          								{ value: "中国", label: "中国" },
          								{ value: "美国", label: "美国" },
          								{ value: "日本", label: "日本" },
          								{ value: "韩国", label: "韩国" },
          							]);
          						}, 1000);
          					});
          				},
          			},
          		},

Select props #

Note, if you find that the drop-down menu scrolls with the page, or you need to trigger Select in other popup layers, please try to use getPopupContainer={triggerNode => triggerNode.parentElement} to fix the drop-down popup rendering node in the parent element of the trigger .

events #

Radio

• 当使用异步加载，出现错误时可以点击重试。

• 与Select相似，参考antd文档，同样支持options传入异步函数获取列表

• 示例

  •   		// radio
          		{
          			label: "性别",
          			field: "sex",
          			component: "Radio",
          			componentProps: {
          				options: [
          					{ value: 1, label: "男" },
          					{ value: 2, label: "女" },
          					{ value: 3, label: "保密" },
          				],
          			},
          			formItemProps: {
          				rules: [
          					{
          						required: true,
          						message: "请选择性别",
          						trigger: "blur",
          					},
          				],
          				hidden: false,
          			},
          			value: 1,
          		},
          		// async radio
          		{
          			label: "异步选择",
          			field: "async-test",
          			component: "Radio",
          			componentProps: {
          				options: async () => await getOptionApi(),
          			},
          			formItemProps: {
          				rules: [
          					{
          						required: true,
          						message: "请选择性别",
          						trigger: "blur",
          					},
          				],
          			},
          			value: 1,
          		},

CheckBox

• 同上，类似Radio

示例

•   		// checkbox
        		{
        			label: "兴趣",
        			field: "hobby",
        			component: "Checkbox",
        			componentProps: {
        				options: [
        					{ value: 1, label: "足球" },
        					{ value: 2, label: "篮球" },
        					{ value: 3, label: "排球" },
        				],
        			},
        		},
        		// async checkbox
        		{
        			label: "异步多选",
        			field: "async-checkbox",
        			component: "Checkbox",
        			componentProps: {
        				options: async () => await getOptionApi(),
        			},
        		},

DatePicker

示例

•   		// datepicker
        		{
        			label: "生日",
        			field: "birthday",
        			component: "DatePicker",
        			formItemProps: {
        				rules: [
        					{
        						required: true,
        						message: "生日日期不能为空",
        						trigger: "blur",
        					},
        				],
        			},
        			componentProps: {
        				format: "YYYY-MM-DD",
        				valueFormat: "YYYY-MM-DD",
        			},
        		},

•    let timeSelectStart: Dayjs = dayjs()
     ......
     	// 开始时间（在当前时间之后）
         {
           label: "开始时间",
           field: "startTime",
           component: "DatePicker",
           //格式：2024-05-14 08:30:22
           formItemProps: {
             rules: [
               { required: true, message: "请选择开始时间" },
               // 建立一个规则用来缓存已经选择的时间
               {
                 validator: (_rule: any, value: any) => {
                   timeSelectStart = value
                   return Promise.resolve()
                 }
               }
             ]
           },
           componentProps: {
             disabledDate: (current: Dayjs) => {
               return current && current < dayjs()
             },
             disabledTime: (current: Dayjs) => {
               if (current.isSame(dayjs(), "day")) {
                 return {
                   disabledHours: () => {
                     return [...Array(24).keys()].filter((hour) => hour < dayjs().hour())
                   }
                 }
               }
               return {}
             },
             ...componentStyle,
             format: "YYYY-MM-DD HH:mm:ss",
             valueFormat: "YYYY-MM-DD HH:mm:ss",
             showTime: true,
             placeholder: "请选择开始时间"
           }
         },
         // 结束时间，在开始时间之后
         {
           label: "结束时间",
           field: "endTime",
           component: "DatePicker",
           formItemProps: {
             rules: [
               { required: true, message: "请选择结束时间" },
               {
                 validator: (_rule: any, value: any) => {
                   if (value < timeSelectStart) {
                     return Promise.reject("结束时间不能早于开始时间")
                   }
                   return Promise.resolve()
                 }
               }
             ]
           },
           componentProps: {
             disabledDate: (current: Dayjs) => {
               return current && current < timeSelectStart
             },
             disabledTime: (current: Dayjs) => {
               if (current.isSame(timeSelectStart, "day")) {
                 return {
                   disabledHours: () => {
                     return [...Array(24).keys()].filter((hour) => hour < timeSelectStart.hour())
                   }
                 }
               }
               return {}
             },
             ...componentStyle,
             format: "YYYY-MM-DD HH:mm:ss",
             valueFormat: "YYYY-MM-DD HH:mm:ss",
             showTime: true,
             placeholder: "请选择结束时间"
           }
         },

Common API #

The following APIs are shared by DatePicker, RangePicker.

Common Events #

Common Methods #

DatePicker #

DatePicker Events #

DatePickerpicker=year(https://www.antdv.com/components/date-picker#datepicker-picker-year)

DatePickerpicker=quarter(https://www.antdv.com/components/date-picker#datepicker-picker-quarter)

DatePickerpicker=month(https://www.antdv.com/components/date-picker#datepicker-picker-month)

DatePickerpicker=week(https://www.antdv.com/components/date-picker#datepicker-picker-week)

RangePicker #