Form 表單組件 · JeecgBoot Vue3前端文檔

# Form 表單組件對`antv`的 form 組件進行封裝，擴展一些常用的功能 > 如果文檔內沒有，可以嘗試在在線示例內尋找 [TOC] ## Usage ### useForm 方式下面是一個使用簡單表單的示例，只有一個輸入框 ~~~ <template> <div class="m-4"> <BasicForm :labelWidth="100" :schemas="schemas" :actionColOptions="{ span: 24 }" @submit="handleSubmit" /> </div> </template> <script lang="ts"> import { defineComponent } from 'vue'; import { BasicForm, FormSchema } from '/@/components/Form'; import { CollapseContainer } from '/@/components/Container'; import { useMessage } from '/@/hooks/web/useMessage'; const schemas: FormSchema[] = [ { field: 'field', component: 'Input', label: '字段1', colProps: { span: 8, }, defaultValue: '1', componentProps: { placeholder: '自定義placeholder', onChange: (e) => { console.log(e); }, }, }, ]; export default defineComponent({ components: { BasicForm, CollapseContainer }, setup() { const { createMessage } = useMessage(); return { schemas, handleSubmit: (values: any) => { createMessage.success('click search,values:' + JSON.stringify(values)); }, }; }, }); </script> ~~~ ### template 方式所有可調用函數見下方`Methods`說明 ~~~ <template> <div class="m-4"> <BasicForm :schemas="schemas" ref="formElRef" :labelWidth="100" @submit="handleSubmit" :actionColOptions="{ span: 24 }" /> <div> </template> <script lang="ts"> import { defineComponent, ref } from 'vue'; import { BasicForm, FormSchema, FormActionType, FormProps } from '/@/components/Form'; import { CollapseContainer } from '/@/components/Container'; const schemas: FormSchema[] = [ ]; export default defineComponent({ components: { BasicForm, CollapseContainer }, setup() { const formElRef = ref<Nullable<FormActionType>>(null); return { formElRef, schemas, setProps(props: FormProps) { const formEl = formElRef.value; if (!formEl) return; formEl.setProps(props); }, }; }, }); </script> ~~~ ## useForm form 組件還提供了`useForm`，方便調用函數內部方法 ### 示例 ~~~ <template> <BasicForm @register="register" @submit="handleSubmit" /> </template> <script lang="ts"> import { defineComponent } from 'vue'; import { BasicForm, FormSchema, useForm } from '/@/components/Form/index'; import { CollapseContainer } from '/@/components/Container/index'; import { useMessage } from '/@/hooks/web/useMessage'; const schemas: FormSchema[] = [ { field: 'field1', component: 'Input', label: '字段1', colProps: { span: 8, }, componentProps: { placeholder: '自定義placeholder', onChange: (e: any) => { console.log(e); }, }, }, ]; export default defineComponent({ components: { BasicForm, CollapseContainer }, setup() { const { createMessage } = useMessage(); const [register, { setProps }] = useForm({ labelWidth: 120, schemas, actionColOptions: { span: 24, }, }); return { register, schemas, handleSubmit: (values: any) => { createMessage.success('click search,values:' + JSON.stringify(values)); }, setProps, }; }, }); </script> ~~~ ### 參數介紹 ~~~ const [register, methods] = useForm(props); ~~~ **參數 props 內的值可以是 computed 或者 ref 類型** **register** register 用于注冊`useForm`，如果需要使用`useForm`提供的 api，必須將 register 傳入組件的`onRegister` ~~~ <template> <BasicForm @register="register" @submit="handleSubmit" /> </template> <script> export default defineComponent({ components: { BasicForm }, setup() { const [register] = useForm(); return { register, }; }, }); </script> ~~~ `Methods`見下方說明 ### Methods **getFieldsValue** 類型:`() => Recordable;` 說明: 獲取表單值 **setFieldsValue** 類型:`<T>(values: T) => Promise<void>` 說明: 設置表單字段值 **resetFields** 類型:`()=> Promise<any>` 說明: 重置表單值 **validateFields** 類型:`(nameList?: NamePath[]) => Promise<any>` 說明: 校驗指定表單項 **validate** 類型:`(nameList?: NamePath[]) => Promise<any>` 說明: 校驗整個表單 **submit** 類型:`() => Promise<void>` 說明: 提交表單 **scrollToField** 類型:`(name: NamePath, options?: ScrollOptions) => Promise<void>` 說明: 滾動到對應字段位置 **clearValidate** 類型:`(name?: string | string[]) => Promise<void>` 說明: 清空校驗 **setProps** TIP 設置表單的 props 可以直接在標簽上傳遞，也可以使用 setProps，或者初始化直接寫 useForm(props) 類型:`(formProps: Partial<FormProps>) => Promise<void>` 說明: 設置表單 Props **removeSchemaByFiled** 類型:`(field: string | string[]) => Promise<void>` 說明: 根據 field 刪除 Schema **appendSchemaByField** 類型:`( schema: FormSchema, prefixField: string | undefined, first?: boolean | undefined ) => Promise<void>` 說明: 插入到指定 filed 后面，如果沒傳指定 field，則插入到最后,當 first = true 時插入到第一個位置 **updateSchema** 類型:`(data: Partial<FormSchema> | Partial<FormSchema>[]) => Promise<void>` 說明: 更新表單的 schema, 只更新函數所傳的參數 e.g ~~~ updateSchema({ field: 'filed', componentProps: { disabled: true } }); updateSchema([ { field: 'filed', componentProps: { disabled: true } }, { field: 'filed1', componentProps: { disabled: false } }, ]); ~~~ ## Props 溫馨提醒除以下參數外，官方文檔內的 props 也都支持，具體可以參考 [antv form](https://www.antdv.com/components/form-cn) | 屬性 | 類型 | 默認值 | 可選值 | 說明 | 版本 | | --- | --- | --- | --- | --- | --- | | schemas | `Schema[]` | \- | \- | 表單配置，見下方`FormSchema`配置 | | | submitOnReset | `boolean` | `false` | \- | 重置時是否提交表單 | | | labelCol | Partial<ColEx> | \- | \- | 整個表單通用 LabelCol 配置 | | | wrapperCol | Partial<ColEx> | \- | \- | 整個表單通用 wrapperCol 配置 | | | baseColProps | Partial<ColEx> | \- | \- | 配置所有選子項的 ColProps，不需要逐個配置，子項也可單獨配置優先與全局 | | | baseRowStyle | `object` | \- | \- | 配置所有 Row 的 style 樣式 | | | labelWidth | number , string | \- | \- | 擴展 form 組件，增加 label 寬度，表單內所有組件適用，可以單獨在某個項覆蓋或者禁用 | | | labelAlign | `string` | \- | `left`,`right` | label 布局 | | | mergeDynamicData | `object` | \- | \- | 額外傳遞到子組件的參數 values | | | autoFocusFirstItem | `boolean` | `false` | \- | 是否聚焦第一個輸入框，只在第一個表單項為 input 的時候作用 | | | compact | `boolean` | `false` | `true/false` | 緊湊類型表單，減少 margin-bottom | | | size | `string` | `default` | `'default' , 'small' , 'large'` | 向表單內所有組件傳遞 size 參數,自定義組件需自行實現 size 接收 | | | disabled | `boolean` | `false` | `true/false` | 向表單內所有組件傳遞 disabled 屬性，自定義組件需自行實現 disabled 接收 | | | autoSetPlaceHolder | `boolean` | `true` | `true/false` | 自動設置表單內組件的 placeholder，自定義組件需自行實現 | | | autoSubmitOnEnter | `boolean` | `false` | `true/false` | 在input中輸入時按回車自動提交 | 2.4.0 | | rulesMessageJoinLabel | `boolean` | `false` | `true/false` | 如果表單項有校驗，會自動生成校驗信息，該參數控制是否將字段中文名字拼接到自動生成的信息后方 | | | showAdvancedButton | `boolean` | `false` | `true/false` | 是否顯示收起展開按鈕 | | | emptySpan | number , Partial<ColEx> | 0 | \- | 空白行格,可以是數值或者 col 對象數 | | | autoAdvancedLine | `number` | 3 | \- | 如果 showAdvancedButton 為 true，超過指定行數行默認折疊 | | | alwaysShowLines | `number` | 1 | \- | 折疊時始終保持顯示的行數 | 2.7.1 | | showActionButtonGroup | `boolean` | `true` | `true/false` | 是否顯示操作按鈕(重置/提交) | | | actionColOptions | `Partial<ColEx>` | \- | \- | 操作按鈕外層 Col 組件配置，如果開啟 showAdvancedButton，則不用設置，具體見下方 actionColOptions | | | showResetButton | `boolean` | `true` | \- | 是否顯示重置按鈕 | | | resetButtonOptions | `object` | | \- | 重置按鈕配置見下方 ActionButtonOption | | | showSubmitButton | `boolean` | `true` | \- | 是否顯示提交按鈕 | | | submitButtonOptions | `object` | | \- | 確認按鈕配置見下方 ActionButtonOption | | | resetFunc | () => Promise<void> | | \- | 自定義重置按鈕邏輯`() => Promise<void>;` | | | submitFunc | () => Promise<void> | | \- | 自定義提交按鈕邏輯`() => Promise<void>;` | | | fieldMapToTime | [string, [string, string], string?][] | | \- | 用于將表單內時間區域的應設成 2 個字段,見下方說明 | | ### ColEx 見 [src/components/Form/src/types/index.ts](https://github.com/jeecgboot/jeecgboot-vue3/tree/master/src/components/Form/src/types/index.ts) ### ActionButtonOption [BasicButtonProps](https://github.com/jeecgboot/jeecgboot-vue3/tree/master/src/components/Button/types.ts) ~~~ export interface ButtonProps extends BasicButtonProps { text?: string; } ~~~ ### fieldMapToTime 將表單內時間區域的值映射成 2 個字段如果表單內有時間區間組件，獲取到的值是一個數組，但是往往我們傳遞到后臺需要是 2 個字段 ~~~ useForm({ fieldMapToTime: [ // data為時間組件在表單內的字段，startTime，endTime為轉化后的開始時間于結束時間 // 'YYYY-MM-DD'為時間格式，參考moment ['datetime', ['startTime', 'endTime'], 'YYYY-MM-DD'], // 支持多個字段 ['datetime1', ['startTime1', 'endTime1'], 'YYYY-MM-DD HH:mm:ss'], ], }); // fieldMapToTime沒寫的時候表單獲取到的值 { datetime: [Date(),Date()] } // ['datetime', ['startTime', 'endTime'], 'YYYY-MM-DD'],之后 { datetime: [Date(),Date()], startTime: '2020-08-12', endTime: '2020-08-15', } ~~~ ### FormSchema | 屬性 | 類型 | 默認值 | 可選值 | 說明 | | --- | --- | --- | --- | --- | | field | `string` | \- | \- | 字段名 | | label | `string` | \- | \- | 標簽名 | | subLabel | `string` | \- | \- | 二級標簽名灰色 | | suffix | string , number , ((values: RenderCallbackParams) => string / number); | \- | \- | 組件后面的內容 | | changeEvent | `string` | \- | \- | 表單更新事件名稱 | | helpMessage | `string , string[]` | \- | \- | 標簽名右側溫馨提示 | | helpComponentProps | `HelpComponentProps` | \- | \- | 標簽名右側溫馨提示組件 props,見下方 HelpComponentProps | | labelWidth | `string , number` | \- | \- | 覆蓋統一設置的 labelWidth | | disabledLabelWidth | `boolean` | false | true/false | 禁用 form 全局設置的 labelWidth,自己手動設置 labelCol 和 wrapperCol | | component | `string` | \- | \- | 組件類型，見下方 ComponentType | | componentProps | `any,()=>{}` | \- | \- | 所渲染的組件的 props | | rules | `ValidationRule[]` | \- | \- | 校驗規則,見下方 ValidationRule | | required | `boolean` | \- | \- | 簡化 rules 配置，為 true 則轉化成 \[{required:true}\]。`2.4.0`之前的版本只支持string類型的值 | | rulesMessageJoinLabel | `boolean` | false | \- | 校驗信息是否加入 label | | itemProps | `any` | \- | \- | 參考下方 FormItem | | colProps | `ColEx` | \- | \- | 參考上方 actionColOptions | | defaultValue | `object` | \- | \- | 所渲渲染組件的初始值 | | render | (renderCallbackParams: RenderCallbackParams) => VNode / VNode[] / string | \- | \- | 自定義渲染組件 | | renderColContent | (renderCallbackParams: RenderCallbackParams) => VNode / VNode[] / string | \- | \- | 自定義渲染組件（需要自行包含 formItem） | | renderComponentContent | (renderCallbackParams: RenderCallbackParams) => any / string | \- | \- | 自定義渲染組內部的 slot | | slot | `string` | \- | \- | 自定義 slot，渲染組件 | | colSlot | `string` | \- | \- | 自定義 slot，渲染組件（需要自行包含 formItem） | | show | boolean / ((renderCallbackParams: RenderCallbackParams) => boolean) | \- | \- | 動態判斷當前組件是否顯示，css 控制，不會刪除 dom | | ifShow | boolean / ((renderCallbackParams: RenderCallbackParams) => boolean) | \- | \- | 動態判斷當前組件是否顯示，js 控制，會刪除 dom | | dynamicDisabled | boolean / ((renderCallbackParams: RenderCallbackParams) => boolean) | \- | \- | 動態判斷當前組件是否禁用 | | dynamicRules | boolean / ((renderCallbackParams: RenderCallbackParams) => boolean) | \- | \- | 動態判返當前組件你校驗規則 | **RenderCallbackParams** ~~~ export interface RenderCallbackParams { schema: FormSchema; values: any; model: any; field: string; } ~~~ **componentProps** * 當值為對象類型時,該對象將作為`component`所對應組件的的 props 傳入組件 * 當值為一個函數時候參數有 4 個 `schema`: 表單的整個 schemas `formActionType`: 操作表單的函數。與 useForm 返回的操作函數一致 `formModel`: 表單的雙向綁定對象，這個值是響應式的。所以可以方便處理很多操作 `tableAction`: 操作表格的函數，與 useTable 返回的操作函數一致。注意該參數只在表格內開啟搜索表單的時候有值，其余情況為`null`, ~~~ { // 簡單例子，值改變的時候操作表格或者修改表單內其他元素的值 component:'Input', componentProps: ({ schema, tableAction, formActionType, formModel }) => { return { // xxxx props onChange:e=>{ const {reload}=tableAction reload() // or formModel.xxx='123' } }; }; } ~~~ **HelpComponentProps** ~~~ export interface HelpComponentProps { maxWidth: string; // 是否顯示序號 showIndex: boolean; // 文本列表 text: any; // 顏色 color: string; // 字體大小 fontSize: string; icon: string; absolute: boolean; // 定位 position: any; } ~~~ **ComponentType** schema 內組件的可選類型 ~~~ export type ComponentType = | 'Input' | 'InputGroup' | 'InputPassword' | 'InputSearch' | 'InputTextArea' | 'InputNumber' | 'InputCountDown' | 'Select' | 'ApiSelect' | 'TreeSelect' | 'RadioButtonGroup' | 'RadioGroup' | 'Checkbox' | 'CheckboxGroup' | 'AutoComplete' | 'Cascader' | 'DatePicker' | 'MonthPicker' | 'RangePicker' | 'WeekPicker' | 'TimePicker' | 'Switch' | 'StrengthMeter' | 'Upload' | 'IconPicker' | 'Render' | 'Slider' | 'Rate' | 'Divider'; // v2.7.2新增 ~~~ ### Divider schema說明 `Divider`類型用于在`schemas`中占位，將會渲染成一個分割線（始終占一整行的版面），可以用于較長表單的版面分隔。請只將Divider類型的schema當作一個分割線，而不是一個常規的表單字段。 * **`Divider`僅在`showAdvancedButton`為false時才會顯示**（也就是說如果啟用了表單收起和展開功能，`Divider`將不會顯示） * `Divider`使用`schema`中的`label`以及`helpMessage`來渲染分割線中的提示內容 * `Divider`可以使用`componentProps`來設置除`type`之外的props * `Divider`不會渲染`AFormItem`，因此`schema`中除`label`、`componentProps`、`helpMessage`、`helpComponentProps`以外的屬性不會被用到 ## 自行添加需要的組件類型在`src/components/Form/src/componentMap.ts`內，添加需要的組件，并在上方**ComponentType**添加相應的類型 key ### 方式 1 這種寫法適用與適用頻率較高的組件 ~~~ componentMap.set('componentName', 組件); // ComponentType export type ComponentType = xxxx | 'componentName'; ~~~ ### 方式 2 使用**useComponentRegister**進行注冊這種寫法只能在當前頁使用，頁面銷毀之后會從 componentMap 刪除相應的組件 ~~~ import { useComponentRegister } from '@/components/form/index'; import { StrengthMeter } from '@/components/strength-meter/index'; useComponentRegister('StrengthMeter', StrengthMeter); ~~~ 提示方式 2 出現的原因是為了減少打包體積，如果某個組件體積很大，用方式 1 的話可能會使首屏體積增加 ### render 自定義渲染內容 ~~~ <template> <div class="m-4"> <BasicForm @register="register" @submit="handleSubmit" /> </div> </template> <script lang="ts"> import { defineComponent, h } from 'vue'; import { BasicForm, FormSchema, useForm } from '/@/components/Form/index'; import { useMessage } from '/@/hooks/web/useMessage'; import { Input } from 'ant-design-vue'; const schemas: FormSchema[] = [ { field: 'field1', component: 'Input', label: '字段1', colProps: { span: 8, }, rules: [{ required: true }], render: ({ model, field }) => { return h(Input, { placeholder: '請輸入', value: model[field], onChange: (e: ChangeEvent) => { model[field] = e.target.value; }, }); }, }, { field: 'field2', component: 'Input', label: '字段2', colProps: { span: 8, }, rules: [{ required: true }], renderComponentContent: () => { return { suffix: () => 'suffix', }; }, }, ]; export default defineComponent({ components: { BasicForm }, setup() { const { createMessage } = useMessage(); const [register, { setProps }] = useForm({ labelWidth: 120, schemas, actionColOptions: { span: 24, }, }); return { register, schemas, handleSubmit: (values: any) => { createMessage.success('click search,values:' + JSON.stringify(values)); }, setProps, }; }, }); </script> ~~~ ### slot 自定義渲染內容提示使用插槽自定義表單域時，請注意antdv有關FormItem的 [相關說明](https://www.antdv.com/components/form-cn/#API)。 ~~~ <template> <div class="m-4"> <BasicForm @register="register"> <template #customSlot="{ model, field }"> <a-input v-model:value="model[field]" /> </template> </BasicForm> </div> </template> <script lang="ts"> import { defineComponent } from 'compatible-vue'; import { BasicForm, useForm } from '@/components/Form/index'; import { BasicModal } from '@/components/modal/index'; export default defineComponent({ name: 'FormDemo', setup(props) { const [register] = useForm({ labelWidth: 100, actionColOptions: { span: 24, }, schemas: [ { field: 'field1', label: '字段1', slot: 'customSlot', }, ], }); return { register, }; }, }); </script> ~~~ ### ifShow/show/dynamicDisabled 自定義顯示/禁用 ~~~ <template> <div class="m-4"> <BasicForm @register="register" /> </div> </template> <script lang="ts"> import { defineComponent } from 'vue'; import { BasicForm, FormSchema, useForm } from '/@/components/Form/index'; const schemas: FormSchema[] = [ { field: 'field1', component: 'Input', label: '字段1', colProps: { span: 8, }, show: ({ values }) => { return !!values.field5; }, }, { field: 'field2', component: 'Input', label: '字段2', colProps: { span: 8, }, ifShow: ({ values }) => { return !!values.field6; }, }, { field: 'field3', component: 'DatePicker', label: '字段3', colProps: { span: 8, }, dynamicDisabled: ({ values }) => { return !!values.field7; }, }, ]; export default defineComponent({ components: { BasicForm }, setup() { const [register, { setProps }] = useForm({ labelWidth: 120, schemas, actionColOptions: { span: 24, }, }); return { register, schemas, setProps, }; }, }); </script> ~~~ * * * 見 [antv form](https://www.antdv.com/components/form-cn) ## Slots | 名稱 | 說明 | | --- | --- | | formFooter | 表單底部區域 | | formHeader | 表單頂部區域 | | resetBefore | 重置按鈕前 | | submitBefore | 提交按鈕前 | | advanceBefore | 展開按鈕前 | | advanceAfter | 展開按鈕后 | ## ApiSelect 遠程下拉加載組件，該組件可以用于學習參考如何自定義組件集成到 Form 組件內，將自定義組件交由 Form 去管理 ### Usage ~~~ const schemas: FormSchema[] = [ { field: 'field', component: 'ApiSelect', label: '字段', }, ]; ~~~ ### Props | 屬性 | 類型 | 默認值 | 說明 | | --- | --- | --- | --- | | numberToString | `boolean` | `false` | 是否將`number`值轉化為`string` | | api | ()=>Promise<{ label: string; value: string; disabled?: boolean }[]> | \- | 數據接口，接受一個 Promise 對象 | | params | `object` | \- | 接口參數。此屬性改變時會自動重新加載接口數據 | | resultField | `string` | \- | 接口返回的字段，如果接口返回數組，可以不填。支持`x.x.x`格式 | | labelField | `string` | `label` | 下拉數組項內`label`顯示文本的字段，支持`x.x.x`格式 | | valueField | `string` | `value` | 下拉數組項內`value`實際值的字段，支持`x.x.x`格式 | | immediate | `boolean` | `true` | 是否立即請求接口，否則將在第一次點擊時候觸發請求 | ## ApiTreeSelect 遠程下拉樹加載組件，和`ApiSelect`類似，2.6.1以上版本 ### Props | 屬性 | 類型 | 默認值 | 說明 | | --- | --- | --- | --- | | api | ()=>Promise<{ label: string; value: string; children?: any[] }[]> | - | 數據接口，接受一個 Promise 對象 | | params | `object` | \- | 接口參數。此屬性改變時會自動重新加載接口數據 | | resultField | `string` | \- | 接口返回的字段，如果接口返回數組，可以不填。支持`x.x.x`格式 | | immediate | `boolean` | `true` | 是否立即請求接口。 | ## RadioButtonGroup Radio Button 風格的選擇按鈕 ### Usage ~~~ const schemas: FormSchema[] = [ { field: 'field', component: 'RadioButtonGroup', label: '字段', }, ]; ~~~ ### Props | 屬性 | 類型 | 默認值 | 說明 | | --- | --- | --- | --- | | options | { label: string; value: string; disabled?: boolean }[] | - | 數據字段 | ### dynamicRules 必填校驗示例 ~~~ dynamicRules: ({ model, schema }) => { return [{ required: true, message: '請輸入角色!' }]; }, ~~~