@aoao-y33/ui

v0.1.4

Published

a month ago

elementPlus二次封装组件

0High
0Medium
0Low

yangaoao

@aoao-y33/ui

基于 Vue 3 + Element Plus 的企业级 UI 组件库，提供丰富的业务组件和 Hooks，支持高度自定义和动态配置。

✨ 特性

🎨 基于 Element Plus：无缝集成 Element Plus 组件，保持一致的设计语言
🔧 高度可配置：支持动态配置组件属性、事件和样式
📦 丰富的组件：提供 Button、Form、Table、Modal、Layout 等常用业务组件
🎯 TypeScript 支持：完整的类型定义，提供良好的 IDE 提示
🚀 Hooks 驱动：使用 Composition API 和自定义 Hooks，提升开发效率
🌲 动态组件池：支持动态注册和管理组件，灵活扩展功能
📱 响应式设计：适配各种屏幕尺寸
🌓 深色模式：内置深色主题支持

📦 安装

bash npm install @aoao-y33/ui
或
pnpm add @aoao-y33/ui
或
yarn add @aoao-y33/ui

🚀 快速开始

按需引入

import { AxButton, useForm, useTable, useModal } from '@aoao-y33/ui'

样式引入

组件库默认会自动引入样式，如果需要单独引入：

import '@aoao-y33/ui/dist/index.css'

📖 组件文档

1. Button 按钮组件

基础按钮组件，支持多种类型和自定义配置。

基础用法

<template> 
	<AxButton text="点击我" type="primary" @click="handleClick" /> </template>
<script setup lang="ts"> 
import { AxButton } from '@aoao-y33/ui' 
const handleClick = () => { 
  console.log('按钮被点击') 
} 
</script>

带图标按钮

<template> 
	<AxButton text="搜索" type="primary" icon="Search" @click="handleSearch" /> 
</template>

动态控制显示/隐藏

<template> 
	<AxButton text="编辑" :hidden="(data) => !data.canEdit" :disabled="(data) => data.isLocked" /> 
</template>

注册自定义按钮类型

import { addButtonField } from '@aoao-y33/ui' 
import CustomButton from './CustomButton.vue'
addButtonField('custom', CustomButton)

API

AxButtonProps

| 属性 | 类型 | 默认值 | 说明 | | -------------- | -------------------------------- | ------ | ---------------------------- | | text | string | - | 按钮文本 | | type | keyof buttonFields | - | 按钮类型 | | icon | string \| Component | - | 图标名称或组件 | | disabled | boolean \| ((data) => boolean) | - | 禁用状态 | | hidden | boolean \| ((data) => boolean) | - | 隐藏状态 | | className | string | - | 自定义类名 | | isMl | boolean | - | 是否添加左边距 | | componentProps | ButtonProps | - | Element Plus Button 额外属性 |

事件

| 事件名 | 参数 | 说明 | | -------- | ------------------- | -------- | | click | (data: T) => void | 单击事件 | | dblClick | (data: T) => void | 双击事件 |

2. Form 表单组件

强大的表单组件，支持动态字段配置、验证和数据提交。

使用 ax-form组件

<template>
	<ax-form ref="form">
  	<ax-form label="用户名" field-name="username" type="text"></ax-form>
    <ax-form label="邮箱" field-name="mail" type="text" :vtypes="['required','mail']"></ax-form>
    <template #button>
			<ax-button @click="handleSubmit">提交</ax-button>
      <ax-button @click="handleReset">重置</ax-button>
		</template>
  </ax-form>
</template>
<script setup lang="ts">
import { AxForm,AxFormItem,AxButton } from '@aoao-y33/ui' 
const form = ref()
const handleSubmit = async (data:any) => { 
  await form.value?.load(data) 
} 
const handleReset = () => { 
  form.value?.resetValues() 
} 
</script>

使用 useForm Hook

<template>
	<Form /> 
</template>
<script setup lang="ts"> 
import { useForm } from '@aoao-y33/ui' 
const [Form, formApi] = useForm({ 
  fieldConfig: { 
    fields: [ 
      { 
        label: "用户名", 
        fieldName: 'username', 
        type: 'text' 
      }, 
      { 
        label: "邮箱", 
       	fieldName: 'email', 
        type: 'text', 
        vtypes: ['required', 'mail'] 
      } 
    ] 
  }, 
  buttonConfig: { 
    fields: [ 
      { 
        text: '提交',  
        onClick: handleSubmit,
      }, 
      { text: '重置', 
       onClick: handleReset 
      } 
    ] 
  } 
}) 
const handleSubmit = async (data:any) => { 
  await formApi.requestApi.load(data) 
} 
const handleReset = () => { 
  formApi.resetValues() 
} 
</script>

