Skip to content

全局方法使用指南

FormCreate 提供了一系列全局方法,本指南将详细介绍这些全局方法的使用方法、配置说明,并通过示例帮助新用户快速上手。

如何调用全局方法

在开始使用这些方法之前,你需要先确保已经导入了 formCreate。以下是如何在项目中导入并使用 FormCreate 的全局方法的示例。

导入 FormCreate

首先,确保你已经安装了 FormCreate,并在项目中引入它:

js
import { createApp } from 'vue';
import App from './App.vue';
import formCreate from '@form-create/element-ui'; // 根据你的UI框架选择对应的包


const app = createApp(App);


app.use(formCreate);
app.mount('#app');

调用全局方法

在你的组件或应用中,你可以通过 formCreate 对象来访问和调用全局方法。以下是一些常见方法的调用示例:

js
const api = formCreate.getApi('formName');

表单操作相关方法

create

用于生成一个表单实例,返回表单的 API 对象,可以用于进一步操作表单。

  • 类型
ts
type Create = (rules:Rule[], options:object) => Api;
  • 示例
js
const rules = [
    { type: 'input', field: 'name', title: 'Name', value: '' },
    { type: 'input', field: 'email', title: 'Email', value: '' }
];


const options = {
    onSubmit: (formData) => {
        console.log('Form Submitted', formData);
    }
};


const fApi = formCreate.create(rules, options);

create 方法通过规则数组生成表单,并允许通过 options 配置表单的行为(如提交事件、初始值等)。返回的 fApi 是一个表单 API 对象,可以用于动态控制表单。

getApi

通过表单的 name 获取表单的 API 实例。这在需要跨组件或在大型应用中操作特定表单时非常有用。

  • 类型
ts
type GetApi = (name:string) => Api | Api[];
  • 示例
html
<form-create name="form" :rule="rule" />
js
const api = formCreate.getApi('form')

copyRules

用于拷贝生成规则的数组,确保对规则的更改不会影响原始规则。

  • 类型
ts
type CopyRules = (rules:Rule[]) => Rule[];
  • 示例
js
const rules = formCreate.copyRules([{
  type:'input',
  field:'goods_name',
  title:'商品名称',
  value:'form-create'
}])

copyRule

用于拷贝单个生成规则,确保对规则的更改不会影响原始规则。

  • 类型
ts
type CopyRule = (rule:Rule) => Rule;
  • 示例
js
 const rule = formCreate.copyRule({
  type:'input',
  field:'goods_name',
  title:'商品名称',
  value:'form-create'
})

JSON转换相关方法

toJson

将指定生成规则转换为 JSON 字符串,方便存储和传递。

  • 类型
ts
type ToJson = (value:Rule[]|object) => string;
  • 示例
js
const rules = [
    { type: 'input', field: 'goods_name', title: '商品名称', value: 'form-create' }
];
const json = formCreate.toJson(rules);
console.log(json); // 输出JSON字符串

parseFn

parseFn 方法将函数转换为 JSON 字符串。

  • 类型
ts
type ParseFn = (fnString:string) => Function;
  • 示例
js
const fn = formCreate.parseFn(`function() {
    console.log('This is a function');
}`);

parseJson

将 JSON 字符串转换为表单的生成规则,用于恢复表单结构。

  • 类型
ts
type ParseJson = (json:string) => Rule[]|object;
  • 示例
js
const json = '{"type":"input","field":"goods_name","title":"商品名称","value":"form-create"}';
const rules = formCreate.parseJson(json);

组件和扩展相关方法

$form

获取 FormCreate 组件实例,通常用于手动挂载到应用中。

  • 类型
ts
type $form = () => Component;
  • 示例
js
const $formCreate = formCreate.$form();
app.component('form-create', $formCreate);

component

用于在 FormCreate 中挂载或获取自定义组件。

  • 类型
ts
type Component = (name: string, component?: Component)=> Component|undefined;
  • 示例
js
//挂载组件
formCreate.component('user',component)
//获取组件
const component = formCreate.component('user')

componentAlias

用于为组件设置别名,便于在生成规则中使用更简洁的名称引用组件。

  • 类型
ts
type ComponentAlias = (alias:{[aliasName:string]:string }) => void;
  • 示例
js
formCreate.componentAlias({btn:'ElButton'})

setModelField

设置自定义表单组件值的双向绑定字段名称,默认为 modelValue

ts
type SetModelField = (componentName:string,propName:string) => void;
  • 示例
js
formCreate.setModelField('input','value');

directive

用于在 FormCreate 中挂载自定义指令。

  • 类型
ts
type Directive = (name:string, directive:Directive) => void;
  • 示例
