Config 选项

本文档描述封装组件的详细配置，包括 CRUD、表单、表格、搜索、分页、弹窗等组件。

<template>
  <div>
    <crud ref="crudRef" :config="userConfig" />
  </div>
</template>

<script>
const userConfig = proxy.$createConfig({
  search: {...},
  form: {...},
  items: [
    {
      field: {...},
      props: {...},
      event: {...}
    }
  ],
  menu: [...],
  operate: [...],
});
</script>

所有参数设计，除非必要，均以 Element-Plus 属性命名为优先原则，以减少学习成本。

通常情况下，createConfig 会自动处理大部分预设配置，开发者只需要传入少量的必要配置，即可快速创建完整的组件。

---

结构说明

配置对象包含以下核心参数：

参数	是否必要	说明
idKey	可选	主键配置。
hideSearch	可选	隐藏搜索栏。
hideMenu	可选	隐藏菜单栏。
hideTool	可选	隐藏工具栏。
useDetail	可选	是否使用详情接口。
useDynamicSearch	可选	是否后端动态配置搜索栏。
waitTime	可选	防抖时间设置。
default	可选	默认表单数据配置。
dialog	可选	弹窗配置。
search	可选	搜索栏配置。
defaultSearchForm	可选	默认搜索表单。
localPagination	可选	是否启用本地分页
page	可选	分页配置。
table	可选	表格配置。
form	可选	表单配置。
items	必填	列项配置。
menu	可选	菜单栏配置。
operate	可选	操作栏配置。
group	可选	多级表头配置。

const example = {
  idKey: "someID", // 主键配置
  useDetail: false, // 是否使用详情接口
  useDynamicSearch: false, // 是否启用动态搜索栏
  waitTime: 500, // 防抖时间配置
  default: { someName: "", someDefType: "0" }, // 默认表单数据配置
  dialog: { width: "600px", style: { padding: "0px 14px" } }, // 弹窗配置
  search: { span: 1.5, labelWidth: 80, labelPosition: "right" }, // 搜索栏配置
  defaultSearchForm: { propName: value }, // 默认搜索表单
  page: { pageSize: 10, pageRange: [10, 20, 30, 50] }, // 分页配置
  table: {}, // 表格配置
  form: {}, // 表单配置
  items: [
    {
      type: "el-radio",
      field: { prop: "configName", label: "参数名称" },
      props: { options: [] }
    }
    // ...
  ],
  menu: ["add"], // 菜单栏配置
  operate: ["edit"] // 操作栏配置
};

---

主键 - idKey

• 说明：CRUD 操作中用于删除、编辑请求时的主键字段。
• 默认值："id"
• 示例：

  idKey: "someID";
  

---

编辑详情 - useDetail

• 说明：编辑数据时，是否使用详情接口获取完整数据。（默认匹配 API 中的 detail 接口）
• 类型：boolean
• 默认值：false
• 示例：

  useDetail: true;
  

---

动态搜索栏 - useDynamicSearch

• 说明：是否启用后端动态搜索栏。（默认匹配 API 的 dynamicSearch 接口）
• 类型：boolean
• 默认值：false

---

防抖时间 - waitTime

• 说明：防抖时间，用于控制按钮、搜索、弹窗等操作的延迟。
• 类型：number
• 默认值：500

---

默认表单 - default

• 说明：新增、编辑表单的默认值配置。
• 示例：

  default: {
    someName: '',
    someDefType: '0'
  }
  

---

弹窗 - dialog

• 说明：弹窗的基础配置。
• 示例：

  dialog: {
    width: '600px',
    style: {
      padding: '0px 14px'
    }
    // 配置基本与 element 保持一致，可参照文档添加配置
  }
  

---

搜索栏 - search

• 说明：搜索栏的相关配置。
• 示例：

  search: {
    // 默认 1.5 代表宽度自适应, 即日期搜索要比 input 宽
    // 如配置为 12, 就代表一行 2个 input
    span: 1.5,
    // label 宽度设置, 默认自动计算
    // 取 items 中最宽的 label 作为 labelWidth
    labelWidth: 80,
    labelPosition: 'right'
    // 配置基本与 element 保持一致，可参照文档添加配置
  }
  

---

分页 - page