表单验证规则

内置验证规则：

required: 必填
phone: 手机号
tel: 固定电话
mail: 邮箱

import { addFormRules } from '@aoao-y33/ui'
// 注册自定义验证规则 
addFormRules('idCard', (type, label) => ({ pattern: /^\d{17}[\dXx]$/, message: `${label}身份证号格式错误` }))

API

useForm 返回值

| 属性 | 类型 | 说明 | | ---------- | -------------- | ---------------------------- | | Form | Component | 表单组件 | | setForm | StateApi | 更新表单属性 | | requestApi | FormFetchApi | 请求 API（submit、fetch 等） | | fieldsApi | FieldsApi | 字段管理 API | | buttonsApi | FieldsApi | 按钮管理 API |

formApi方法

类型：FormApi<T>
getElForm(): 获取底层的Element UI表单实例
getValues(): 获取表单的所有字段值
getValue(field:string): 获取表单指定字段的值
getFields(): 获取表单的所有字段名称列表
getDefaultValues(): 获取表单字段的默认值
setValues(data:T): 批量设置表单字段的值
resetValues(): 重置表单所有字段的值到默认状态
clearValues(): 清空表单所有字段的值

requestApi 方法

类型：FormFetchApi<T,R>
setConfig(config: FetchOptions<T, R>): 设置请求配置等信息
setApi(api: RequestFetch<T, R>): 设置请求API
load(params?: T): 加载表单数据，可选择传入参数
getConfig(): 获取当前请求的配置信息
get(): 获取请求结果
getReady(): 获取接口是否就绪状态
setParams(data: T, load?: boolean): 设置请求参数，指示设置参数后是否立即执行加载操作
reload(): 重新加载表单数据

3. Table 表格组件

高级表格组件，集成数据展示、分页、搜索、工具栏等功能。

使用 ax-table组件

<template>
	<ax-table :api="getUserList">
    <template #search>
			<ax-table-select>
  			<ax-form-item label="用户名" field-name="username"></ax-form-item>
  		</ax-table-select>
		</template>
		<template #tool>
			<ax-button @click=handleAdd>新增</ax-button>	
		</template>
  	<ax-table-column type="selection"/>
    <ax-table-column label="序号" type="index"/>
    <ax-table-column label="用户名" prop="username"/>
    <ax-table-column label="邮箱"  prop="username"/>
    <ax-table-column label="操作" :component-props="actionConfig"/>
		<template #footer>
			<ax-table-page :pageSizes="[10, 20, 50, 100]"/>
		</template>
  </ax-table>
</template>
<script setup lang="ts"> 
 import {getUserList} from '../api'
 const actionConfig = {
       actionList: [ { 
               	text: "修改", 
              	onClick: handleEdit 
             }, { 
               text: "删除", 
               onClick: handleDelete 
             } 
           ] 
 } 
 const handleEdit = (row: any) => { 
   console.log('编辑', row) 
 } 
 const handleDelete = (row: any) => { 
   console.log('删除', row) 
 } 
 const handleAdd = () => { 
   console.log('新增') 
 } </script>

使用 useTable Hook

<template>
	<Table /> 
</template>
<script setup lang="ts"> 
 import { useTable } from '@aoao-y33/ui' 
 import {getUserList} from '../api'
 const [Table, tableApi] = useTable({ 
   api: getUserList, 
   columnConfig: { 
     fields: [ 
       { type: 'selection' }, 
       { label: "序号", type: "index", width: 80 }, 
       { label: "用户名", prop: "username" }, 
       { label: "邮箱", prop: "email" }, 
       { 
         label: "操作", 
         type: "action", 
         componentProps: {
           actionList: [ 
             { 
               text: "修改", 
              	onClick: handleEdit 
             }, 
             { 
               text: "删除", 
               onClick: handleDelete 
             } 
           ] 
         } 
       } 
     ] 
   }, 
   searchConfig: { 
     fieldConfig: { 
       fields: [ 
         { label: "用户名", fieldName: "username", type: "text" } 
       ] 
     }
   }, 
   toolConfig: { 
     fields: [ 
       { 
         text: "新增", 
         type: "primary", 
         onClick: handleAdd 
       } 
     ] 
   }, 
   pageConfig: { 
     pageSizes: [10, 20, 50, 100] 
   }
 }) 
 const handleEdit = (row: any) => { 
   console.log('编辑', row) 
 } 
 const handleDelete = (row: any) => { 
   console.log('删除', row) 
 } 
 const handleAdd = () => { 
   console.log('新增') 
 } </script>

