@hxyfe/mc-form

介绍

mc-form，一个表单通用组件，目的是通过一份配置文件生成一个表单，减少重复性的工作。demo。

安装

npm install mc-form -S

使用

// mc-form-installer.js
import Vue from 'vue';
import McForm from 'mc-form';
import 'mc-form/dist/assets/index.css';

// 组件安装
Vue.component(McForm.name, McForm);

组件属性: `config`

mc-form的配置文件，根据该配置生成表单

{
  // 是否开启特殊符号拼接的字段解析 后续详解
  symbol: false,
  // el-row的gutter
  gutter: 10,
  // el-form的label-width
  labelWidth: '80px',
  // 初始state
  state: {},
  // 各个表单项配置
  properties: []
}

表单项配置: `config.properties`

config.properties为数组，里面包含了各种表单项的相关配置对象。通用字段如下：

{
  // 表单项类型
  type: 'text|number|password|select|checkbox|radio|time|year|month|date|dates|week|datetime|datetimerange|daterange|monthrange|selector|editor|inputrange|upload|tree|component',
  // 字段名
  field: 'field',
  // 标签值
  label: 'label',
  // 字段初始值
  value: 'value',
  // ui
  ui: {
    // 所占栏数，总共24栏
    column: 24,
    // 大小
    size: 'mini',
    // 强制换行，无视内部的排列规则
    wrap: false,
    // 是否占位，此处用于与前一个构成if-else，若为false，不进行column计算
    occupation: true,
    // 是否隐藏 支持dx表达式
    hidden: false,
    // 是否disabled 支持dx表达式
    disabled: false,
    // 是否readonly 支持dx表达式
    readonly: false,
    // 是否可清空
    clearable: false,
    // 占位
    placeholder: '',
    // label宽度
    labelWidth: ''
  },

  // 关联字段，当当前字段的值发生变化是，会触发以下字段的更新，使用场景，省市区关联
  linkeds: [
    {
      // 路径
      path: 'field',
      // 值 支持dx表达式
      value: 'dx:{{ [] }}',
      // 是否需要刷新options.data(省市区多级联动之类的)
      refresh: true
    }
  ],

  // 校验规则，与el-form一致
  rules: [
    { required: true, message: '必填', trigger: 'change'}
  ]
}

1. 文本框 demo

{
  // 文本框类型
  type: 'text|number|password',
  // 字段
  field: 'field',
  //字段初始值
  value: null,
  // label
  label: '文本框'

  input: {
    // 支持所有el-input的相关属性，驼峰命名
  }
}

2. inputnumber demo

{
  // inputnumber
  type: 'inputnumber',
  // 字段
  field: 'field',
  //字段初始值
  value: null,
  // label
  label: '数量'

  inputnumber: {
    // 支持所有el-input-number的相关属性，驼峰命名
  }
}

3. 单选框 demo

{
  // 单选框
  type: 'radio',
  // 字段
  field: 'field',
  //字段初始值
  value: null,
  // label
  label: '单选框',
  // 选项相关
  options: {
    // 选项，支持数组或者字符串，如果是字符串，到this.$store去获取
    data: [ { label: '是', value: 1 } ] || 'state.DICT.dict.vipLevels',
    // 键值字段相对于data选项的映射
    label: 'label',
    value: 'value',

    // 异步请求获取选项，当该选项存在时，data无效
    ajax: {
      // 自定义请求函数，当该值不存在时，使用全局配置的request
      request: (data, params) => Promise.reolve([]),
      // 请求链接
      url: '/url',
      // 拼在链接后的参数 值支持dx表达式
      params: {
        id: 'dx:{{ $state.id }}'
      }, 
      // request body的参数 值支持dx表达式
      data: {
        name: 'dx:{{ $state.name }}'
      },
      // 方法
      method: 'post',
      // 请求前判断，如果返回falsy，则不发送请求。 支持dx表达式
      beforeSend: 'dx:{{ !!$state.parentId }}',
      // 使用后端接口返回的结果，根据该路径去获取选项数据
      path: 'data.content'
    },
    // 包含的值 支持dx表达式
    include: [],
    // 排除的值 支持dx表达式
    exclude: []
  },
  // 单选框相关配置
  radio: {
    // 是否显示边框
    border: false,
    // 按钮形式的 Radio 激活时的文本颜色
    textColor: '#fff',
    // 按钮形式的 Radio 激活时的填充色和边框色
    fill: '#409EFF'
  }
}