js
formCreate.directive('autofocus',(el) => {
  el.focus();
})

数据处理相关方法

setData

挂载自定义数据,使其在表单中可用,方便在组件间共享数据。

  • 类型
ts
type SetData = (name:string,value:any) => void;
  • 示例
js
 formCreate.setData('options',[
        {label:'好用',value:0},
        {label:'快速',value:1},
        {label:'高效',value:2},
        {label:'全能',value:3},
 ]);

setDataDriver

导入自定义的数据获取函数,允许你根据特定的逻辑从外部数据源中获取数据。

  • 类型
ts
type SetDataDriver = (id: string, callback: (key: string) => any) => void;
  • 示例
js
formCreate.setDataDriver('$user', function(key) {
    return $store.state.user[key];
});

setDataDriver 方法允许你为表单指定数据驱动函数,使得表单组件可以动态地获取数据。例如,你可以从 Vuex 状态管理中获取用户数据,并在表单中显示。

getData

获取先前通过 setData 挂载的自定义数据。

  • 类型
ts
type GetData = (name: string) => any;
  • 示例
js
const options = formCreate.getData('options');
console.log(options);

removeData

移除之前通过 setData 方法挂载的自定义数据。

  • 类型
ts
type RemoveData = (name:string) => void;
  • 示例
js
formCreate.removeData('options');

refreshData

手动刷新与特定数据相关的表单渲染,确保表单组件的显示和数据保持同步。

  • 类型
ts
type RefreshData = (name:string) => void;
  • 示例
js
formCreate.refreshData('options');

fetch

FormCreate 内置的数据请求方法,支持重写,方便处理异步数据。

  • 类型
ts
type Fetch = (options: {
  //接口
  action: String;
  //请求方式
  method?: String;
  //调用接口附带数据
  data?: object;
  //调用接口附带数据的提交方式,默认为 `formData`
  dataType?: 'json';
  //自定义 header 头信息
  headers?: object;
  //接口调用成功回调
  onSuccess: (body: any) => void
  //接口调用失败回调
  onError?: (e: Error | ProgressEvent) => void;
})=> void;
  • 示例
js
formCreate.fetch({
  action: 'https://api.example.com/data',
  method: 'POST',
  data: { key: 'value' },
  onSuccess: (response) => {
    console.log('Data fetched', response);
  },
  onError: (error) => {
    console.error('Error fetching data', error);
  }
});

进阶扩展方法

extendApi

扩展 formCreate 的表单 API,添加自定义的表单操作方法。

  • 类型
ts
type ExtendApi = (fn:(api: Api)=>Object) => void;
js
formCreate.extendApi((api) => ({
  open(id) {
    console.log('This is a custom method');
    api.top.el(id).open();
  }
}));

parser

为表单组件绑定自定义解析器,用于处理特殊的数据格式或转换逻辑。

  • 类型
ts
type Parser = (name:string,parser:Parser) => void;
  • 示例
js
formCreate.parser({
    name:'input',
    toFormValue(val){
        return parseFloat(val)||0
    }
})

register

用于注册自定义属性扩展,使得在生成规则时可以自动执行某些逻辑。

  • 类型
ts
type Register = (name:string, effect:Effect) => void;
  • 示例
js
formCreate.register('loadOptions', {
  component:'select',
  init(rule){
      rule.props.options = [
        {label:'好用',value:0},
        {label:'快速',value:1},
        {label:'高效',value:2},
        {label:'全能',value:3},
      ];
  }
})

factory

创建一个全新的 formCreate

  • 类型
ts
type Factory = () => FormCreate;
  • 示例
js
const subFormCreate = formCreate.factory()

use

安装 formCreate 插件。如果插件是一个对象,必须提供 install 方法。如果插件是一个函数,它会被作为 install 方法。install 方法调用时,会将 formCreate 作为参数传入。 该方法需要在插件初始化时调用。

  • 类型
ts
type Use = (fn: (formCreate:FormCreate, opt:object) => FormCreate) => void;

useApp

组件初始化时会通过 app 被回调

  • 类型
ts
type UseApp = (fn: (formCreate:FormCreate, app:App)=>void ) => void;

FormCreate 提供了丰富的全局方法,使得表单的创建、管理和操作更加灵活和高效。通过 create 方法,你可以轻松地生成表单实例,并通过其他全局方法,如 getApicomponentsetData 等,进一步扩展和控制表单的行为。无论是挂载自定义组件、处理表单数据,还是配置复杂的交互逻辑,将帮助你更好地发挥 FormCreate 的全部潜力。

FormCreate 是一个开源项目,基于 MIT 许可证发布,欢迎个人和企业用户免费使用