• 说明：分页配置。
• 示例：

  page: {
    // 用于适配不同开发人员的习惯
    pageKey: 'pageNum',
    pageSizeKey: 'pageSize',
    // 分页设置
    pageSize: 20, // 可选 pageRange 中配置的选项
    pageRange: [10, 20, 30, 50]
  }
  

---

表格 - table

• 说明：表格的配置项。
• 示例：

  table: {
    editable: false, // 开启行编辑
    defaultExpandAll: true, // 树表格展开
    treeProps: {
      children: 'children',
      hasChildren: 'hasChildren'
    }
  }
  

---

表单 - form

• 说明：表单的相关配置。
• 示例：

  form: {
    // 默认 24，如配置 12 就代表 2列表单，8 就代表 3列表单
    span: 24,
    // labelWidth 默认 ""
    // CRUD 框架内部会自动计算, 取所有 label 最宽的作为基准
    // 如果设置了此属性, 则优先级高于默认属性
    labelWidth: 120,
    // 规则配置，配置参数与 element 保持一致
    rules: {
      someRule: [
        {
          required: true,
          trigger: 'blur',
          message: '请正确填写...'
          // 更多配置，可参考 element 文档
        }
      ],
      // 基本与 element 一致，但加入了一些便捷操作
      // - 通常，既然写在 rules 中，基本都是必要的，还要额外写 required: true
      // - 所以 rules 默认加入了 required: true，以节省工作量
      requireRule: [{}], // 直接空 {} 也会有默认值校验
      // 灵活的设置
      // - 其他需要 false 的情况，可直接设置 false
      // - 比如验证手机，不是必须填写，但是如果填写就需要验证是否是正确的手机号
      falseRule: [{ required: false, pattern: isPhone }]
      // trigger 默认值 ['blur', 'change']
      triggerRule: [{}] // 可省略
      triggerRule1: [{ trigger: ['blur'] }] // 可覆盖
      // message 默认值取 label
      // 并根据不同的组件类型：input、select 等等
      // 会有不同的消息提示：请输入、请选择 等等
      nameRule: [{}] // 可省略
      nameRule1: [{ message: '请输入正确的名称' }] // 可覆盖
    }
  }
  

---

列项 - items

• 说明：表单或表格的字段配置。

• 示例：

  items: [
    {
      // type 对应 element 组件名称
      type: "el-radio", // 可省略，默认 el-input
      // field 完全对接 element
      // - 在表格中，对应 el-table-column 参数配置
      // - 在表单中，对应 el-form-item 参数配置
      field: {
        prop: "configName",
        label: "参数名称"
      },
      // props 对应 element 组件的 props 配置
      props: {
        type: "password",
        maxlength: 20
      },
      // event 对应 element 组件的 event 配置
      event: {
        onChange: someChangeFunc
      }
    }
  ];
  

• items 的额外自定义配置

  items: [
    {
      // 常规配置
      type: "el-radio",
      // 扩展 type，对应不同模式单独配置的组件
      // 可选：如果没有设置，默认取 type
      // 如果 type 未设置，默认 el-input
      searchType: "el-select",
      tableType: "el-input-number",
      formType: "el-input",
      // 宽度配置
      span: 24,
      searchSpan: 8,
      formSpan: 12,
      viewSpan: 24,
      // 组件显隐, 默认 false
      // 这样设计, 可公用一套配置项, 并可以灵活控制
      hideSearch: true,
      hideTable: true,
      hideForm: true,
      hideView: true,
      // 组件插槽, 默认 false
      // 用于提升组件灵活性, 以支持定制内容
      // 使用：设置为 true 后，在 crud 组件中使用插槽
      searchSlot: true,
      tableSlot: true,
      formSlot: true,
      viewSlot: true,
      // 注意：使用 slot 时，要遵循命名规则
      // - 规则说明
      // #[search|table|form|view] - [propName]
      // search 对应搜索栏, table 对应表格, form 对应表单, view 对应查看窗口
      // propName 对应 items 中的 prop 值
      // ---
      // 示例：
      // #search-name，表示搜索栏中，name 字段
      // #table-name="scope"，在表格中，可使用 scope.row
      // #form-name，在表单中，不需要 scope
      // ---
      // element 插槽兼容
      // #form-name-prefix, prefix 对应的是 element 的插槽具名
      // 这样, 即可以实现自定义插槽, 同时也兼容 element 插槽
      // element 插槽可参考 element 文档
  
      // 行内编辑，开启后可直接在表格上编辑
      // 注：行内编辑的渲染优先级 > table 插槽
      // 因为 table 插槽，大概率用来显示内容
      // 所以点击编辑时，应该覆盖掉 slot 插槽的自定义渲染
      editable: false,
      // 复制, 默认 false
      copy: false, // 开启后, 点击表格中内容可直接复制
      field: {
        // 控制列项的对齐
        // 可单独控制对应 search、table、form
        align: "center",
        formAlign: "left",
        // help 是自定义的参数，可为字符 ｜ 数组 [字符]
        // 设置 help 后会在对应的表单项加入 ? 提示
        help: "访问地址，若外网地址以 http(s):// 开头"
      },
      props: {}
    }
  ];
  