4. 多选框 demo

{
  // 多选框
  type: 'checkbox',
  // 字段
  field: 'field',
  //字段初始值
  value: null,
  // label
  label: '多选框',
  // 选项相关
  options: {
    // 选项，支持数组或者字符串，如果是字符串，到this.$store去获取
    data: [ { label: '是', value: 1 } ] || 'state.DICT.dict.vipLevels',
    // 键值字段相对于data选项的映射
    label: 'label',
    value: 'value',

    // 异步请求获取选项，当该选项存在时，data无效
    ajax: {
      // 自定义请求函数，当该值不存在时，使用全局配置的request
      request: (data, params) => Promise.reolve([]),
      // 请求链接
      url: '/url',
      // 拼在链接后的参数 值支持dx表达式
      params: {
        id: 'dx:{{ $state.id }}'
      }, 
      // request body的参数 值支持dx表达式
      data: {
        name: 'dx:{{ $state.name }}'
      },
      // 方法
      method: 'post',
      // 请求前判断，如果返回falsy，则不发送请求。 支持dx表达式
      beforeSend: 'dx:{{ !!$state.parentId }}',
      // 使用后端接口返回的结果，根据该路径去获取选项数据，使用||做或处理
      path: 'data.content'
    },
    // 包含的值
    include: [],
    // 排除的值
    exclude: [],
    // 额外添加一个全选功能
    checkAll: true
  },
}

5. 选择框 demo

{
  // 选择框
  type: 'select',
  // 字段
  field: 'field',
  //字段初始值
  value: null,
  // label
  label: '选择框',
  // 选项相关
  options: {
    // 选项，支持数组或者字符串，如果是字符串，到this.$store去获取
    data: [ { label: '是', value: 1 } ] || 'state.DICT.dict.vipLevels',
    // 键值字段相对于data选项的映射
    label: 'label',
    value: 'value',

    // 异步请求获取选项，当该选项存在时，data无效
    ajax: {
      // 开启远程搜索 值为请求参数名
      remote: 'name',
      // 自定义请求函数，当该值不存在时，使用全局配置的request
      request: (data, params) => Promise.reolve([]),
      // 请求链接
      url: '/url',
      // 拼在链接后的参数 值支持dx表达式
      params: {
        id: 'dx:{{ $state.id }}'
      }, 
      // request body的参数 值支持dx表达式
      data: {
        name: 'dx:{{ $state.name }}'
      },
      // 方法
      method: 'post',
      // 请求前判断，如果返回falsy，则不发送请求。 支持dx表达式
      beforeSend: 'dx:{{ !!$state.parentId }}',
      // 使用后端接口返回的结果，根据该路径去获取选项数据
      path: 'data.content'
    },
    // 包含的值
    include: [],
    // 排除的值
    exclude: [],
    // 额外选项，例如搜索框加个全部神马的
    additional: {
      [label]: 'label',
      [value]: 'value'
    }
  },
  // 针对选择框的配置
  select: {
    // 支持所有el-select的相关属性，驼峰命名
  }
}

6. 日期时间选择器 demo

{
  // 选择器类型
  type: 'time|year|month|date|dates|week|datetime|datetimerange|daterange|monthrange',
  // 字段
  field: 'field',
  //字段初始值
  value: null,
  // label
  label: '日期选择器',
  // 针对选择器的配置选项
  picker: {
    // 支持所有el-date-picker el-time-picker的相关属性，驼峰命名
  }
}

7.选择器 demo

该组件是为了类似于点击按钮，出现弹窗后选择的类似需求，需要配合setState和selector.event使用。界面形式为左边el-tag，右边el-button

{
  // 选择器
  type: 'selector',
  // 字段
  field: 'field',
  // 字段初始值
  value: null,
  // label
  label: '日期选择器',
  // 针对选择器的配置选项
  selector: {
    // el-tag展示字段，对应value数组值的键
    label: 'label',
    //  按钮类型
    type: 'primary',
    // 按钮显示文本
    text: '选择',
    // 标签的size
    size: 'medium',
    // 按钮触发的事件名称
    event: 'click',
    // 标签是否允许删除
    closable: true,
  }
}

