# 商品选择功能使用说明

## 概述

商品选择功能现在支持通过最后一列的"选择"按钮来控制单选和多选模式，提供了更直观的用户体验。

## 功能特性

### 单选模式
- 表格最后一列显示蓝色的"选择"按钮
- 点击任意商品的"选择"按钮即可直接完成选择并关闭弹窗
- 适用于奖品商品选择等单选场景

### 多选模式
- 表格最后一列显示绿色的"选择"按钮
- 点击"选择"按钮后变为红色的"取消选择"按钮
- 可以选择多个商品，底部显示已选择数量
- 支持最大选择数量限制
- 适用于营销活动参与商品等多选场景

## 使用方法

### 1. JavaScript调用

#### 单选模式
```javascript
Fast.api.open('shop/goods/select?selectMode=single', '选择商品', {
    callback: function(data) {
        if (data.length > 0) {
            var goods = data[0];
            console.log('选中的商品:', goods);
            // 处理选中的商品
        }
    }
});
```

#### 多选模式
```javascript
Fast.api.open('shop/goods/select?selectMode=multiple', '选择商品', {
    callback: function(data) {
        if (data.length > 0) {
            console.log('选中的商品列表:', data);
            // 处理选中的商品列表
        }
    }
});
```

#### 多选模式（带数量限制）
```javascript
Fast.api.open('shop/goods/select?selectMode=multiple&maxSelect=5', '选择商品（最多5个）', {
    callback: function(data) {
        if (data.length > 0) {
            console.log('选中的商品列表:', data);
            // 处理选中的商品列表
        }
    }
});
```

### 2. 使用activity.js中的封装方法

```javascript
// 单选商品（奖品场景）
Controller.api.selectPrizeGoods('#prize-goods-container');

// 多选商品（任务场景）
Controller.api.selectTaskGoods('#task-goods-container');

// 通用商品选择
Controller.api.selectGoods({
    mode: 'single',           // 'single' 或 'multiple'
    title: '选择商品',
    container: '#selected-goods',
    maxSelect: 0,             // 最大选择数量，0表示无限制
    callback: function(data) {
        // 处理选中的商品
    }
});
```

## URL参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| selectMode | string | multiple | 选择模式：single(单选) 或 multiple(多选) |
| maxSelect | number | 0 | 最大选择数量，仅在多选模式下有效，0表示无限制 |

## 界面说明

### 选择模式提示
- 页面顶部会显示当前的选择模式（单选/多选）和操作提示
- 单选模式：提示"单击任意商品的'选择'按钮即可完成选择"
- 多选模式：提示"点击商品的'选择'按钮添加到选择列表，再次点击可取消选择"

### 按钮状态
- **单选模式**：蓝色"选择"按钮，点击后直接完成选择
- **多选模式**：
  - 未选择：绿色"选择"按钮
  - 已选择：红色"取消选择"按钮
  - 达到数量限制：未选择的按钮变为禁用状态

### 确认按钮
- 单选模式：保留传统的确认按钮作为备选方案
- 多选模式：确认按钮显示已选择的商品数量，如"确认选择 (3)"

## 界面变更

相比之前的版本，新版本有以下重要变更：
- **完全移除**了传统的checkbox/radio选择列
- **专用按钮选择**：只通过操作列的选择按钮进行选择
- **更简洁界面**：减少不必要的列，界面更加简洁
- **更直观操作**：按钮状态和颜色直观反映选择状态

## 注意事项

1. **专用按钮选择**：只能通过操作列的选择按钮进行选择，不再支持点击行或checkbox方式
2. **单选直接选择**：单选模式下点击"选择"按钮会直接关闭弹窗，无需再点击确认按钮
3. **多选状态保持**：多选模式下表格刷新、搜索、分页后选择状态会自动保持
4. **按钮状态反馈**：通过按钮颜色和图标直观显示选择状态（绿色=可选，红色=已选）
5. **模式选择**：建议根据业务场景选择合适的选择模式和数量限制
6. **确认按钮逻辑**：单选模式隐藏确认按钮，多选模式显示确认按钮并显示选择数量

## 示例场景

- **奖品选择**：使用单选模式，用户点击即可快速选择奖品
- **营销活动参与商品**：使用多选模式，允许选择多个参与商品
- **优惠券适用商品**：使用多选模式，并设置合理的数量限制

## 显示样式

**注意：单选和多选模式现在使用相同的显示样式模板**

### 单选模式显示（奖品商品）
```
┌─────────────────────────────────────────────────┐
│ [图片] [标签]商品名称                      删除    │
│        ¥价格  [单规格/多规格]                     │
│        编码: xxx | 分类: xxx | 类型: xxx         │
└─────────────────────────────────────────────────┘
```

