yj-Kikimore

几个 Element Plus / Element 组件的封装。

安装

npm i yj-kikimore

• Vite

// vite.config.ts

export default defineConfig({
  optimizeDeps: {
    include: ['yj-kikimore'],
  },
})

• Vue CLI

// vue.config.js

module.exports = {
  transpileDependencies: ['yj-kikimore'],
}

Element Plus (Vue 3)

局部注册

<script setup>
import { KiFormDialog, KiPopButton, KiPopSwitch, KiSelect } from 'yj-kikimore'
</script>

全局注册

import { KiFormDialog, KiPopButton, KiPopSwitch, KiSelect } from 'yj-kikimore'

app
  .use(KiFormDialog, {
    // 全局配置
  })
  .use(KiPopButton, {
    // 全局配置
  })
  .use(KiPopSwitch, {
    // 全局配置
  })
  .use(KiSelect, {
    // 全局配置
  })

CDN

⚠ 暂不支持。

Element (Vue 2)

局部注册

<script>
import { KiFormDialog, KiPopButton, KiPopSwitch, KiSelect } from 'yj-kikimore'

export default {
  components: { KiFormDialog, KiPopButton, KiPopSwitch, KiSelect },
}
</script>

全局注册

import Vue from 'vue'
import { KiFormDialog, KiPopButton, KiPopSwitch, KiSelect } from 'yj-kikimore'

Vue.use(FormDialog, {
  // 全局配置
})
Vue.use(KiPopButton, {
  // 全局配置
})
Vue.use(KiPopSwitch, {
  // 全局配置
})
Vue.use(KiSelect, {
  // 全局配置
})

CDN

⚠ 暂不支持。

FormDialog

el-dialog + el-form 组合拳。

特性

• 打开对话框自动回显数据，关闭对话框自动重置数据
• 提交、拒绝、重置、全屏一应俱全
• 校验失败时平滑滚动至错误项并震动提示
• 限制高度，无页面级滚动条
• 只读模式
• 支持全局属性、全局事件、全局插槽 (vue-global-config 提供技术支持)

属性

事件

modelValue (Vue 3) / value (Vue 2) / v-model

如果是 plain object 类型，将用于 el-form 的 model。

onMounted 时记录初始值 (与 el-form-item 保持一致)，关闭对话框时会重置至初始值。

retrieve

<template>
  <KiFormDialog
    :retrieve="() => {
      // 表格打开之后、获取数据之前
      $POST('xxx').then(() => {
        // 获取数据之后
      })
    }"
  />
</template>

readonly

开启只读模式时默认不显示确认和取消按钮。

跟 <el-form disabled /> 的区别是在样式上，更便于用户阅读。

如果希望部分组件不进入禁用状态：

• 单独给这个组件设置 :disabled="false"
• 给这部分组件包一层 <el-form />

confirm

如果返回一个 Promise 实例，则在该 Promise 实例状态终结后对话框才会关闭。

<template>
  <KiFormDialog
    :confirm="() => {
      // 确认之前
      $POST('xxx').then(() => {
        // 确认之后
      })
    }"
  />
</template>

返回 Promise.reject() / Promise.resolve({ show: true }) / { show: true } 时对话框不会关闭。

<template>
  <KiFormDialog
    :confirm="() => {
      const valid = true
      if (valid) {
        return $POST('xxx')
      }
      else {
        $swal.warning('校验失败')
        return {
          show: true,
        }
      }
    }"
  />
</template>

deny

如果返回一个 Promise 实例，则在该 Promise 实例状态终结后对话框才会关闭。

<template>
  <KiFormDialog
    :deny="() => {
      // 确认之前
      $POST('xxx').then(() => {
        // 确认之后
      })
    }"
  />
</template>

返回 Promise.reject() / Promise.resolve({ show: true }) / { show: true } 时对话框不会关闭。

<template>
  <KiFormDialog
    :deny="() => {
      const valid = true
      if (valid) {
        return $POST('xxx')
      }
      else {
        $swal.warning('校验失败')
        return {
          show: true,
        }
      }
    }"
  />