8. 富文本 demo

需要额外安装mc-form-editor组件

{
  // 富文本
  type: 'editor',
  // 字段
  field: 'field',
  // 字段初始值
  value: null,
  // label
  label: '富文本',
  // 针对富文本的配置选项
  editor:{
    // 菜单
    menus: [
      'head',
      'bold',
      'fontSize',
      'fontName',
      'italic',
      'underline',
      'strikeThrough',
      'foreColor',
      'backColor',
      'list',
      'justify',
      'image'
    ],
    // 字体颜色
    colors: [
      '#000000',
      '#eeece0',
      '#1c487f',
      '#4d80bf',
      '#c24f4a',
      '#8baa4a',
      '#7b5ba1',
      '#46acc8',
      '#f9963b',
      '#ffffff'
    ],
    zIndex: 9,
    // 使用后端接口返回的结果，根据该路径去获取图片上传路径
    path: 'content',
    // 额外参数
    data: {}
    // 上传接口
    action: null,
    // 自定义请求函数，当该值不存在时，使用全局配置的request
    request: (formData) => Promise.reolve({}),
    // 上传名称
    uploadFileName: 'file',
    uploadImgShowBase64: false,
    uploadImgMaxSize: 1 * 1024 * 1024,
    // 成功回调判断
    onSuccess: _ => ({ success: true })
  }
}

9. 文本框范围 demo

{
  // 文本范围
  type: 'inputrange',
  // 字段
  field: 'field',
  // 字段初始值
  value: null,
  // label
  label: '文本框范围',
  // 针对文本范围的配置选项
  inputrange: {
    // 范围选择时开始日期的占位内容
    startPlaceholder: '',
    // 范围选择时结束日期的占位内容
    endPlaceholder: '',
    // 选择范围时的分隔符
    rangeSeparator: '-',
    // 文本框类型
    type: 'number'
  }
}

10. 文件上传 demo

{
  // 文件上传
  type: 'upload',
  // 字段
  field: 'field',
  // 字段初始值
  value: null,
  // label
  label: '文件上传',
  // 针对上传的配置选项
  upload: {
    // 接受上传的文件类型（thumbnail-mode 模式下此参数无效）
    accept: 'image/jpeg,image/jpg,image/png',
    // 必选参数，上传的地址
    action: '',
    // 设置上传的请求头部
    headers: {},
    // 是否支持多选文件
    multiple: false,
    // 上传的文件字段名
    name: 'file',
    // 最大允许上传个数
    limit: 0,
    // tip
    tip: '',
    // 文件列表的类型
    listType: 'picture-card',
    // 文件大小限制 单位为M
    limitSize: 1,
    // 上传前校验
    beforeUpload: blob => Promise.reject(),
    // 请求完成后执行的回调，返回一个对象。success: 是否上传成功，message: 失败后的提示语，uri: 文件上传路径
    onSuccess: res => ({ success: res.code === 200, message: res.chnDesc, uri: res.content }),
    urlPrefix: '', // 上传回显示资源，需要拼上的前缀
  }
}

11. 树

抱歉，尚未实现异步加载

{
  // 树
  type: 'tree',
  // 字段
  field: 'field',
  // 字段初始值
  value: null,
  // label
  label: '树',
  // 针对树的配置选项
  tree: {
    // 展示数据
    data: [] || 'state.USER.user.permissionTree',
    // 内容为空的时候展示的文本
    emptyText: '暂无数据',
    // 每个树节点用来作为唯一标识的属性，整棵树应该是唯一的
    nodeKey: 'id',
    // 配置选项
    props: {
      label: 'label',
      children: 'children'
    },
    // 是否高亮当前选中节点，默认值是 false
    highlightCurrent: false,
    // 是否默认展开所有节点
    defaultExpandAll: false,
    // 是否在点击节点的时候展开或者收缩节点， 默认值为 true，如果为 false，则只有点箭头图标的时候才会展开或者收缩节点
    expandOnClickNode: true,
    // 是否在点击节点的时候选中节点，默认值为 false，即只有在点击复选框时才会选中节点
    checkOnClickNode: false,
    // 展开子节点的时候是否自动展开父节点
    autoExpandParent: true,
    // 在显示复选框的情况下，是否严格的遵循父子不互相关联的做法，默认为 false
    checkStrictly: false,
    // 是否每次只打开一个同级树节点展开
    accordion: false,
    // 是否只获取选中的叶子节点
    leafOnly: false,
    // 是否包含半选节点
    includeHalfChecked: false,
    // 是否设置子节点
    deep: false
  }
}