• 其他：表格中多选的固定写法

    // 固定写法
    { field: { type: 'selection' } },
    // 创建时，默认 50px 宽, 左对齐。所以只需配置 field type，可以省略其他参数
    // 如果想覆盖，直接正常配置参数即可
  

---

菜单栏 - menu

• 说明：菜单栏的配置。

• 示例：

  menu: [
    // 内置按钮，可直接输入字符串，会匹配按钮类型进行渲染展示
    "add", // 新增
    "dels", // 批量删除
    "import", // 导入（逻辑未实现，尚未根据业务调整）
    "export", // 导出（逻辑未实现，尚未根据业务调整）
    // 自定义按钮
    {
      // 按钮类型
      // - 如果设置为 add 则使用内置按钮的逻辑、样式
      // - 如果是自定义按钮，可以忽略，但是不设置 type 无法通过 findMenu 查找
      type: "add", // 按钮类型，自定义按钮可忽略
      text: "按钮文字",
      attr: {
        type: "primary", // 按钮主题
        icon: "Plus" // 按钮图标，对应 element 图标名称
      },
      // 按钮点击事件
      // - element {object} 对应按钮配置
      // - getList {function} 刷新列表数据
      // - dialog {function} 弹窗方法（true 打开弹窗，false 关闭弹窗）
      handle: function (element, getList, dialog) {},
      // 按钮确认事件
      // - 搭配内置弹窗的时候生效
      // - hideLoading {function} 隐藏 loading
      // - getList {function} 刷新列表数据
      // - dialog {function} 弹窗方法（true 打开弹窗，false 关闭弹窗）
      confirm: function (hideLoading, getList, dialog) {},
      // 控制按钮显隐
      // - 如果需要自定义显隐，可重写此方法
      handleVisible: function () {},
      // 按钮权限
      // - 后端程序员的命名习惯不同，以后端为准
      // - 目前约定的权限是：小驼峰 + 点 + 动作。
      // - 比如：system.add、systemUsers.edit
      permission: "somePermi.someAction"
    }
  ];
  

  其他情况示例

  // 使用内置的 “新增按钮”，及其逻辑，但是增加 permission 修改权限
  menu: [
    {'add', permission: 'system.add'},
    {
      type: 'add',
      // 内置的自定义逻辑是不生效的
      handle: function (element, getList, dialog) {
        // 这里只针对自定义按钮的配置
      }
    },
    {
      type: 'addRole',
      permission: 'role.add',
      handle: function (element, getList, dialog) {
        // 这时逻辑会生效，confirm 同理
      }
    }
  ]
  

---

操作栏 - operate

• 说明：操作栏配置。
• 示例：

  // 操作栏的配置方式与 menu 类似
  operate: [
    // 内置按钮
    "edit", // 编辑
    "del", // 删除
    "view", // 查看
    // 自定义按钮
    {
      type: "custom",
      text: "自定义操作",
      handle: function (element, getList, dialog) {},
      confirm: function (hideLoading, getList, dialog) {},
      // 控制按钮显隐
      handleVisible: function (row) {},
      // 按钮权限
      permission: "somePermi.someAction"
    }
  ];
  

---

多级表头 - group

• 说明：多级表头配置。

• 示例：

  group: [
    "title", // 如过是字符串，会判定为一级表头
    {
      label: "二级表头",
      children: ["coins", "level"]
    }
  ];
  
  // 多级表头示例
  group: [
    {
      label: '用户信息',
      children: [
        'username',
        'role',
        { label: '联系方式', children: ['email', 'phone'] },
      ],
    },
  ],
  

---

以上为各个配置项的详细说明，可根据业务需求灵活配置。