sohelp-eleplus 1.1.27 → 1.1.28

package/sohelp-user-modal-select/README.md

@@ -0,0 +1,739 @@
+# SohelpUserModalSelect 用户选择器
+
+基于 `sohelp-modal-select` 封装的用户选择组件，预置了用户列表接口和列配置，支持单选/多选用户。开箱即用，无需手动配置表格列。
+
+## ✨ 特性
+
+- 🎯 **开箱即用** - 预置用户接口和列配置
+- 🔍 **内置搜索** - 支持用户名、登录名、昵称搜索
+- 📊 **分页加载** - 默认每页 5 条数据
+- 🎨 **灵活显示** - 默认显示格式：`${user_name}-${login_name}`
+- ⚙️ **可自定义** - 支持覆盖默认接口和列配置
+- 🔄 **双向绑定** - 完整的 v-model 和 v-model:data 支持
+- 🪝 **钩子函数** - 支持 beforeOpen、confirm 等回调
+
+## 📖 基础用法
+
+### 多选用户
+
+```vue
+<template>
+  <sohelp-user-modal-select
+    v-model="selectedUserIds"
+    v-model:data="selectedUserData"
+    multiple
+    placeholder="请选择用户"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedUserIds = ref([]);
+const selectedUserData = ref([]);
+</script>
+```
+
+### 单选用户
+
+```vue
+<template>
+  <sohelp-user-modal-select
+    v-model="selectedUserId"
+    v-model:data="selectedUserData"
+    :multiple="false"
+    placeholder="请选择用户"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedUserId = ref('');
+const selectedUserData = ref({});
+</script>
+```
+
+### 自定义弹窗标题和宽度
+
+```vue
+<template>
+  <sohelp-user-modal-select
+    v-model="selectedUserIds"
+    v-model:data="selectedUserData"
+    :modalProps="{
+      title: '选择审批人',
+      width: '900px',
+      minHeight: 600
+    }"
+    placeholder="请选择审批人"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedUserIds = ref([]);
+const selectedUserData = ref([]);
+</script>
+```
+
+### 自定义显示格式
+
+```vue
+<template>
+  <sohelp-user-modal-select
+    v-model="selectedUserIds"
+    v-model:data="selectedUserData"
+    selectionTemplate="${user_name} (${nickname})"
+    placeholder="请选择用户"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedUserIds = ref([]);
+const selectedUserData = ref([]);
+</script>
+```
+
+### 自定义字段
+
+```vue
+<template>
+  <sohelp-user-modal-select
+    v-model="selectedUserIds"
+    v-model:data="selectedUserData"
+    :labelField="nickname"
+    :valueField="user_id"
+    selectionTemplate="${nickname}"
+    placeholder="请选择用户"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedUserIds = ref([]);
+const selectedUserData = ref([]);
+</script>
+```
+
+### 覆盖默认接口和列配置
+
+```vue
+<template>
+  <sohelp-user-modal-select
+    v-model="selectedUserIds"
+    v-model:data="selectedUserData"
+    :gridProps="{
+      url: '/api/custom/user/page',
+      gridOptions: {
+        columns: [
+          { field: 'user_name', title: '姓名', width: 150 },
+          { field: 'login_name', title: '登录名', width: 180 },
+          { field: 'nickname', title: '昵称', width: 150 },
+          { field: 'email', title: '邮箱', width: 200 },
+          { field: 'phone', title: '手机号', width: 150 }
+        ],
+        pagerConfig: {
+          pageSize: 10
+        }
+      }
+    }"
+    placeholder="请选择用户"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedUserIds = ref([]);
+const selectedUserData = ref([]);
+</script>
+```
+
+### 使用钩子函数
+
+```vue
+<template>
+  <sohelp-user-modal-select
+    v-model="selectedUserIds"
+    v-model:data="selectedUserData"
+    :beforeOpen="handleBeforeOpen"
+    @confirm="handleConfirm"
+    placeholder="请选择用户"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { ElMessage } from 'element-plus';
+
+const selectedUserIds = ref([]);
+const selectedUserData = ref([]);
+
+// 打开前钩子
+const handleBeforeOpen = (modelValue, data) => {
+  console.log('当前选中用户:', data);
+  // 可以在这里做一些校验或数据预处理
+  return true;
+};
+
+// 确认事件
+const handleConfirm = (selectedIds, selectedData) => {
+  ElMessage.success(`已选择 ${selectedIds.length} 个用户`);
+  console.log('选中的用户:', selectedData);
+};
+</script>
+```
+
+### 表单验证场景
+
+```vue
+<template>
+  <el-form :model="form" :rules="rules" ref="formRef">
+    <el-form-item label="审批人" prop="approverIds">
+      <sohelp-user-modal-select
+        v-model="form.approverIds"
+        v-model:data="form.approverData"
+        :modalProps="{ title: '选择审批人' }"
+        placeholder="请选择审批人"
+      />
+    </el-form-item>
+    
+    <el-form-item label="抄送人" prop="ccIds">
+      <sohelp-user-modal-select
+        v-model="form.ccIds"
+        v-model:data="form.ccData"
+        multiple
+        placeholder="请选择抄送人"
+      />
+    </el-form-item>
+    
+    <el-form-item>
+      <el-button type="primary" @click="submitForm">提交</el-button>
+    </el-form-item>
+  </el-form>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const formRef = ref(null);
+const form = ref({
+  approverIds: '',
+  approverData: {},
+  ccIds: [],
+  ccData: []
+});
+
+const rules = {
+  approverIds: [
+    { required: true, message: '请选择审批人', trigger: 'change' }
+  ],
+  ccIds: [
+    { type: 'array', required: true, message: '请选择抄送人', trigger: 'change' }
+  ]
+};
+
+const submitForm = async () => {
+  await formRef.value?.validate();
+  console.log('提交表单:', form.value);
+};
+</script>
+```
+
+### 数据回显场景
+
+```vue
+<template>
+  <sohelp-user-modal-select
+    v-model="form.approverIds"
+    v-model:data="form.approverData"
+    placeholder="请选择审批人"
+  />
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue';
+
+const form = ref({
+  approverIds: '',
+  approverData: {}
+});
+
+// 模拟从后端加载数据
+onMounted(async () => {
+  const response = await fetch('/api/approval/detail');
+  const data = await response.json();
+  
+  form.value.approverIds = data.approverId;
+  form.value.approverData = {
+    id: data.approverId,
+    user_name: data.approverName,
+    login_name: data.approverLoginName
+  };
+  
+  // 组件会自动回显
+});
+</script>
+```
+
+### 禁用/只读状态
+
+```vue
+<template>
+  <div>
+    <!-- 禁用 -->
+    <sohelp-user-modal-select
+      v-model="selectedUserIds"
+      v-model:data="selectedUserData"
+      disabled
+      placeholder="禁用状态"
+    />
+    
+    <!-- 只读 -->
+    <sohelp-user-modal-select
+      v-model="selectedUserIds"
+      v-model:data="selectedUserData"
+      readonly
+      placeholder="只读状态"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedUserIds = ref([]);
+const selectedUserData = ref([]);
+</script>
+```
+
+### 动态过滤用户
+
+```vue
+<template>
+  <div>
+    <el-select v-model="deptId" placeholder="请选择部门" style="width: 200px; margin-right: 10px;">
+      <el-option label="全部" value="" />
+      <el-option label="技术部" value="1" />
+      <el-option label="市场部" value="2" />
+      <el-option label="销售部" value="3" />
+    </el-select>
+    
+    <sohelp-user-modal-select
+      v-model="selectedUserIds"
+      v-model:data="selectedUserData"
+      :gridProps="dynamicGridProps"
+      placeholder="请选择用户"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref, computed } from 'vue';
+
+const deptId = ref('');
+const selectedUserIds = ref([]);
+const selectedUserData = ref([]);
+
+const dynamicGridProps = computed(() => ({
+  url: deptId.value ? `/api/user/page?deptId=${deptId.value}` : '/admin/system/user/page',
+  gridOptions: {
+    columns: [
+      { field: 'user_name', title: '姓名', width: 120 },
+      { field: 'login_name', title: '登录名', width: 180 },
+      { field: 'nickname', title: '昵称', width: 120 }
+    ]
+  }
+}));
+</script>
+```
+
+### 清空选中
+
+```vue
+<template>
+  <div>
+    <sohelp-user-modal-select
+      ref="userSelectRef"
+      v-model="selectedUserIds"
+      v-model:data="selectedUserData"
+      placeholder="请选择用户"
+    />
+    
+    <el-button @click="clearSelection">清空选中</el-button>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const userSelectRef = ref(null);
+const selectedUserIds = ref([]);
+const selectedUserData = ref([]);
+
+const clearSelection = () => {
+  userSelectRef.value?.clearAll();
+};
+</script>
+```
+
+## 📋 属性 (Props)
+
+| 属性名 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| modelValue (v-model) | String / Array | - | 否 | 选中用户的 ID 值 |
+| data (v-model:data) | Array / Object | - | 否 | 选中用户的完整数据 |
+| valueField | String | `'id'` | 否 | 值字段名 |
+| labelField | String | `'user_name'` | 否 | 显示字段名 |
+| multiple | Boolean | `true` | 否 | 是否多选 |
+| selectionTemplate | String | `'${user_name}-${login_name}'` | 否 | 已选列表的显示模板 |
+| modalProps | Object | `{}` | 否 | 传递给弹窗的属性配置 |
+| gridProps | Object | `{}` | 否 | 传递给表格的属性配置 |
+
+### 默认配置
+
+```javascript
+// 默认接口
+url: '/admin/system/user/page'
+
+// 默认列配置
+columns: [
+  { field: 'user_name', title: '用户姓名', width: 120 },
+  { field: 'login_name', title: '登录账户', width: 200 },
+  { field: 'nickname', title: '昵称', width: 120 }
+]
+
+// 默认分页
+pageSize: 5
+
+// 默认弹窗
+title: '选择用户'
+width: 800
+
+// 默认字段
+valueField: 'id'
+labelField: 'user_name'
+selectionTemplate: '${user_name}-${login_name}'
+```
+
+## 🔄 双向绑定 (v-model)
+
+| 属性名 | 类型 | 说明 |
+| --- | --- | --- |
+| modelValue | String / Array | 选中用户的 ID 值，多选时为数组，单选时为字符串 |
+| data | Array / Object | 选中用户的完整数据对象，多选时为数组，单选时为对象 |
+
+## 🎯 事件 (Events)
+
+| 事件名 | 回调参数 | 说明 |
+| --- | --- | --- |
+| update:modelValue | `(selectedIds)` | 选中值变化时触发 |
+| confirm | `(selectedIds, selectedData)` | 点击确认后触发 |
+| page-change | `(pageInfo)` | 分页变化时触发 |
+
+## 🔧 方法 (Methods)
+
+通过 `ref` 可以调用以下方法：
+
+| 方法名 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| clearAll | - | - | 清空所有选中数据 |
+
+## 📝 数据结构
+
+### 选中数据对象（单选）
+
+```javascript
+{
+  id: '1',
+  user_name: '张三',
+  login_name: 'zhangsan',
+  nickname: '张三'
+}
+```
+
+### 选中数据数组（多选）
+
+```javascript
+[
+  {
+    id: '1',
+    user_name: '张三',
+    login_name: 'zhangsan',
+    nickname: '张三'
+  },
+  {
+    id: '2',
+    user_name: '李四',
+    login_name: 'lisi',
+    nickname: '李四'
+  }
+]
+```
+
+## 🎯 最佳实践
+
+### 1. 审批流程场景
+
+```vue
+<template>
+  <el-form :model="form">
+    <el-form-item label="申请人">
+      <el-input v-model="form.applicantName" disabled />
+    </el-form-item>
+    
+    <el-form-item label="审批人">
+      <sohelp-user-modal-select
+        v-model="form.approverId"
+        v-model:data="form.approverData"
+        :multiple="false"
+        :modalProps="{ title: '选择审批人' }"
+        placeholder="请选择审批人"
+      />
+    </el-form-item>
+    
+    <el-form-item label="抄送人">
+      <sohelp-user-modal-select
+        v-model="form.ccIds"
+        v-model:data="form.ccData"
+        :modalProps="{ title: '选择抄送人' }"
+        placeholder="请选择抄送人"
+      />
+    </el-form-item>
+  </el-form>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const form = ref({
+  applicantName: '张三',
+  approverId: '',
+  approverData: {},
+  ccIds: [],
+  ccData: []
+});
+</script>
+```
+
+### 2. 团队管理场景
+
+```vue
+<template>
+  <el-form :model="form">
+    <el-form-item label="团队名称">
+      <el-input v-model="form.teamName" placeholder="请输入团队名称" />
+    </el-form-item>
+    
+    <el-form-item label="团队负责人">
+      <sohelp-user-modal-select
+        v-model="form.leaderId"
+        v-model:data="form.leaderData"
+        :multiple="false"
+        selectionTemplate="${user_name} (${nickname})"
+        placeholder="请选择团队负责人"
+      />
+    </el-form-item>
+    
+    <el-form-item label="团队成员">
+      <sohelp-user-modal-select
+        v-model="form.memberIds"
+        v-model:data="form.memberData"
+        :gridProps="{
+          gridOptions: {
+            pagerConfig: {
+              pageSize: 10
+            }
+          }
+        }"
+        placeholder="请选择团队成员"
+      />
+    </el-form-item>
+  </el-form>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const form = ref({
+  teamName: '',
+  leaderId: '',
+  leaderData: {},
+  memberIds: [],
+  memberData: []
+});
+</script>
+```
+
+### 3. 权限分配场景
+
+```vue
+<template>
+  <el-form :model="form">
+    <el-form-item label="角色名称">
+      <el-input v-model="form.roleName" placeholder="请输入角色名称" />
+    </el-form-item>
+    
+    <el-form-item label="角色管理员">
+      <sohelp-user-modal-select
+        v-model="form.adminIds"
+        v-model:data="form.adminData"
+        :modalProps="{ title: '选择角色管理员' }"
+        placeholder="请选择角色管理员"
+      />
+    </el-form-item>
+  </el-form>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const form = ref({
+  roleName: '',
+  adminIds: [],
+  adminData: []
+});
+</script>
+```
+
+## ❓ 常见问题
+
+### Q1: 如何修改默认的列配置？
+
+**A**: 通过 `gridProps.gridOptions.columns` 覆盖默认配置：
+
+```vue
+<sohelp-user-modal-select
+  v-model="selectedIds"
+  v-model:data="selectedData"
+  :gridProps="{
+    gridOptions: {
+      columns: [
+        { field: 'user_name', title: '姓名', width: 150 },
+        { field: 'login_name', title: '登录名', width: 180 },
+        { field: 'email', title: '邮箱', width: 200 },
+        { field: 'phone', title: '手机号', width: 150 }
+      ]
+    }
+  }"
+/>
+```
+
+### Q2: 如何修改默认的分页大小？
+
+**A**: 通过 `gridProps.gridOptions.pagerConfig.pageSize` 设置：
+
+```vue
+<sohelp-user-modal-select
+  v-model="selectedIds"
+  v-model:data="selectedData"
+  :gridProps="{
+    gridOptions: {
+      pagerConfig: {
+        pageSize: 20
+      }
+    }
+  }"
+/>
+```
+
+### Q3: 如何修改默认的接口地址？
+
+**A**: 通过 `gridProps.url` 覆盖：
+
+```vue
+<sohelp-user-modal-select
+  v-model="selectedIds"
+  v-model:data="selectedData"
+  :gridProps="{
+    url: '/api/custom/user/page'
+  }"
+/>
+```
+
+### Q4: 单选和多选有什么区别？
+
+**A**: 
+- 单选：`multiple="false"`，`modelValue` 为字符串，弹窗显示 radio 列
+- 多选：`multiple="true"`（默认），`modelValue` 为数组，弹窗显示 checkbox 列和已选列表
+
+### Q5: 如何实现按部门筛选用户？
+
+**A**: 使用计算属性动态修改 `gridProps.url`：
+
+```vue
+<script setup>
+import { ref, computed } from 'vue';
+
+const deptId = ref('1');
+const selectedIds = ref([]);
+const selectedData = ref([]);
+
+const dynamicGridProps = computed(() => ({
+  url: `/api/user/page?deptId=${deptId.value}`,
+  gridOptions: {
+    columns: [
+      { field: 'user_name', title: '姓名' },
+      { field: 'login_name', title: '登录名' }
+    ]
+  }
+}));
+</script>
+```
+
+### Q6: 为什么显示格式是 `${user_name}-${login_name}`？
+
+**A**: 这是组件的默认配置，通过 `selectionTemplate` 属性设置。你可以自定义：
+
+```vue
+<sohelp-user-modal-select
+  v-model="selectedIds"
+  v-model:data="selectedData"
+  selectionTemplate="${nickname}"
+  placeholder="请选择用户"
+/>
+```
+
+### Q7: 如何限制只能选择一定数量的用户？
+
+**A**: 使用 `beforeOpen` 钩子：
+
+```vue
+<script setup>
+const MAX_USERS = 10;
+
+const handleBeforeOpen = (modelValue, data) => {
+  const currentCount = Array.isArray(modelValue) ? modelValue.length : 0;
+  if (currentCount >= MAX_USERS) {
+    ElMessage.warning(`最多只能选择 ${MAX_USERS} 个用户`);
+    return false;
+  }
+  return true;
+};
+</script>
+```
+
+## 🔗 相关组件
+
+- [sohelp-modal-select](../sohelp-modal-select/README.md) - 弹窗选择器（通用）
+- [sohelp-vxe-grid](../sohelp-vxe-grid/README.md) - 数据网格组件
+- [sohelp-modal](../sohelp-modal/README.md) - 弹窗组件
+
+## 📝 更新日志
+
+### v1.2.0
+- ✨ 优化默认显示格式为 `${user_name}-${login_name}`
+- ✨ 改进数据回显逻辑
+- 🐛 修复取消操作后数据一致性问题
+
+### v1.1.0
+- ✨ 支持自定义 `selectionTemplate`
+- ✨ 支持自定义字段配置
+
+### v1.0.0
+- 🎉 初始版本