CustomerSelect 组件说明

本目录包含两个客户选择组件，分别适用于不同的使用场景。

组件列表

1. SimpleCustomerSelect.vue - 简单客户选择组件

适用场景：只需要选择客户的简单场景

特点：

轻量级，代码简洁
支持搜索和远程搜索
双向数据绑定（v-model）
显示客户名称和编码
自动加载活跃客户列表

基本用法：

<template>
  <SimpleCustomerSelect
    v-model="selectedCustomerId"
    placeholder="请选择客户"
    :disabled="false"
    @change="handleCustomerChange"
  />
</template>

<script setup>
import SimpleCustomerSelect from '@/components/CustomerSelect/SimpleCustomerSelect.vue'

const selectedCustomerId = ref(null)

const handleCustomerChange = (value, customer) => {
  console.log('选中的客户ID:', value)
  console.log('选中的客户信息:', customer)
}
</script>

事件：
| 事件名 | 说明 | 回调参数 |
|——–|——|———-|
| update:modelValue | 值更新事件 | (value: number/string) |
| change | 选择变更事件 | (value: number/string, customer: object) |
| clear | 清空选择事件 | - |

方法（通过ref调用）：
| 方法名 | 说明 | 参数 | 返回值 |
|——–|——|——|——–|
| refresh | 刷新客户列表 | - | Promise |
| reset | 重置选择 | - | void |
| getSelectedCustomer | 获取选中的客户信息 | - | Object/null |
| loadCustomers | 加载客户列表 | - | Promise |

2. index.vue - 复杂级联客户选择组件

适用场景：需要客户-项目-设备三级级联选择的复杂场景

特点：

支持客户、项目、设备三级联动
可配置显示哪些层级
自动级联清空下级数据
支持编辑模式自动加载数据

选择建议

使用 SimpleCustomerSelect 的场景：

✅ 只需要选择客户的简单表单
✅ 备件入库、出库、锁定等操作
✅ 轻量级、高响应性要求
✅ 快速开发、简单配置

使用复杂级联组件的场景：

✅ 需要客户-项目-设备三级联动
✅ 工单管理等复杂业务流程
✅ 需要级联数据关联的场景
✅ 需要灵活配置显示层级的表单

复杂级联组件使用指南

完整级联选择(一行显示)

<CustomerSelect
  v-model:customer-id="form.customerId"
  v-model:project-id="form.projectId"
  v-model:equipment-id="form.equipmentId"
/>

分行显示(表单布局)

<el-row :gutter="20">
  <el-col :span="12">
    <CustomerSelect
      v-model:customer-id="form.customerId"
      v-model:project-id="form.projectId"
      v-model:equipment-id="form.equipmentId"
      :show-customer="true"
      :show-project="false"
      :show-equipment="false"
      customer-prop="customerId"
      @customer-change="handleCustomerChange"
    />
  </el-col>

  <el-col :span="12">
    <CustomerSelect
      v-model:customer-id="form.customerId"
      v-model:project-id="form.projectId"
      v-model:equipment-id="form.equipmentId"
      :show-customer="false"
      :show-project="true"
      :show-equipment="false"
      project-prop="projectId"
      :auto-load="true"
      :cascade="true"
      ref="projectSelectRef"
      @project-change="handleProjectChange"
    />
  </el-col>
</el-row>

只显示客户选择

<CustomerSelect
  v-model:customer-id="customerId"
  :show-project="false"
  :show-equipment="false"
/>

编辑模式(自动加载已选数据)

<CustomerSelect
  v-model:customer-id="form.customerId"
  v-model:project-id="form.projectId"
  v-model:equipment-id="form.equipmentId"
  :auto-load="true"
/>

完整三级联动选择(客户-项目-设备)

