knt-shared 1.0.0 → 1.1.0

package/README.md

@@ -1,259 +1,514 @@
 # knt-shared
 
-KNT共享组件库和工具函数（基于 Vue3 + @arco-design/web-vue）
+KNT 共享组件库和工具函数（基于 Vue3 + @arco-design/web-vue）
 
 参考 [Vben Admin](https://doc.vvbin.cn/components/introduction.html) 的设计思路实现
 
-## 安装
+## ✨ 特性
+
+- 🎨 **二次封装** - 基于 Arco Design Vue 进行二次封装，提供更便捷的使用方式
+- 📦 **开箱即用** - 高质量的 Vue3 组件，简单配置即可使用
+- 🔧 **函数式调用** - 支持通过 Hooks 进行组件注册和控制
+- 🎯 **TypeScript** - 完整的 TypeScript 类型支持
+- 🔄 **动态配置** - 支持动态修改组件属性和数据
+- 📱 **响应式** - 完整的响应式布局支持
+
+## 📦 安装
 
 ```bash
 npm install knt-shared
+# 或
+pnpm install knt-shared
+# 或
+yarn add knt-shared
+```
+
+## 🔨 依赖要求
+
+```json
+{
+  "vue": "^3.4.0",
+  "@arco-design/web-vue": "^2.50.0"
+}
 ```
 
-## 使用
+## 📚 组件列表
 
 ### Description 详情组件
 
+用于展示详细信息的组件，支持自定义渲染、动态控制字段显示等功能。
+
+**基础使用：**
+
 ```vue
 <template>
-  <Description
+  <BasicDescription
     title="用户信息"
-    :items="descriptionItems"
     :column="3"
-    bordered
+    :data="userData"
+    :schema="schema"
   />
 </template>
 
 <script setup lang="ts">
-import { Description } from 'knt-shared';
-import type { DescriptionItem } from 'knt-shared';
-
-const descriptionItems: DescriptionItem[] = [
-  { label: '姓名', value: '张三' },
-  { label: '年龄', value: 28 },
-  { label: '邮箱', value: 'zhangsan@example.com' },
-  { label: '地址', value: '北京市朝阳区', span: 2 },
+import { BasicDescription } from 'knt-shared';
+import type { DescItem } from 'knt-shared';
+
+const userData = {
+  username: 'zhangsan',
+  nickName: '张三',
+  age: 25,
+  email: 'zhangsan@example.com',
+};
+
+const schema: DescItem[] = [
+  { field: 'username', label: '用户名' },
+  { field: 'nickName', label: '昵称' },
+  { field: 'age', label: '年龄' },
+  { field: 'email', label: '邮箱' },
 ];
 </script>
 ```
 
-### Form 表单组件
+**使用 Hook：**
 
 ```vue
 <template>
-  <Form
-    ref="formRef"
-    :model="formData"
-    :rules="rules"
-    @submit="handleSubmit"
-  >
-    <a-form-item field="name" label="姓名">
-      <a-input v-model="formData.name" placeholder="请输入姓名" />
-    </a-form-item>
-    <a-form-item field="email" label="邮箱">
-      <a-input v-model="formData.email" placeholder="请输入邮箱" />
-    </a-form-item>
-    <a-form-item>
-      <a-button type="primary" html-type="submit">提交</a-button>
-      <a-button @click="handleReset">重置</a-button>
-    </a-form-item>
-  </Form>
+  <BasicDescription @register="register" />
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue';
-import { Form } from 'knt-shared';
-
-const formRef = ref();
-const formData = ref({
-  name: '',
-  email: '',
+import { BasicDescription, useDescription } from 'knt-shared';
+
+const [register, { setDescriptionProps }] = useDescription({
+  title: '用户信息',
+  column: 3,
+  data: { username: 'zhangsan', nickName: '张三' },
+  schema: [
+    { field: 'username', label: '用户名' },
+    { field: 'nickName', label: '昵称' },
+  ],
 });
+</script>
+```
 
-const rules = {
-  name: [{ required: true, message: '请输入姓名' }],
-  email: [
-    { required: true, message: '请输入邮箱' },
-    { type: 'email', message: '邮箱格式不正确' },
-  ],
-};
+### Form 表单组件
+
+动态表单组件，支持 schema 配置、自动组件映射、动态控制等功能。
+
+**基础使用：**
+
+```vue
+<template>
+  <BasicForm
+    :schemas="formSchemas"
+    :labelCol="{ span: 6 }"
+    :wrapperCol="{ span: 18 }"
+    @submit="handleSubmit"
+  />
+</template>
+
+<script setup lang="ts">
+import { BasicForm } from 'knt-shared';
+import type { FormSchema } from 'knt-shared';
+
+const formSchemas: FormSchema[] = [
+  {
+    field: 'name',
+    label: '姓名',
+    component: 'Input',
+    required: true,
+  },
+  {
+    field: 'email',
+    label: '邮箱',
+    component: 'Input',
+    required: true,
+    rules: [{ type: 'email', message: '邮箱格式不正确' }],
+  },
+  {
+    field: 'age',
+    label: '年龄',
+    component: 'InputNumber',
+  },
+];
 
 const handleSubmit = (values: Record<string, any>) => {
   console.log('提交数据:', values);
 };
+</script>
+```
 
-const handleReset = () => {
-  formRef.value?.resetFields();
+**使用 Hook：**
+
+```vue
+<template>
+  <BasicForm @register="register" />
+</template>
+
+<script setup lang="ts">
+import { BasicForm, useForm } from 'knt-shared';
+
+const [register, { setFieldsValue, validate }] = useForm({
+  schemas: formSchemas,
+});
+
+// 设置表单值
+const setValues = () => {
+  setFieldsValue({ name: '张三', age: 25 });
+};
+
+// 验证表单
+const submit = async () => {
+  const values = await validate();
+  console.log(values);
 };
 </script>
 ```
 
 ### Table 表格组件
 
+高级表格组件，支持自动请求数据、搜索表单、操作列、自定义渲染等功能。
+
+**基础使用：**
+
 ```vue
 <template>
-  <Table
-    ref="tableRef"
+  <BasicTable
     :columns="columns"
-    :data="tableData"
-    :loading="loading"
+    :dataSource="tableData"
     :pagination="{ pageSize: 10 }"
-    @page-change="handlePageChange"
   />
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue';
-import { Table } from 'knt-shared';
-import type { TableColumnData } from '@arco-design/web-vue';
+import { BasicTable } from 'knt-shared';
+import type { BasicColumn } from 'knt-shared';
 
-const tableRef = ref();
-const loading = ref(false);
-const tableData = ref([
+const columns: BasicColumn[] = [
+  { title: '姓名', dataIndex: 'name' },
+  { title: '年龄', dataIndex: 'age' },
+  { title: '邮箱', dataIndex: 'email' },
+];
+
+const tableData = [
   { id: 1, name: '张三', age: 25, email: 'zhangsan@example.com' },
   { id: 2, name: '李四', age: 30, email: 'lisi@example.com' },
-]);
+];
+</script>
+```
+
+**使用 request 自动加载数据：**
 
-const columns: TableColumnData[] = [
+```vue
+<template>
+  <BasicTable
+    :columns="columns"
+    :request="loadData"
+    :searchFormConfig="{ schemas: searchSchemas }"
+  />
+</template>
+
+<script setup lang="ts">
+import { BasicTable } from 'knt-shared';
+
+const columns = [
   { title: '姓名', dataIndex: 'name' },
   { title: '年龄', dataIndex: 'age' },
-  { title: '邮箱', dataIndex: 'email' },
 ];
 
-const handlePageChange = (page: number) => {
-  console.log('页码变化:', page);
-  // 加载数据
+const searchSchemas = [
+  { field: 'name', label: '姓名', component: 'Input' },
+];
+
+const loadData = async (params: any) => {
+  const response = await fetchData(params);
+  return {
+    data: response.list,
+    total: response.total,
+  };
 };
+</script>
+```
 
-// 使用 request 属性自动加载数据
-const tableWithRequest = {
+**使用 Hook：**
+
+```vue
+<template>
+  <BasicTable @register="register" />
+</template>
+
+<script setup lang="ts">
+import { BasicTable, useTable } from 'knt-shared';
+
+const [register, { reload, setTableData }] = useTable({
   columns,
-  request: async (params: Record<string, any>) => {
-    // 调用 API
-    const response = await fetchData(params);
-    return {
-      data: response.list,
-      total: response.total,
-    };
-  },
+  request: loadData,
+});
+
+// 重新加载数据
+const refresh = () => {
+  reload();
 };
 </script>
 ```
 
 ### Modal 模态框组件
 
+模态框组件，支持拖拽、全屏、异步操作、数据传递等功能。
+
+**基础使用：**
+
 ```vue
 <template>
   <div>
-    <a-button @click="openModal">打开模态框</a-button>
-    <Modal
-      v-model:visible="visible"
-      title="编辑信息"
-      @ok="handleOk"
-      @cancel="handleCancel"
-    >
-      <a-form :model="formData">
-        <a-form-item label="姓名">
-          <a-input v-model="formData.name" />
-        </a-form-item>
-      </a-form>
-    </Modal>
+    <a-button @click="openModal(true)">打开模态框</a-button>
+    <MyModal @register="register" />
   </div>
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue';
-import { Modal } from 'knt-shared';
+import { useModal } from 'knt-shared';
+import MyModal from './MyModal.vue';
 
-const visible = ref(false);
-const formData = ref({ name: '' });
+const [register, { openModal }] = useModal();
+</script>
+```
 
-const openModal = () => {
-  visible.value = true;
-};
+**模态框组件定义：**
 
-const handleOk = () => {
-  console.log('确定', formData.value);
-  visible.value = false;
-};
+```vue
+<!-- MyModal.vue -->
+<template>
+  <BasicModal v-bind="$attrs" title="编辑信息" @ok="handleOk">
+    <a-form :model="formData">
+      <a-form-item label="姓名">
+        <a-input v-model="formData.name" />
+      </a-form-item>
+    </a-form>
+  </BasicModal>
+</template>
 
-const handleCancel = () => {
-  console.log('取消');
-};
+<script setup lang="ts">
+import { BasicModal, useModalInner } from 'knt-shared';
+import { reactive } from 'vue';
+
+const formData = reactive({ name: '' });
+
+const [register, { closeModal, changeOkLoading }] = useModalInner((data) => {
+  // 接收传递的数据
+  if (data) {
+    formData.name = data.name;
+  }
+});
 
-// 使用 ref 控制模态框
-const modalRef = ref();
-modalRef.value?.open(); // 打开
-modalRef.value?.close(); // 关闭
+const handleOk = async () => {
+  changeOkLoading(true);
+  try {
+    // 异步操作
+    await saveData(formData);
+    closeModal();
+  } finally {
+    changeOkLoading(false);
+  }
+};
 </script>
 ```
 
-### 工具函数
+**传递数据：**
+
+```typescript
+// 打开模态框并传递数据
+const [register, { openModal }] = useModal();
+openModal(true, { name: '张三' });
+```
 
-```ts
-import { formatDate, formatNumber, isValidEmail } from 'knt-shared';
+## 🔧 工具函数
 
-// 格式化日期
-const dateStr = formatDate(new Date(), 'YYYY-MM-DD');
+### 验证工具
 
-// 格式化数字
-const numStr = formatNumber(1234567); // "1,234,567"
+```typescript
+import { isValidEmail, isValidPhone, isValidUrl, isValidIdCard } from 'knt-shared';
 
 // 验证邮箱
-const isValid = isValidEmail('test@example.com');
+isValidEmail('test@example.com'); // true
+
+// 验证手机号（中国大陆）
+isValidPhone('13800138000'); // true
+
+// 验证 URL
+isValidUrl('https://example.com'); // true
+
+// 验证身份证号（中国大陆18位）
+isValidIdCard('110101199001011234'); // true
 ```
 
-### Hooks (Composition API)
+### 防抖工具
+
+```typescript
+import { debounce } from 'knt-shared';
+
+// 创建防抖函数
+const debouncedFn = debounce((value: string) => {
+  console.log('搜索:', value);
+}, 300);
+
+// 使用
+debouncedFn('关键词');
+```
+
+## 🪝 Hooks (Composition API)
+
+### useDebounce - 防抖
 
 ```vue
 <template>
   <div>
-    <input v-model="inputValue" />
-    <p>防抖值: {{ debouncedValue }}</p>
+    <a-input v-model="inputValue" placeholder="输入搜索关键词" />
+    <p>防抖后的值: {{ debouncedValue }}</p>
   </div>
 </template>
 
 <script setup lang="ts">
 import { ref } from 'vue';
-import { useDebounce, useLocalStorage, useToggle } from 'knt-shared';
+import { useDebounce } from 'knt-shared';
 
 const inputValue = ref('');
 const debouncedValue = useDebounce(inputValue, 500);
+</script>
+```
+
+### useToggle - 布尔值切换
+
+```vue
+<template>
+  <div>
+    <p>状态: {{ isOpen }}</p>
+    <a-button @click="toggle">切换</a-button>
+    <a-button @click="setTrue">打开</a-button>
+    <a-button @click="setFalse">关闭</a-button>
+  </div>
+</template>
 
-const [stored, setStored] = useLocalStorage('key', 'default');
+<script setup lang="ts">
+import { useToggle } from 'knt-shared';
 
-const [isOpen, toggle, open, close] = useToggle(false);
+const [isOpen, toggle, setTrue, setFalse] = useToggle(false);
 </script>
 ```
 
-## 开发
+### useLocalStorage - 本地存储
+
+```vue
+<script setup lang="ts">
+import { useLocalStorage } from 'knt-shared';
+
+const [stored, setStored] = useLocalStorage('myKey', 'defaultValue');
+
+// 读取值
+console.log(stored.value);
+
+// 设置值
+setStored('newValue');
+</script>
+```
+
+### 组件 Hooks
+
+- **useForm** - 表单控制
+- **useTable** - 表格控制
+- **useModal** - 模态框外部控制
+- **useModalInner** - 模态框内部控制
+- **useDescription** - 详情组件控制
+
+## 🛠️ 开发
+
+### 安装依赖
 
 ```bash
-# 安装依赖
-npm install
+pnpm install
+```
+
+### 构建
 
-# 构建
-npm run build
+```bash
+# 构建库
+pnpm run build
 
 # 开发模式（监听文件变化）
-npm run dev
+pnpm run dev
 ```
 
-## Playground 测试环境
-
-项目包含一个 playground 目录，用于测试和演示组件：
+### 发布
 
 ```bash
-cd playground
-npm install
-npm run dev
+pnpm run prepublishOnly
+pnpm publish
 ```
 
-访问 http://localhost:3000 查看所有组件的测试和演示。
+## 🎮 Playground 测试环境
 
-## 发布
+项目包含一个 `playground` 目录，用于测试和演示所有组件：
 
 ```bash
-npm publish
+cd playground
+pnpm install
+pnpm run dev
 ```
 
+访问 http://localhost:5173 查看所有组件的测试和演示。
+
+### Playground 包含的示例
+
+**Description 组件：**
+- 基础示例
+- 自定义渲染
+- 动态控制
+
+**Form 组件：**
+- 基础表单
+- 使用 Hook 配置
+- 性能测试
+
+**Table 组件：**
+- 基础表格
+- 搜索表格
+- 操作列
+- 自定义渲染
+- 使用 Hook
+
+**Modal 组件：**
+- 基础弹窗
+- 数据传递
+- 异步操作
+- 自定义底部
+- Loading 状态
+- 内部控制
+
+## 📖 文档
+
+每个组件都包含详细的文档：
+
+- **Description**: `src/components/Description/README.md`
+- **Form**: `src/components/Form/修复总结.md`
+- **Table**: `src/components/Table/TABLE.md`
+- **Modal**: `src/components/Modal/MODAL.md`
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 License
+
+MIT
+
+## 👨‍💻 作者
+
+hss
+
+## 🔗 相关链接
+
+- [GitHub Repository](https://github.com/Noah-Neverland/knt-shard)
+- [Arco Design Vue](https://arco.design/vue)
+- [Vben Admin](https://doc.vvbin.cn/components/introduction.html)
+