@aoao-y33/ui 0.0.2

package/README.md

@@ -0,0 +1,811 @@
+# @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
+bash npm install @aoao-y33/ui
+或
+pnpm add @aoao-y33/ui
+或
+yarn add @aoao-y33/ui
+````
+
+
+
+## 🚀 快速开始
+
+### 全局引入
+
+````typescript
+import { createApp } from 'vue' 
+import AoaoUI from '@aoao-y33/ui' 
+import App from './App.vue'
+const app = createApp(App) 
+app.use(AoaoUI) 
+app.mount('#app')
+````
+
+### 按需引入
+
+```typescript
+import { AxButton, useForm, useTable, useModal } from '@aoao-y33/ui'
+```
+
+### 样式引入
+
+组件库默认会自动引入样式，如果需要单独引入：
+
+```typescript
+import '@aoao-y33/ui/dist/index.css'
+```
+
+## 📖 组件文档
+
+### 1. Button 按钮组件
+
+基础按钮组件，支持多种类型和自定义配置。
+
+#### 基础用法
+
+```vue
+<template> 
+	<AxButton text="点击我" type="primary" @click="handleClick" /> </template>
+<script setup lang="ts"> 
+import { AxButton } from '@aoao-y33/ui' 
+const handleClick = () => { 
+  console.log('按钮被点击') 
+} 
+</script>
+```
+
+#### 带图标按钮
+
+```vue
+<template> 
+	<AxButton text="搜索" type="primary" icon="Search" @click="handleSearch" /> 
+</template>
+```
+
+#### 动态控制显示/隐藏
+
+````vue
+<template> 
+	<AxButton text="编辑" :hidden="(data) => !data.canEdit" :disabled="(data) => data.isLocked" /> 
+</template>
+````
+
+#### 注册自定义按钮类型
+
+```typescript
+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组件
+
+```vue
+<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
+
+```vue
+<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`: 邮箱
+
+```typescript
+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组件
+
+```vue
+<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
+
+```vue
+<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>
+```
+
+#### 注册自定义列类型
+
+```typescript
+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组件
+
+```vue
+<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
+
+```vue
+<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组件
+
+```vue
+<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
+
+```vue
+<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组件
+
+```vue
+<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
+
+```vue
+<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>
+```
+
+#### 注册自定义布局
+
+```typescript
+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 | 底部区域     |
+
+---
+
+## 🎨 工具函数
+
+### 图标工具
+
+```typescript
+// 获取 Element Plus 图标 
+const SearchIcon = getIcons('Search')
+```
+
+#### API
+
+##### getIcons(icon: string)
+
+| 参数   | 类型                     | 说明                           |
+| ------ | ------------------------ | ------------------------------ |
+| icon   | `string`                 | 图标名称（Element Plus Icons） |
+| 返回值 | `Component \| undefined` | 图标组件                       |
+
+### 组件注册工具
+
+```typescript
+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 变量用于主题定制：
+
+```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
+<html class="dark"> <!-- 深色模式 --> </html>
+```
+
+---
+
+## 🔗 相关项目
+
+- [@aoao-y33/hooks](../hooks/README.md) - Hooks 工具库
+- [@aoao-y33/utils](../utils/README.md) - 通用工具函数
+
+## 📄 许可证
+
+MIT License