12. 纯文本

纯文本，可用于写个表头或者描述性文本

{
  type: 'plaintext',

  plaintext: {
    // 文字对齐方式
    align: 'center',
    // 显示文本 支持dx表达式
    text: '',
    // 文本css classname
    clsName: ''
  }
}

13. 自定义组件 demo

众所周知，产品的需求是相当骚的，为了实现某些骚操作，开放自定义组件的功能供开发者使用。

{
  type: 'component',
  // component实例
  component: Component
}

使用自定义组件可接受以下 props: ['state', 'gutter']。同时，由于自组件不能修改父组件的数据，需要额外$emit，不能舒舒服服的用v-model，请自行衡量。

// 修改对象属性值 this.$emit('update:object', 修改对象, 修改属姓名, 修改属性值);
this.$emit('update:object', this.state, 'name', '刘伟健');
// 或者
this.$emit('update:object', this.state, { name: '刘伟健' });
// 修改数组，增删 this.$emit('update:array', 修改数组, 数组方法名, 额外参数);
this.$emit('update:array', this.state.users, 'push', { name: null, sex: null });

修改默认配置

由于默认配置不太适合于其他项目，所以提供一个可修改默认配置的方法。PS：请在mc-form注册前设置。

import instance from '@http/instance';
import McForm, { setDefaultConfigs } from 'mc-form';

export default function install(Vue) {
  // 组件安装
  Vue.component(McForm.name, McForm);
  // 修改以上默认配置
  setDefaultConfigs({
    // options相关异步获取的全局配置实例
    request: instance,
    // 修改上传的成功处理
    upload: {
      onSuccess: res => ({ success: false, message: 'error' })
    };
  });
}

组件实例方法

{
  /**
   * @param { String | undefined } field 字段名，不传则返回整个state
   * @returns { Any }
   * @description 获取表单state
   */
  getState(field) {},

  /**
   * @returns { Promise }
   * @description 表单校验
   */
  validate() {},

  /**
   * @description 移除验证效果
   */
  clear() {},

  /**
   * @param { String | Object } field 字段名
   * @param { Any } value 字段值
   * @description 设置state
   */
  setState(field, value) {},

  /**
   * @param { Object } state
   * @description 替换state
   */
  replace(state) {},

  /**
   * @param { String } field 字段名
   * @param { String } prop 属性名: disabled, readonly, hidden, closable
   * @param { String | Boolean } expr 支持dx表达式
   * @description 设置可编辑性
   */
  setEditable(field, prop, expr) {},

  /**
   * @param { String } field 字段名
   * @param { String } prop 选项名: include, exclude, data
   * @param { Array } options
   * @description 设置options.data 或者 tree.data
   */
  setOptions(field, prop, options) {},

  /**
   * @description 重置表单
   */
  reset() {}
}

组件事件

组件事件只针对内置组件做通知，自定义组件不会触发。回调参数为一个对象: { field, value }，value视element-ui的相关组件的相关事件的回调参数而定。

change: 值改变时触发，相当于input，历史原因，保留命名
native-change: 相当于change
blur: 失去焦点触发
focus: 获取焦点触发

<mc-form @change="handleChange"></mc-form>

关于dx表达式 demo

dx表达式的存在是为了实现数据关联的效果。例如，当某字段为空时不允许编辑 disabled: 'dx:{{ !$state.field }}'，具有以下特点:

格式如：'dx:{{ expression }}'
特殊字段$state代表表单(el-form)的model对象
不允许赋值的存在，比如 'dx{{ $state.name = 1 }}'是不合法的

关于关联字段 demo

关联字段的存在是为了设置关联的字段值，和刷新相关的选项。

关于特殊符号拼接的字段 demo

为了更方便地获取和设置mc-form的state，可以使用symbol: true开启以下特殊符号在字段中的特殊作用

