recruitment-wechat-uniapp-241012/components/JobTypePicker-README.md

# JobTypePicker 工种选择组件

基于 AddressPicker 组件设计的工种选择组件，支持单选、多选和多级树形结构。

## 功能特性

- ✅ **单选模式**：选择单个工种
- ✅ **多选模式**：支持选择多个工种
- ✅ **多级树形结构**：支持一级、二级、三级工种选择
- ✅ **灵活配置**：可配置只选择到二级工种
- ✅ **整个工种选择**：支持选择整个工种类别
- ✅ **数据缓存**：自动缓存已加载的工种数据
- ✅ **响应式设计**：适配不同屏幕尺寸

## 组件属性

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| multiple | Boolean | false | 是否支持多选 |
| onlySubType | Boolean | false | 是否只选择到二级工种，不选择三级 |
| showSelectWholeType | Boolean | false | 是否显示"选择整个工种"选项 |

## 事件

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| confirm | 确认选择时触发 | result: 选择结果对象 |

## 返回数据结构

```javascript
{
  // 选中的工种层级
  parentType: Object,      // 一级工种对象
  subType: Object,         // 二级工种对象
  detailType: Object,      // 三级工种对象
  
  // 多选时的数组
  subTypes: Array,         // 多选二级工种数组
  detailTypes: Array,      // 多选三级工种数组
  
  // 最终选中的工种
  selectedJobType: Object, // 最终选中的工种对象
  
  // 用于后端的数据
  selectedId: String,      // 单选时的工种ID
  selectedIds: Array,      // 多选时的工种ID数组
  
  // 显示文本
  fullJobType: String      // 完整的工种名称文本
}
```

## 基本用法

### 1. 单选模式

```vue
<template>
  <view>
    <uv-cell
      title="选择工种"
      :value="selectedJobType || '请选择工种'"
      @click="openJobTypePicker"
      isLink
    ></uv-cell>
    
    <JobTypePicker 
      ref="jobTypePicker" 
      @confirm="onJobTypeConfirm" 
    />
  </view>
</template>

<script>
import JobTypePicker from '@/components/JobTypePicker.vue'

export default {
  components: {
    JobTypePicker
  },
  data() {
    return {
      selectedJobType: ''
    }
  },
  methods: {
    openJobTypePicker() {
      this.$refs.jobTypePicker.open()
    },
    onJobTypeConfirm(result) {
      this.selectedJobType = result.fullJobType
      console.log('选中的工种ID:', result.selectedId)
    }
  }
}
</script>
```

### 2. 多选模式

```vue
<template>
  <view>
    <JobTypePicker 
      ref="multipleJobTypePicker" 
      :multiple="true"
      @confirm="onMultipleJobTypeConfirm" 
    />
  </view>
</template>

<script>
export default {
  methods: {
    onMultipleJobTypeConfirm(result) {
      console.log('选中的工种:', result.fullJobType)
      console.log('选中的工种ID数组:', result.selectedIds)
      console.log('选中的工种数量:', result.selectedIds.length)
    }
  }
}
</script>
```

### 3. 只选择到二级工种

```vue
<template>
  <view>
    <JobTypePicker 
      ref="subTypeJobTypePicker" 
      :onlySubType="true"
      @confirm="onSubTypeJobTypeConfirm" 
    />
  </view>
</template>

<script>
export default {
  methods: {
    onSubTypeJobTypeConfirm(result) {
      // 只会返回到二级工种，不会有三级工种
      console.log('选中的二级工种:', result.selectedJobType)
    }
  }
}
</script>
```

### 4. 带"选择整个工种"选项

```vue
<template>
  <view>
    <JobTypePicker 
      ref="wholeJobTypePicker" 
      :showSelectWholeType="true"
      @confirm="onWholeJobTypeConfirm" 
    />
  </view>
</template>

<script>
export default {
  methods: {
    onWholeJobTypeConfirm(result) {
      // 可以选择整个工种类别
      console.log('选中结果:', result)
    }
  }
}
</script>
```

## 数据源配置

组件依赖 Vuex store 中的工种数据，需要确保以下配置：

### 1. store.js 配置

```javascript
// state 中添加
state: {
  jobTypeList: [],        // 一级工种列表
  jobTypeTreeMap: {}      // 多级工种映射
}

// mutations 中添加
mutations: {
  setChildJobTypeList(state, { pid, list }) {
    state.jobTypeTreeMap[pid] = list
  }
}

// actions 中添加
actions: {
  async getChildJobTypeList({ state, commit }, pid) {
    if(state.jobTypeTreeMap[pid]) {
      return Promise.resolve(state.jobTypeTreeMap[pid])
    }
    
    return new Promise((resolve, reject) => {
      api('commonQueryJobTypeList', {
        pageNo: 1,
        pageSize: 99999,
        pid: pid
      }, res => {
        if(res.code == 200) {
          commit('setChildJobTypeList', { pid, list: res.result.records })
          resolve(res.result.records)
        } else {
          reject(res)
        }
      })
    })
  }
}
```

### 2. API 接口

确保 `commonQueryJobTypeList` 接口支持 `pid` 参数来获取子级工种：

```javascript
// api.js
commonQueryJobTypeList: {
  url: '/api/common/queryJobTypeList',
  method: 'GET'
}
```

## 样式自定义

组件使用了 SCSS 变量，可以通过修改 uni-app 的主题变量来自定义样式：

```scss
// uni.scss
$uni-color: #007aff; // 主题色
```

## 注意事项

1. **数据格式**：工种数据需要包含 `id`、`name` 字段
2. **层级关系**：通过 `pid` 字段建立父子关系
3. **缓存机制**：已加载的工种数据会自动缓存，避免重复请求
4. **错误处理**：当获取子级工种失败时，会自动确认当前选择
5. **性能优化**：使用了 scroll-view 组件，支持大量数据的流畅滚动

## 示例页面

可以参考 `pages/demo/JobTypePickerDemo.vue` 文件查看完整的使用示例。

## 依赖组件

- uv-popup：弹窗组件
- uv-icon：图标组件
- uv-cell：单元格组件（示例中使用）

## 兼容性

- ✅ H5
- ✅ 小程序
- ✅ App

## 更新日志

### v1.0.0
- 初始版本
- 支持单选、多选、多级树形结构
- 支持数据缓存和错误处理