fastadmin_tailored/docs/商品选择功能使用说明.md

商品选择功能使用说明

概述

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

功能特性

单选模式

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

多选模式

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

使用方法

1. JavaScript调用

单选模式

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

多选模式

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

多选模式（带数量限制）

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

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

// 单选商品（奖品场景）
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个商品）

选中的商品会生成以下隐藏字段：

<input type="hidden" name="goods_id" value="商品ID" />

多选模式（选择多个商品）

选中的商品会生成以下隐藏字段：

<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" />

高级用法

自定义配置

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 - 最大选择数量限制（仅多选模式有效）

常用配置示例

// 单选商品（奖品选择）
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'
});

获取已选商品

// 获取单选商品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 模板，它支持单选和多选两种模式，会根据商品数量自动生成正确的表单字段。

模板可用数据字段

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

{
    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配置

// 单选模式
{
    field: 'state',
    radio: true
}

// 多选模式
{
    checkbox: true
}

事件监听

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