### 多选模式显示（任务商品）
```
┌─────────────────────────────────────────────────┐
│ [图片] [标签]商品名称1                     删除    │
│        ¥价格1  [单规格/多规格]                    │
│        编码: xxx | 分类: xxx | 类型: xxx         │
├─────────────────────────────────────────────────┤
│ [图片] [标签]商品名称2                     删除    │
│        ¥价格2  [单规格/多规格]                    │
│        编码: xxx | 分类: xxx | 类型: xxx         │
├─────────────────────────────────────────────────┤
│ [图片] [标签]商品名称3                     删除    │
│        ¥价格3  [单规格/多规格]                    │
│        编码: xxx | 分类: xxx | 类型: xxx         │
└─────────────────────────────────────────────────┘
```

## 商品信息显示说明

### 商品标签
系统会根据商品属性自动显示相应的彩色标签：

- **密** - 虚拟商品（type=2）
- **荐** - 推荐商品（isrecom=1）
- **热** - 热门商品（ishot=1）
- **新** - 新品（isnew=1）

### 规格类型标签
- **单规格** - 蓝色标签，商品只有一种规格
- **多规格** - 橙色标签，商品有多种规格选择

### 商品类型
- **普通商品** - 实体商品，需要物流配送
- **虚拟商品** - 虚拟商品，如卡密、服务等
- **服务商品** - 服务类商品

### 其他信息
- **编码** - 商品的唯一编码标识
- **分类** - 商品所属的分类名称
- **价格** - 商品销售价格，红色加粗显示

## 表单字段

**注意：模板会根据选择的商品数量自动判断字段名**

### 单选模式（选择1个商品）
选中的商品会生成以下隐藏字段：
```html
<input type="hidden" name="goods_id" value="商品ID" />
```

### 多选模式（选择多个商品）
选中的商品会生成以下隐藏字段：
```html
<input type="hidden" name="task_goods_ids[]" value="商品ID1" />
<input type="hidden" name="task_goods_ids[]" value="商品ID2" />
<input type="hidden" name="task_goods_ids[]" value="商品ID3" />
```

## 高级用法

### 自定义配置
```javascript
Controller.api.selectGoods({
    mode: 'single',              // 选择模式：single/multiple
    title: '自定义标题',          // 弹窗标题
    container: '#my-container',   // 显示容器
    template: 'my-template',      // 使用的模板
    maxSelect: 5,                 // 最大选择数量（仅多选模式有效），0表示无限制
    callback: function(data) {    // 选择完成后的回调
        console.log('选中的商品：', data);
    }
});
```

### 选择模式控制

系统通过URL参数控制商品选择器的行为：

- `selectMode=single` - 单选模式，显示单选按钮
- `selectMode=multiple` - 多选模式，显示复选框（默认）
- `maxSelect=N` - 最大选择数量限制（仅多选模式有效）

### 常用配置示例

```javascript
// 单选商品（奖品选择）
Controller.api.selectGoods({
    mode: 'single',
    title: '选择奖品商品',
    container: '#prize-goods',
    template: 'goods-list-template'
});

// 多选商品（任务商品，最多3个）
Controller.api.selectGoods({
    mode: 'multiple',
    title: '选择参与商品',
    container: '#task-goods',
    template: 'goods-list-template',
    maxSelect: 3
});

// 无限制多选
Controller.api.selectGoods({
    mode: 'multiple',
    title: '选择商品',
    container: '#goods-list',
    template: 'goods-list-template'
});
```

### 获取已选商品
```javascript
// 获取单选商品ID
var goodsId = $('input[name="goods_id"]').val();

// 获取多选商品ID数组
var taskGoodsIds = [];
$('input[name="task_goods_ids[]"]').each(function() {
    taskGoodsIds.push($(this).val());
});
```

## 模板说明

系统现在统一使用一个商品显示模板：

1. **goods-list-template** - 统一的商品列表模板（支持单选和多选）
2. **prize-goods-template** - 奖品商品模板（已废弃）

**统一使用：** `goods-list-template` 模板，它支持单选和多选两种模式，会根据商品数量自动生成正确的表单字段。

### 模板可用数据字段

模板中每个商品对象包含以下字段：

```javascript
{
    id: '商品ID',
    name: '商品名称',
    title: '商品标题',
    image: '商品图片URL（已处理CDN）',
    price: '商品价格',
    goods_sn: '商品编码',
    spec_type: '规格类型（0=单规格，1=多规格）',
    category: {name: '分类名称'},
    type_name: '商品类型名称',
    type_text: '商品标签文本（热、新、荐、密等）'
}
```

如需自定义显示样式，可以修改对应的模板文件：
`application/admin/view/lottery/activity/scripttpl.html`

## 技术实现

### URL参数控制
选择器通过以下URL参数控制行为：
```
shop/goods/select?selectMode=single           // 单选
shop/goods/select?selectMode=multiple         // 多选
shop/goods/select?selectMode=multiple&maxSelect=5  // 多选，最多5个
```

### Bootstrap Table配置
```javascript
// 单选模式
{
    field: 'state',
    radio: true
}

// 多选模式
{
    checkbox: true
}
```

### 事件监听
```javascript
// 多选数量限制控制
table.on('check.bs.table check-all.bs.table', function (e, row) {
    // 检查选择数量并控制
});
```