注册自定义列类型

import { addTableColumnField } from '@aoao-y33/ui' 
import StatusColumn from './StatusColumn.vue'
addTableColumnField('status', StatusColumn)

API

useTable 返回值

| 属性 | 类型 | 说明 | | ---------- | ------------- | ------------------ | | Table | Component | 表格组件 | | setTable | StateApi | 更新表格属性 | | setPage | StateApi | 更新分页配置 | | setSearch | StateApi | 更新搜索配置 | | toolsApi | FieldsApi | 工具栏按钮管理 API | | searchApi | FieldsApi | 搜索表单 API | | fieldsApi | FieldsApi | 搜索字段管理 API | | buttonsApi | FieldsApi | 搜索按钮管理API |

tableApi 方法

类型：TableApi
getElTable(): 获取ElTable 的所有原生方法和属性

requestApi方法：同上

4. Modal 弹窗组件

通用弹窗组件，支持 Drawer 和 Dialog 两种模式，可动态渲染内容。

使用ax-modal组件

<template> 
	<ax-modal title="用户详情" v-model:open="open">
  	<user-detail/>
    <template>
			<ax-button @clicl="open = false">关闭</ax-button>
		</template>
  </ax-modal>
	<button @click="open = true">打开弹窗</button> 
</template>
<script setup lang="ts"> 
import { useModal } from '@aoao-y33/ui' 
import UserDetail from './UserDetail.vue' 
const open = ref(false);
</script>

使用 useModal Hook

<template> 
	<Modal /> 
	<button @click="openModal">打开弹窗</button> </template>
<script setup lang="ts"> 
import { useModal } from '@aoao-y33/ui' 
import UserDetail from './UserDetail.vue' 
const [Modal, modalApi] = useModal({ 
  title: '用户详情', 
  type: 'dialog', // 'drawer' | 'dialog' 
  component: UserDetail, 
  buttonConfig: { 
    fields: [ 
      { 
        text: '关闭', 
        onClick: () => modalApi.close() 
      } 
    ] 
  } 
}) 
const openModal = () => { 
  modalApi.open() 
} 
// 获取内部组件实例 
const componentInstance = modalApi.getComponent() 
</script>

API

useModal 返回值

| 属性 | 类型 | 说明 | | ------------ | ----------- | ---------------- | | Modal | Component | 弹窗组件 | | buttonsApi | FieldsApi | 按钮管理 | | setModal | StateApi | 设置弹窗属性 | | open | Function | 打开弹窗 | | getComponent | Function | 获取内部组件实例 |

ModalApi 方法

close(): 关闭弹窗
getModal(): 获取原生弹窗组件实例

5. FormModal 表单弹窗组件

结合表单和弹窗的组件，适用于编辑、新增等场景。

使用ax-form-modal组件

<template> 
	<ax-form-modal ref="modalRef" :api="updateUser" title="编辑用户"	:api-config="apiConfog">
  	<ax-form-item label="用户名" field-name="username" :vtypes="['required']"></ax-form-item>
      	<ax-form-item label="用户名" field-name="username" :vtypes="['required', 'mail']"></ax-form-item>
  </ax-form-modal>
	<button @click="openEditModal">编辑</button> 
</template>
<script setup lang="ts"> 
import {AxFormModal,AxFormItem } from '@aoao-y33/ui' 
improt {updateUser} from './api'
const modalRef = ref();
const apiConfog = {
    success(data){
      modalRef.value?.close()
      return data
    }
  }
})
</script>

使用 useFormModal Hook

<template> 
	<FormModal />
	<button @click="openEditModal">编辑</button> 
