sohelp-eleplus 1.1.26 → 1.1.28

package/sohelp-modal-select/README.md

@@ -0,0 +1,745 @@
+# SohelpModalSelect 弹窗选择器
+
+基于 `sohelp-modal` 和 `sohelp-vxe-grid` 封装的弹窗选择组件，点击输入框弹出表格列表进行单选/多选，选中后以 Tag 形式回显。
+
+## ✨ 特性
+
+- 🎯 **单选/多选** - 支持灵活的选模式切换
+- 🔍 **分页搜索** - 内置分页和关键字搜索功能
+- 📊 **实时预览** - 多选模式下实时显示已选数据
+- 🎨 **自定义模板** - 支持自定义显示格式
+- ⚙️ **灵活配置** - 完全自定义弹窗和表格配置
+- 🔄 **双向绑定** - v-model 和 v-model:data 完整支持
+- 🪝 **钩子函数** - 打开前/确认前的回调控制
+- 📱 **响应式布局** - 高度自适应，无抖动
+- 🛡️ **数据一致性** - 取消操作后数据自动回显
+
+## 📖 基础用法
+
+### 基础多选
+
+```vue
+<template>
+  <sohelp-modal-select
+    v-model="selectedIds"
+    v-model:data="selectedData"
+    :gridProps="{
+      url: '/api/user/page',
+      gridOptions: {
+        columns: [
+          { field: 'name', title: '姓名', width: 120 },
+          { field: 'code', title: '编码', width: 120 }
+        ]
+      }
+    }"
+    labelField="name"
+    valueField="id"
+    multiple
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedIds = ref([]);
+const selectedData = ref([]);
+</script>
+```
+
+### 单选模式
+
+```vue
+<template>
+  <sohelp-modal-select
+    v-model="selectedId"
+    v-model:data="selectedData"
+    :gridProps="{
+      url: '/api/user/page',
+      gridOptions: {
+        columns: [
+          { field: 'name', title: '姓名' },
+          { field: 'code', title: '编码' }
+        ]
+      }
+    }"
+    :multiple="false"
+    labelField="name"
+    valueField="id"
+    placeholder="请选择用户"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedId = ref('');
+const selectedData = ref({});
+</script>
+```
+
+### 自定义显示模板
+
+使用 `selectionTemplate` 属性自定义已选列表的显示格式，支持 `${field}` 占位符：
+
+```vue
+<template>
+  <sohelp-modal-select
+    v-model="selectedIds"
+    v-model:data="selectedData"
+    :gridProps="{
+      url: '/api/user/page',
+      gridOptions: {
+        columns: [
+          { field: 'user_name', title: '姓名' },
+          { field: 'login_name', title: '登录名' }
+        ]
+      }
+    }"
+    labelField="user_name"
+    valueField="id"
+    selectionTemplate="${user_name} (${login_name})"
+    multiple
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedIds = ref([]);
+const selectedData = ref([]);
+</script>
+```
+
+### 自定义弹窗配置
+
+```vue
+<template>
+  <sohelp-modal-select
+    v-model="selectedIds"
+    v-model:data="selectedData"
+    :modalProps="{
+      title: '选择用户',
+      width: '80%',
+      minWidth: 800,
+      minHeight: 600
+    }"
+    :gridProps="{
+      url: '/api/user/page',
+      gridOptions: {
+        columns: [
+          { field: 'user_name', title: '姓名' },
+          { field: 'login_name', title: '登录名' }
+        ]
+      }
+    }"
+    labelField="user_name"
+    valueField="id"
+  />
+</template>
+```
+
+### 使用钩子函数
+
+```vue
+<template>
+  <sohelp-modal-select
+    v-model="selectedIds"
+    v-model:data="selectedData"
+    :gridProps="gridProps"
+    labelField="name"
+    valueField="id"
+    :beforeOpen="handleBeforeOpen"
+    @confirm="handleConfirm"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { ElMessage } from 'element-plus';
+
+const selectedIds = ref([]);
+const selectedData = ref([]);
+
+const gridProps = {
+  url: '/api/user/page',
+  gridOptions: {
+    columns: [
+      { field: 'name', title: '姓名' },
+      { field: 'code', title: '编码' }
+    ]
+  }
+};
+
+// 打开前钩子
+const handleBeforeOpen = (modelValue, data) => {
+  console.log('当前选中值:', modelValue);
+  console.log('当前选中数据:', data);
+  // 返回 false 可以阻止弹窗打开
+  return true;
+};
+
+// 确认事件
+const handleConfirm = (selectedIds, selectedData) => {
+  console.log('选中的 ID:', selectedIds);
+  console.log('选中的数据:', selectedData);
+  ElMessage.success('已选择 ' + selectedIds.length + ' 条数据');
+};
+</script>
+```
+
+### 表单验证场景
+
+```vue
+<template>
+  <el-form :model="form" :rules="rules" ref="formRef">
+    <el-form-item label="用户" prop="userIds">
+      <sohelp-modal-select
+        v-model="form.userIds"
+        v-model:data="form.userData"
+        :gridProps="{
+          url: '/api/user/page',
+          gridOptions: {
+            columns: [
+              { field: 'user_name', title: '姓名' },
+              { field: 'login_name', title: '登录名' }
+            ]
+          }
+        }"
+        labelField="user_name"
+        valueField="id"
+        placeholder="请选择用户"
+      />
+    </el-form-item>
+    
+    <el-form-item>
+      <el-button type="primary" @click="submitForm">提交表单</el-button>
+      <el-button @click="resetForm">重置</el-button>
+    </el-form-item>
+  </el-form>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const formRef = ref(null);
+const form = ref({
+  userIds: [],
+  userData: []
+});
+
+const rules = {
+  userIds: [
+    { required: true, message: '请选择用户', trigger: 'change' }
+  ]
+};
+
+const submitForm = async () => {
+  await formRef.value?.validate();
+  console.log('提交表单:', form.value);
+  // 提交到后端...
+};
+
+const resetForm = () => {
+  formRef.value?.resetFields();
+};
+</script>
+```
+
+### 自定义触发区域
+
+```vue
+<template>
+  <sohelp-modal-select
+    v-model="selectedIds"
+    v-model:data="selectedData"
+    :gridProps="gridProps"
+    labelField="name"
+    valueField="id"
+  >
+    <template #header="{ data }">
+      <el-button type="primary" @click.stop>
+        已选择 {{ data.length }} 人
+      </el-button>
+    </template>
+  </sohelp-modal-select>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectedIds = ref([]);
+const selectedData = ref([]);
+
+const gridProps = {
+  url: '/api/user/page',
+  gridOptions: {
+    columns: [
+      { field: 'name', title: '姓名' },
+      { field: 'code', title: '编码' }
+    ]
+  }
+};
+</script>
+```
+
+### 禁用/只读状态
+
+```vue
+<template>
+  <div>
+    <!-- 禁用 -->
+    <sohelp-modal-select
+      v-model="selectedIds"
+      v-model:data="selectedData"
+      :gridProps="gridProps"
+      labelField="name"
+      valueField="id"
+      disabled
+    />
+    
+    <!-- 只读 -->
+    <sohelp-modal-select
+      v-model="selectedIds"
+      v-model:data="selectedData"
+      :gridProps="gridProps"
+      labelField="name"
+      valueField="id"
+      readonly
+    />
+  </div>
+</template>
+```
+
+### 数据回显场景
+
+```vue
+<template>
+  <sohelp-modal-select
+    v-model="form.userIds"
+    v-model:data="form.userData"
+    :gridProps="{
+      url: '/api/user/page',
+      gridOptions: {
+        columns: [
+          { field: 'user_name', title: '姓名' },
+          { field: 'login_name', title: '登录名' }
+        ]
+      }
+    }"
+    labelField="user_name"
+    valueField="id"
+  />
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue';
+
+const form = ref({
+  userIds: [],
+  userData: []
+});
+
+// 模拟从后端加载数据
+onMounted(async () => {
+  // 这里假设从后端获取数据
+  const response = await fetch('/api/user/detail');
+  const data = await response.json();
+  
+  form.value.userIds = data.userIds || [];
+  form.value.userData = data.userData || [];
+  
+  // 组件会自动回显数据
+});
+</script>
+```
+
+## 📋 属性 (Props)
+
+| 属性名 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| modelValue (v-model) | String / Array | `''` | 否 | 选中项的值（valueField 对应的值），多选时为数组 |
+| data (v-model:data) | Array / Object | `[]` | 否 | 选中项的完整数据对象，多选时为数组 |
+| multiple | Boolean | `true` | 否 | 是否多选模式 |
+| labelField | String | `'label'` | 否 | 显示字段名（Tag 显示） |
+| valueField | String | `'value'` | 否 | 值字段名（用于 v-model） |
+| placeholder | String | `'请选择'` | 否 | 未选择时的占位文本 |
+| title | String | `'选择'` | 否 | 弹窗标题（可被 modalProps.title 覆盖） |
+| disabled | Boolean | `false` | 否 | 是否禁用 |
+| readonly | Boolean | `false` | 否 | 是否只读 |
+| clearable | Boolean | `true` | 否 | 是否可清空 |
+| modalProps | Object | `{ title: '选择数据', width: '100%' }` | 否 | 传递给 sohelp-modal 的属性 |
+| gridProps | Object | `{ url: '/admin/system/user/page', autoLoad: true, gridOptions: { columns: [] } }` | 否 | 传递给 sohelp-vxe-grid 的属性 |
+| beforeOpen | Function | `() => true` | 否 | 打开前的回调函数 |
+| selectionTemplate | String | `''` | 否 | 已选列表的显示模板 |
+
+### modalProps 常用配置
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| title | String | `'选择数据'` | 弹窗标题 |
+| width | String | `'50%'` | 弹窗宽度 |
+| minWidth | Number | `500` | 弹窗最小宽度 |
+| minHeight | Number | `500` | 弹窗最小高度 |
+| closeOnClickModal | Boolean | `true` | 点击遮罩是否关闭 |
+
+### gridProps 常用配置
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| url | String | `'/admin/system/user/page'` | 数据接口地址 |
+| autoLoad | Boolean | `true` | 是否自动加载数据 |
+| gridOptions | Object | - | 表格配置对象 |
+| gridOptions.columns | Array | `[]` | 表格列配置 |
+| gridOptions.pagerConfig | Object | `{ enabled: true, pageSize: 50 }` | 分页配置 |
+
+## 🔄 双向绑定 (v-model)
+
+| 属性名 | 类型 | 说明 |
+| --- | --- | --- |
+| modelValue | String / Array | 选中项的值（valueField 对应的值），多选时为数组，单选时为字符串 |
+| data | Array / Object | 选中项的完整数据对象，多选时为数组，单选时为对象 |
+
+## 🎯 事件 (Events)
+
+| 事件名 | 回调参数 | 说明 |
+| --- | --- | --- |
+| update:modelValue | `(selectedIds)` | 选中值变化时触发 |
+| confirm | `(selectedIds, selectedData)` | 点击确认后触发，返回选中的 ID 数组和完整数据 |
+| page-change | `(pageInfo)` | 分页变化时触发 |
+
+## 🎨 插槽 (Slots)
+
+| 插槽名 | 作用域参数 | 说明 |
+| --- | --- | --- |
+| header | `{ data }` | 自定义触发区域，替换默认的 Tag 输入框 |
+| default | - | 自定义弹窗内容区域，替换默认的表格 |
+
+## 🔧 方法 (Methods)
+
+通过 `ref` 可以调用以下方法：
+
+| 方法名 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| clearAll | - | - | 清空所有选中数据 |
+
+```vue
+<template>
+  <sohelp-modal-select
+    ref="selectRef"
+    v-model="selectedIds"
+    v-model:data="selectedData"
+    :gridProps="gridProps"
+  />
+  <el-button @click="clearSelection">清空选中</el-button>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const selectRef = ref(null);
+const selectedIds = ref([]);
+const selectedData = ref([]);
+
+const clearSelection = () => {
+  selectRef.value?.clearAll();
+};
+</script>
+```
+
+## 📊 数据流说明
+
+组件的数据流设计如下：
+
+```
+┌─────────────┐
+│  打开弹窗    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────────────────────────┐
+│  根据 modelValue 和 data 回显数据      │
+│  - selections = data.value          │
+│  - 表格选中状态 = selections         │
+└──────┬──────────────────────────────┘
+       │
+       ▼
+┌─────────────┐
+│  用户操作     │
+│  - 添加选中   │
+│  - 删除选中   │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────────────────────────┐
+│  selections 临时保存选中状态          │
+│  (不影响 modelValue 和 data)        │
+└──────┬──────────────────────────────┘
+       │
+       ▼
+┌─────────────┐    ┌─────────────┐
+│  点击确认     │    │  点击取消     │
+└──────┬──────┘    └──────┬──────┘
+       │                  │
+       ▼                  ▼
+┌─────────────┐    ┌─────────────────────┐
+│ 更新：        │    │ 不更新：              │
+│ - modelValue │    │ - modelValue 保持不变 │
+│ - data       │    │ - data 保持不变      │
+└─────────────┘    └─────────────────────┘
+```
+
+1. **v-model（modelValue）**：保存选中项的 ID 值（或 ID 数组）
+2. **v-model:data（data）**：保存选中项的完整数据对象
+3. **弹窗打开时**：根据 `modelValue` 和 `data` 自动回显已选数据
+4. **弹窗操作时**：`selections` 临时保存弹窗内的选中状态
+5. **点击确认时**：将 `selections` 同步到 `modelValue` 和 `data`
+6. **点击取消/关闭时**：不修改 `modelValue` 和 `data`，下次打开时重新回显
+
+## 🎯 最佳实践
+
+### 1. 数据回显
+
+```vue
+<template>
+  <sohelp-modal-select
+    v-model="form.userIds"
+    v-model:data="form.userData"
+    :gridProps="{
+      url: '/api/user/page',
+      gridOptions: {
+        columns: [
+          { field: 'user_name', title: '姓名' },
+          { field: 'login_name', title: '登录名' }
+        ]
+      }
+    }"
+    labelField="user_name"
+    valueField="id"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const form = ref({
+  userIds: ['1', '2', '3'],
+  userData: [
+    { id: '1', user_name: '张三', login_name: 'zhangsan' },
+    { id: '2', user_name: '李四', login_name: 'lisi' },
+    { id: '3', user_name: '王五', login_name: 'wangwu' }
+  ]
+});
+
+// 组件会自动回显这些数据
+</script>
+```
+
+### 2. 表单验证
+
+```vue
+<template>
+  <el-form :model="form" :rules="rules">
+    <el-form-item label="用户" prop="userIds">
+      <sohelp-modal-select
+        v-model="form.userIds"
+        v-model:data="form.userData"
+        :gridProps="gridProps"
+      />
+    </el-form-item>
+  </el-form>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const form = ref({
+  userIds: [],
+  userData: []
+});
+
+const rules = {
+  userIds: [
+    { required: true, message: '请选择用户', trigger: 'change' }
+  ]
+};
+</script>
+```
+
+### 3. 动态过滤数据
+
+```vue
+<template>
+  <div>
+    <el-select v-model="deptId" placeholder="请选择部门">
+      <el-option label="技术部" value="1" />
+      <el-option label="市场部" value="2" />
+    </el-select>
+    
+    <sohelp-modal-select
+      v-model="selectedIds"
+      v-model:data="selectedData"
+      :gridProps="dynamicGridProps"
+      labelField="user_name"
+      valueField="id"
+    />
+  </div>
+</template>
+
+<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>
+```
+
+### 4. 级联选择
+
+```vue
+<template>
+  <div>
+    <sohelp-modal-select
+      v-model="form.deptId"
+      v-model:data="form.deptData"
+      :gridProps="deptGridProps"
+      labelField="name"
+      valueField="id"
+      placeholder="请选择部门"
+      @confirm="handleDeptChange"
+    />
+    
+    <sohelp-modal-select
+      v-if="form.deptId"
+      v-model="form.userId"
+      v-model:data="form.userData"
+      :gridProps="userGridProps"
+      labelField="user_name"
+      valueField="id"
+      placeholder="请选择用户"
+    />
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const form = ref({
+  deptId: '',
+  deptData: {},
+  userId: '',
+  userData: {}
+});
+
+const deptGridProps = {
+  url: '/api/dept/page',
+  gridOptions: {
+    columns: [
+      { field: 'name', title: '部门名称' },
+      { field: 'code', title: '部门编码' }
+    ]
+  }
+};
+
+const userGridProps = ref({
+  url: '',
+  gridOptions: {
+    columns: [
+      { field: 'user_name', title: '姓名' },
+      { field: 'login_name', title: '登录名' }
+    ]
+  }
+});
+
+const handleDeptChange = (deptIds) => {
+  if (deptIds.length > 0) {
+    // 根据选择的部门加载用户
+    userGridProps.value.url = `/api/user/page?deptId=${deptIds[0]}`;
+  }
+};
+</script>
+```
+
+## ❓ 常见问题
+
+### Q1: 为什么需要同时绑定 v-model 和 v-model:data？
+
+**A**: 
+- `v-model` 保存 ID 值，用于提交到后端
+- `v-model:data` 保存完整数据，用于界面显示和数据处理
+- 这样设计可以避免重复请求接口获取完整数据
+
+### Q2: 弹窗取消后再次打开，为什么还能看到之前的选中状态？
+
+**A**: 这是正常设计。组件每次打开弹窗时，会根据 `v-model` 和 `v-model:data` 的值重新回显数据，确保数据一致性。只有在点击确认时才会更新这两个值。
+
+### Q3: 如何实现级联选择？
+
+**A**: 可以在 `beforeOpen` 钩子中动态修改 `gridProps.url`，或使用 `:gridProps="dynamicGridProps"` 计算属性。参考上面的"级联选择"示例。
+
+### Q4: 表格高度抖动怎么办？
+
+**A**: 组件已优化布局，使用了 flex 布局的 `min-height: 0` 技巧。如果仍有问题，请检查：
+
+1. 确保 `gridProps.gridOptions.height` 不与容器高度冲突
+2. 确保弹窗容器有明确的高度设置
+3. 检查是否有其他 CSS 样式影响布局
+
+### Q5: 选中数据后再次打开弹窗，取消部分选中，点取消，为什么数据不对？
+
+**A**: 这是已修复的问题。组件现在每次打开弹窗时，都会根据 `modelValue` 和 `data` 重新初始化 `selections`，确保不受上次弹窗操作的影响。
+
+### Q6: 确认后 data.value 中的数据只有部分字段？
+
+**A**: 组件会根据 `gridOptions.columns` 中的字段配置补充数据。如果需要保留所有字段，请确保 `columns` 中包含所需的所有字段，或确保原始数据中已包含所有字段。
+
+### Q7: 如何实现默认选中某些数据？
+
+**A**: 直接设置 `v-model` 和 `v-model:data` 的初始值即可：
+
+```vue
+<script setup>
+const selectedIds = ref(['1', '2', '3']);
+const selectedData = ref([
+  { id: '1', name: '张三' },
+  { id: '2', name: '李四' },
+  { id: '3', name: '王五' }
+]);
+</script>
+```
+
+## 📝 更新日志
+
+### v1.3.0
+- 🐛 修复选中数据后再次打开弹窗，取消部分选中导致数据丢失的问题
+- 🐛 修复确认后 data.value 中数据字段丢失的问题
+- ✨ 优化弹窗布局，修复高度抖动问题
+- ✨ 改进数据回显逻辑，确保取消操作后数据一致性
+
+### v1.2.0
+- ✨ 新增 `selectionTemplate` 属性，支持自定义显示模板
+- ✨ 新增 `beforeOpen` 钩子函数
+- ✨ 支持单选/多选模式切换
+
+### v1.1.0
+- ✨ 优化选中区域显示效果
+- ✨ 支持自定义弹窗内容区域
+
+### v1.0.0
+- 🎉 初始版本
+
+## 🔗 相关组件
+
+- [sohelp-vxe-grid](../sohelp-vxe-grid/README.md) - 数据网格组件
+- [sohelp-modal](../sohelp-modal/README.md) - 弹窗组件
+- [sohelp-user-modal-select](../sohelp-user-modal-select/README.md) - 用户选择器