</template>

reverseButtons

关于 “确定” 和 “取消” 按钮的顺序，可以看看这篇知乎回答。

方法

事件

插槽

改变遮罩层定位

.el-dialog__wrapper, .v-modal {
  position: absolute;
}

// 在原来的基础上减去 navbar + tab 的高度 (以 90px 为例)
.el-dialog {
  .el-dialog__body {
    max-height: calc(100vh - 190px) !important;
  }

  &.is-fullscreen .el-dialog__body {
    max-height: calc(100vh - 135px) !important;
  }
}

PopButton

el-button + el-popconfirm + el-popover + el-tooltip 组合拳。

特性

• 操作拦截 (el-popconfirm 点击确定后才会触发 click 事件)
• el-popover 和 el-tooltip 的 content 属性均支持渲染 HTML
• el-tooltip 不与 el-popconfirm、el-popover 冲突
• el-popconfirm、el-popover、el-tooltip 内容为空时，默认不启用
• 支持全局属性、全局事件、全局插槽 (vue-global-config 提供技术支持)

属性

事件

el-popconfirm、el-popover 的事件。

插槽

PopSwitch

el-switch + el-popconfirm + el-popover + el-tooltip 组合拳。

特性

• 操作拦截 (el-popconfirm 点击确定后才会触发 change 事件)
• 支持内嵌文字描述，宽度自适应
• el-popover 和 el-tooltip 的 content 属性均支持渲染 HTML
• el-tooltip 不与 el-popconfirm、el-popover 冲突
• el-popconfirm、el-popover、el-tooltip 内容为空时，默认不启用
• 支持全局属性、全局事件、全局插槽 (vue-global-config 提供技术支持)

属性

方法

通过 ref 调用 el-switch 的方法。

事件

el-switch、el-popconfirm、el-popover 的事件。

插槽

Select

el-select + el-option + el-option-group 组合拳。

特性

• 单向绑定 label
• 远程搜索时无需关心 options 和 loading
• 无匹配选项时展示 label (而不是 value)
• 多选时支持一键全选
• 支持全局属性、全局事件、全局插槽、全局作用域插槽 (vue-global-config 提供技术支持)

属性

options

默认情况下绑定值将得到选中项的数组元素本身。

可使用 props.value 改变此行为 (比如选项的数组元素是 plain object 类型，而绑定值只想要其中某个属性)。

props

interface Props {
  // 定位 option 中的 value
  // 如果是 string 类型，将默认用于 el-select 的 value-key
  'value': string | symbol | ((value: any) => any)
  // 定位 option 中的 label
  'label': string | symbol | ((value: any) => string)
  // 定位 option 中的 disabled
  'disabled': string | symbol | ((value: any) => boolean)
  // 定位 option 中分组的 label
  'groupLabel': string | symbol | ((value: any) => string)
  // 定位 option 中分组的 options
  'groupOptions': string | symbol | ((value: any) => any[])
  // 定位 option 中分组的 disabled
  'groupDisabled': string | symbol | ((value: any) => boolean)
}

• 支持属性名，如 'url'
• 支持属性路径，如 'data[0].url'
• 支持 symbol 类型的属性名
• 支持 Function，如 value => value.url

方法

事件

el-select 的事件。

插槽

命名

关于 value 和 label 的命名：

• value：这里要表达的含义就是选中目标的 “值”，等同于原生 <input type="checkbox"> 元素的 value 属性，不一定是其唯一标识，所以不应该使用 id 或者 key，且 key 与 Vue 的特殊 attribute 冲突。

• label：HTML 中 <label> 与 <input> 元素相关联，用于对后者进行说明，所以 label 天生是用来表达选中目标的 “展示名称” 的，而 ‘name’ 由于与原生 <input> 元素的 name 属性冲突故不考虑使用 ‘name’。

Element 本身没有做到命名的统一，el-select 中 label 表示选项的标签， 但 el-checkbox 中 label 却表示的是选中状态的值。

UI 组件库的标杆 Ant Design 也是使用 value 与 label 命名。