</template>
<script setup lang="ts"> 
import { useFormModal } from '@aoao-y33/ui' 
improt {updateUser} from './api'
const [FormModal, modalApi] = useFormModal({ 
  title: '编辑用户', 
  api:updateUser,
  fieldConfig: { 
    fields: [ 
      { label: "用户名", fieldName: "username", type: "input", vtypes: ['required'] }, 
      { label: "邮箱", fieldName: "email", type: "input", vtypes: ['required', 'mail'] } ] 
  }, 
  onConfrim:(data:any)=>{
    modalApi.load(data)
  },
  apiConfig:{
    success(data){
      modalApi.close()
      return data
    }
  }
})
</script>

API

useFormModal 返回值

| 属性 | 类型 | 说明 | | ---------- | ----------- | ---------------- | | FormModal | Component | 表单弹窗组件 | | open | Function | 打开弹窗 | | close | Function | 关闭弹窗 | | setModal | StateApi | 更新弹窗属性 | | buttonsApi | FieldsApi | 按钮管理 API | | fieldsApi | FieldsApi | 表单字段管理 API |

formApi方法

requestApi 方法

modalApi 方法

6. Layout 布局组件

灵活的布局组件，支持自定义布局方案。

文件位置

使用ax-layout组件

<template> 
  <AxLayout :type="type"> 
     <template #header> 
        <div>头部内容</div> 
    </template> 
    <template #aside> 
      <div>侧边栏内容</div> 
    </template> 
    <template #main> 
    	<div>主要内容</div> 
    </template> 
    <template #footer> 
    	<div>底部</div> 
    </template>
  </AxLayout> 
	<button @click="setLayout('side')">切换布局</button>
</template>
<script setup lang="ts"> 
import { AxLayout } from '@aoao-y33/ui' 
const type = ref("basic");
const setLayout = (_type:string)=>{
  type.value = _type
}
</script>

使用useLayout Hook

<template> 
	<Layout/>
	<button @click="setLayout({type:'side'})">切换布局</button>
</template>
<script setup lang="ts"> 
import { useLayout } from '@aoao-y33/ui' 
const [Layout,setLayout] = useLayout({
  type:"basice",
  header:()=>h("div","头部")
  aside:()=>h("div","侧边栏内容")
 	main:()=>h("div","主要内容")
  footer:()=>h("div","底部")
})
</script>

注册自定义布局

import { addLayoutField } from '@aoao-y33/ui' 
import SidebarLayout from './SidebarLayout.vue'
addLayoutField('sidebar', SidebarLayout)

API

AxLayout Props

| 属性 | 类型 | 默认值 | 说明 | | ---- | -------------------- | ------- | -------- | | type | keyof layoutFields | 'basic' | 布局类型 |

插槽

| 插槽名 | 说明 | | ------ | ------------ | | header | 头部区域 | | aside | 侧边栏区域 | | main | 主要内容区域 | | footer | 底部区域 |

🎨 工具函数

图标工具

// 获取 Element Plus 图标 
const SearchIcon = getIcons('Search')

API

getIcons(icon: string)

| 参数 | 类型 | 说明 | | ------ | ------------------------ | ------------------------------ | | icon | string | 图标名称（Element Plus Icons） | | 返回值 | Component \| undefined | 图标组件 |

组件注册工具

import { addButtonField, addFormField, addFormRules, addTableColumnField, addLayoutField } from '@aoao-y33/ui'
// 注册各类自定义组件 
addButtonField('custom', CustomButtonComponent) 
addFormField('custom-input', CustomInputComponent) 
addFormRules('custom-rule', customRuleFunction) 
addTableColumnField('custom-column', CustomColumnComponent) 
addLayoutField('custom-layout', CustomLayoutComponent)

API

addButtonField(type: string, component: Component)

注册自定义按钮类型

addFormField(type: string, component: Component)

注册自定义表单字段组件

addFormRules(type: string, rule: VFormItemRule)

注册自定义表单验证规则

addTableColumnField(type: string, component: Component)

注册自定义表格列组件

addLayoutField(type: string, component: Component)

注册自定义布局组件

📖 完整 API 参考

导出组件

按钮组件

AxButton - 按钮组件
useButton - 按钮 Hook

表单组件

AxForm - 表单组件
AxFormItem - 表单项组件
useForm - 表单 Hook
useFormExpose - 表单暴露 API
useFormFetch - 表单请求 Hook