-: 范围字段设置。例如: state['a-b'] = [ state.a, state.b ]，主要应用于range相关的组件
>: 路径字段设置。例如: state['a>b'] = state.a.b
@: 设置关联字段为数组。例如字段 tagIds@tagNames, state = {tagIds: [1,2,3], tagNames: ['刘', '伟', '健']}，会被设置为 state['tagIds@tagNames'] = [{id: 1, name: '刘'}, {id: 2, name: '伟'}, {id: 3, name: '健'}]
&: 设置关联字段为对象。例如字段 tagId&tagName, state = {tagId: 1, tagName: '刘伟健'}，会被设置为 state['tagId&tagName'] = { id: 1, name: '刘伟健' }

关于请求缓存

对于某些请求，例如获取省市区，我们希望能够缓存起来不做二次请求。考虑到mc-form不能进行全局缓存，所以便不支持。但是开发者者可以在ajax.options.request上做处理。以下为实现全局缓存的例子，仅供参考：

/**
 * @param {Function} fn 执行函数，必须返回Promise对象
 * @param {String|Number} prop 缓存标识唯一的属性，从params[prop]中获取
 * @returns {Promise}
 * @description 创建多个缓存
 */
export function createCaches(fn, prop) {
  let caches = {};

  let cb = function _cache(params) {
    let key = params[prop];

    if (isEmptyValue(key)) {
      return Promise.reject(new Error(`params.${prop} is required`));
    }

    if (!caches[key]) {
      caches[key] = fn.call(this, params).catch(e => {
        delete caches[key];
        return Promise.reject(e);
      });
    }

    return caches[key];
  };
  // 清除缓存
  cb.clear = function(key) {
    isEmptyValue(key) ? (caches = {}) : (delete caches[key]);
  };

  return cb;
}

// 获取省市区
const requestRegions = createCaches(data => $http.post('/area', data.parentId === 'TOP' ? {} : data), 'parentId');

// config配置

const config = {
  properties: [
    {
      label: '省市区',
      type: 'select',
      field: 'provinceId',
      value: null,

      ui: {
        column: 8
      },

      options: {
        ajax: {
          request: requestRegions,
          data: {
            parentId: 'TOP'
          }
        },
        label: 'name',
        value: 'id'
      },

      linkeds: [
        {
          path: 'cityId',
          value: null,
          refresh: true
        }
      ]
    },

    {
      label: '',
      type: 'select',
      field: 'cityId',
      value: null,

      ui: {
        column: 4
      },

      options: {
        ajax: {
          request: requestRegions,
          data: {
            parentId: 'dx:{{ $state.provinceId }}'
          },
          beforeSend: 'dx:{{ !!$state.provinceId }}'
        },
        label: 'name',
        value: 'id'
      },

      linkeds: [
        {
          path: 'countyId',
          value: null,
          refresh: true
        }
      ]
    },

    {
      label: '',
      type: 'select',
      field: 'countyId',
      value: null,

      ui: {
        column: 4
      },

      options: {
        ajax: {
          request: requestRegions,
          data: {
            parentId: 'dx:{{ $state.cityId }}'
          },
          beforeSend: 'dx:{{ !!$state.cityId }}'
        },
        label: 'name',
        value: 'id'
      }
    }
  ]
}

@hxyfe/mc-form

介绍

安装

使用

组件属性: `config`

表单项配置: `config.properties`

1. 文本框 demo

2. inputnumber demo

3. 单选框 demo

4. 多选框 demo

5. 选择框 demo

6. 日期时间选择器 demo

7.选择器 demo

8. 富文本 demo

9. 文本框范围 demo

10. 文件上传 demo

11. 树

12. 纯文本

13. 自定义组件 demo

修改默认配置

组件实例方法

组件事件

关于dx表达式 demo

关于关联字段 demo

关于特殊符号拼接的字段 demo

关于请求缓存

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@hxyfe/mc-form

介绍

安装

使用

组件属性: config

表单项配置: config.properties

1. 文本框 demo

2. inputnumber demo

3. 单选框 demo

4. 多选框 demo

5. 选择框 demo

6. 日期时间选择器 demo

7.选择器 demo

8. 富文本 demo

9. 文本框范围 demo

10. 文件上传 demo

11. 树

12. 纯文本

13. 自定义组件 demo

修改默认配置

组件实例方法

组件事件

关于dx表达式 demo

关于关联字段 demo

关于特殊符号拼接的字段 demo

关于请求缓存

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

组件属性: `config`

表单项配置: `config.properties`

Weekly Downloads