# select2-table

**Repository Path**: hu_kang/select2-table

## Basic Information

- **Project Name**: select2-table
- **Description**: select2-table
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-19
- **Last Updated**: 2026-06-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Select2 表格多选组件

基于 jQuery + Select2 的通用表格下拉多选组件，支持**前端分页**和**后端分页**。

## 文件清单

```
select2-table/
├── demo.html                  ← 示例页面（前端 + 三种后端分页演示）
├── server.js                  ← Node.js 测试接口（可选）
├── jquery-3.7.1.min.js        ← 依赖
├── select2.min.js             ← 依赖
├── select2.min.css            ← 依赖
├── select2-table-dropdown.js  ← 本组件（唯一需要关心的文件）
├── image.png                  ← 前端分页截图
├── image2.png                 ← 后端分页截图
└── README.md
```

## 快速开始

```html
<link href="select2-table/select2.min.css" rel="stylesheet" />
<script src="select2-table/jquery-3.7.1.min.js"></script>
<script src="select2-table/select2.min.js"></script>
<script src="select2-table/select2-table-dropdown.js"></script>

<div id="my-select"></div>

<script>
var inst = createSelect2TableDropdown({
    target: '#my-select',
    data: [
        { id: '1', name: '张三', dept: '技术部', title: '工程师' },
        { id: '2', name: '李四', dept: '产品部', title: '产品经理' }
    ],
    columns: [
        { field: 'name',  title: '姓名' },
        { field: 'dept',  title: '部门' },
        { field: 'title', title: '职位' }
    ],
    textField: 'name',
    pageSize: 10,
    onChange: function(values, texts) {
        console.log('选中的值:', values);   // ['1', '2']
        console.log('选中的文本:', texts);  // ['张三', '李四']
    }
});
</script>
```

## 预览

| 前端分页 | 后端分页（buildParams） |
|----------|------------------------|
| ![前端分页](image.png) | ![后端分页](image2.png) |

## 运行 Demo

```bash
cd select2-table
node server.js
# 浏览器打开 http://localhost:3456
```

页面展示 2×2 网格：前端分页 + 三种后端分页方式。

## 参数说明

### 通用参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `target` | `string\|Element` | — | 挂载容器（必填） |
| `data` | `Array` | `[]` | 数据源（前端分页时必填，后端分页可为空） |
| `columns` | `Array` | 自动推断 | 列定义 `[{ field, title }]` |
| `textField` | `string` | 第一列的 field | 输入框中显示的文本字段 |
| `idField` | `string` | `'id'` | ID 字段名 |
| `placeholder` | `string` | `'请选择'` | 占位文字 |
| `width` | `string` | `'100%'` | 组件宽度 |
| `pageSize` | `number` | `10` | 每页条数 |
| `value` | `string\|Array` | `[]` | 初始选中值 |
| `onChange` | `function` | — | 值变化回调 `fn(values[], texts[])` |

### 后端分页参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `serverSide` | `boolean` | `false` | 启用后端分页 |
| `url` | `string` | `''` | 接口地址 |
| `method` | `string` | `'GET'` | 请求方式 |
| `params` | `object\|function` | `{}` | 额外固定参数 |
| `dataField` | `string` | `'data'` | 响应中数据数组的字段名 |
| `totalField` | `string` | `'total'` | 响应中总条数的字段名 |
| `paramNames` | `object` | 见下 | 请求参数字段名映射 |
| `buildParams` | `function` | — | ⭐ 推荐 — 完全自定义请求参数 |
| `request` | `function` | — | 完全接管请求逻辑 |

`paramNames` 默认值：`{ page: 'page', pageSize: 'pageSize', keyword: 'keyword' }`

## API

| 方法 | 说明 |
|------|------|
| `inst.getValue()` | 获取选中值数组 |
| `inst.setValue(vals)` | 设置选中值 |
| `inst.clear()` | 清空所有选择 |

## 后端分页三种方式

### ⭐ 推荐：buildParams

```js
serverSide: true,
url: '/api/users',
buildParams: function(page, pageSize, keyword) {
    return {
        pageIndex: page,     // 字段名完全自定义
        limit: pageSize,
        search: keyword,
        type: 'active'       // 可加任意固定参数
    };
}
// 发送 → ?pageIndex=1&limit=10&search=&type=active
```

### 方式二：paramNames 字段名映射

适合后端参数结构不变、只是字段名不同的场景。

```js
serverSide: true,
url: '/api/users',
paramNames: { page: 'pageNum', pageSize: 'limit', keyword: 'search' }
// 发送 → ?pageNum=1&limit=10&search=
```

### 方式三：request 完全接管

适合需要 token、自定义 header、错误处理等场景。

```js
serverSide: true,
request: function(params, callback) {
    $.ajax({
        url: '/api/users',
        data: params,
        headers: { 'Authorization': 'Bearer xxx' }
    }).done(function(res) {
        callback(null, res);
    }).fail(function(err) {
        callback(err);
    });
}
```

### 期望响应格式

```json
{
    "data": [
        { "id": "1", "name": "张三", "dept": "技术部" }
    ],
    "total": 100
}
```

`data` 和 `total` 的字段名可通过 `dataField` / `totalField` 自定义。

## 分页说明

- 数据量超过 `pageSize` 时自动显示分页按钮
- 搜索后自动重新分页（只对匹配结果翻页）
- 全选仅选中当前页的可见行
- 关闭下拉再打开，搜索关键字自动重置

## 功能清单

- ✅ 表格下拉多选（复选框）
- ✅ 搜索过滤（前端 or 后端接口）
- ✅ 前端分页 / 后端分页
- ✅ 分页按钮 + 总数显示
- ✅ 全选（当前页）
- ✅ 一键清除按钮
- ✅ `columns` 自定义列
- ✅ `textField` / `idField` 自定义字段映射
- ✅ 多实例互不干扰
- ✅ `onChange` 回调
- ✅ 后端分页请求参数完全自定义