表格组件

AxTable - 表格组件
AxTableColumn - 表格列组件
AxTablePage - 分页组件
AxTableSelect - 搜索选择组件
useTable - 表格 Hook
useTableExpose - 表格暴露 API

弹窗组件

AxModal - 弹窗组件
AxFormModal - 表单弹窗组件
useModal - 弹窗 Hook
useFormModal - 表单弹窗 Hook
useModalExpose - 弹窗暴露 API

布局组件

AxLayout - 布局组件
useLayout - 布局 Hook

工具函数

getIcons - 获取图标组件
addButtonField - 注册按钮类型
addFormField - 注册表单字段
addFormRules - 注册表单规则
addTableColumnField - 注册表格列
addLayoutField - 注册布局类型

类型导出

Button 类型

AxButtonProps - 按钮属性类型
AxButtonEmits - 按钮事件类型
AxButtonOptions - 按钮配置类型

Form 类型

AxFormProps - 表单属性类型
AxFormOptions - 表单配置类型
AxFormItemProps - 表单项属性类型
AxFormItemOptions - 表单项配置类型
FormApi - 表单 API 类型
FormFetchApi - 表单请求 API 类型
VFormItemRule - 表单验证规则类型

Table 类型

AxTableProps - 表格属性类型
AxTableOptions - 表格配置类型
AxTableColumnsProps - 表格列属性类型
AxTablePageProps - 分页属性类型
AxTableSelectProps - 搜索选择属性类型

Modal 类型

AxModalProps - 弹窗属性类型
AxModalOptions - 弹窗配置类型
AxFormModalProps - 表单弹窗属性类型
AxFormModalOptions - 表单弹窗配置类型
ModalApi - 弹窗 API 类型

其他类型

StateApi - 状态管理 API 类型
FieldsApi - 字段管理 API 类型

🎨 主题定制

CSS 变量

组件库提供了以下 CSS 变量用于主题定制：

root { 
  --ax-bg-color: #F5F5F5; 
  --ax-block-color: #FFFFFF;
  --ax-border-color: #E7E7E7; 
  --ax-small-radius: 4px; 
  --ax-normal-radius: 10px; 
  --el-fill-color-lighter: #EEF1F5; 
  --el-fill-color-blank: #fff; 
}
:root.dark { 
  --ax-bg-color: #14161A; 
  --ax-block-color: #1C1E23; 
  --ax-border-color: #1C1E23;
  --el-fill-color-lighter: #313740; 
  --el-fill-color-blank: #191E27; 
}

深色模式

组件库内置深色模式支持，通过给根元素添加 dark 类来启用：

<html class="dark"> <!-- 深色模式 --> </html>

🔗 相关项目

@aoao-y33/hooks - Hooks 工具库
@aoao-y33/utils - 通用工具函数

📄 许可证

MIT License

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@aoao-y33/ui

✨ 特性

📦 安装

🚀 快速开始

按需引入

样式引入

📖 组件文档

1. Button 按钮组件

基础用法

带图标按钮

动态控制显示/隐藏

注册自定义按钮类型

API

AxButtonProps

事件

2. Form 表单组件

使用 ax-form组件

使用 useForm Hook

表单验证规则

API

useForm 返回值

formApi方法

requestApi 方法

3. Table 表格组件

使用 ax-table组件

使用 useTable Hook

注册自定义列类型

API

useTable 返回值

tableApi 方法

4. Modal 弹窗组件

使用ax-modal组件

使用 useModal Hook

API

useModal 返回值

ModalApi 方法

5. FormModal 表单弹窗组件

使用ax-form-modal组件

使用 useFormModal Hook

API

useFormModal 返回值

formApi方法

6. Layout 布局组件

文件位置

使用ax-layout组件

使用useLayout Hook

注册自定义布局

API

AxLayout Props

插槽

🎨 工具函数

图标工具

API

getIcons(icon: string)

组件注册工具

API

addButtonField(type: string, component: Component)

addFormField(type: string, component: Component)

addFormRules(type: string, rule: VFormItemRule)

addTableColumnField(type: string, component: Component)

addLayoutField(type: string, component: Component)

📖 完整 API 参考

导出组件

按钮组件

表单组件

表格组件

弹窗组件

布局组件

工具函数

类型导出

Button 类型

Form 类型

Table 类型

Modal 类型