<el-row :gutter="20">
  <el-col :span="8">
    <CustomerSelect
      v-model:customer-id="form.customerId"
      v-model:project-id="form.projectId"
      v-model:equipment-id="form.equipmentId"
      :show-customer="true"
      :show-project="false"
      :show-equipment="false"
      customer-prop="customerId"
      @customer-change="handleCustomerChange"
    />
  </el-col>
  <el-col :span="8">
    <CustomerSelect
      v-model:customer-id="form.customerId"
      v-model:project-id="form.projectId"
      v-model:equipment-id="form.equipmentId"
      :show-customer="false"
      :show-project="true"
      :show-equipment="false"
      project-prop="projectId"
      :auto-load="true"
      :cascade="true"
      ref="projectSelectRef"
      @project-change="handleProjectChange"
    />
  </el-col>
  <el-col :span="8">
    <CustomerSelect
      v-model:customer-id="form.customerId"
      v-model:project-id="form.projectId"
      v-model:equipment-id="form.equipmentId"
      :show-customer="false"
      :show-project="false"
      :show-equipment="true"
      equipment-prop="equipmentId"
      :auto-load="true"
      :cascade="true"
      ref="equipmentSelectRef"
    />
  </el-col>
</el-row>

事件处理示例

<script setup>
import { ref } from 'vue'

const projectSelectRef = ref(null)
const equipmentSelectRef = ref(null)

// 客户变化处理 - 自动加载项目列表
const handleCustomerChange = (customerId) => {
  if (customerId && projectSelectRef.value) {
    setTimeout(() => {
      if (projectSelectRef.value) {
        projectSelectRef.value.loadProjectsByCustomer(customerId)
      }
    }, 100)
  }
}

// 项目变化处理 - 自动加载设备列表
const handleProjectChange = (projectId) => {
  if (projectId && equipmentSelectRef.value) {
    setTimeout(() => {
      if (equipmentSelectRef.value) {
        equipmentSelectRef.value.loadEquipmentsByProject(projectId)
      }
    }, 100)
  }
}
</script>

迁移指南

从复杂组件迁移到简单组件：

原有代码：

<CustomerSelect
  v-model:customer-id="form.customerId"
  :show-project="false"
  :show-equipment="false"
  placeholder="请选择客户"
/>

新代码：

<SimpleCustomerSelect
  v-model="form.customerId"
  placeholder="请选择客户"
/>

注意事项：

简单组件使用 v-model 而不是 v-model:customer-id
简单组件不需要配置 :show-project="false" :show-equipment="false"
简单组件的事件回调参数略有不同
简单组件提供了更多便捷的方法调用

已重构的组件

以下组件已经从复杂级联组件迁移到简单客户选择组件：

StockInDialog.vue - 备件入库对话框
StockOutDialog.vue - 备件出库对话框
LockDialog.vue - 备件锁定对话框

最佳实践

优先使用简单组件：对于只需要客户选择的场景，优先使用 SimpleCustomerSelect
合理配置自动加载：根据场景选择是否启用 autoLoad 和 loadOnFocus
利用事件回调：使用 change 事件获取完整的客户信息
注意性能优化：设置合适的 pageSize，避免一次性加载过多数据

更新日志

v2.1.0 (2025-10-21)

修复级联选择功能：解决选择客户后项目无数据、选择项目后设备无数据的问题
完善分行显示示例：添加事件监听和自动加载配置
新增三级联动完整示例：提供客户-项目-设备完整级联选择实现
添加事件处理说明：提供handleCustomerChange和handleProjectChange处理函数示例
优化组件Props说明：明确auto-load和cascade属性的使用场景

v2.0.0 (2025-10-21)

新增 SimpleCustomerSelect 简单客户选择组件
重构备件管理相关组件，使用简单客户选择组件
保留复杂级联组件用于需要级联的场景
更新组件使用说明文档

v1.0.0 (2025-01-12)

首次发布复杂级联客户选择组件
支持客户-项目-设备级联选择
支持远程搜索和自动加载
支持独立显示和组合显示

作者：聂盼盼创建时间：2025-10-27 23:09
最后编辑：聂盼盼更新时间：2025-10-28 19:53

第二版