# layui表格列筛选示例扩展
**Repository Path**: qaz1123/table-filter
## Basic Information
- **Project Name**: layui表格列筛选示例扩展
- **Description**: layui表格列筛选示例
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-24
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# tableFilter - layui 表格列筛选扩展
## 实列展示
为 layui table 提供类似 Excel 的列内容筛选功能，支持多选、搜索、多表格实例。
## 功能特点
- ✅ 支持多表格实例，每个表格独立管理筛选状态
- ✅ 支持列内容多选筛选
- ✅ 支持关键字搜索过滤选项
- ✅ 支持全选、清空、反选操作
- ✅ 筛选后自动重载表格数据
- ✅ 支持手动设置/获取筛选条件
- ✅ 筛选图标激活状态高亮显示
- ✅ 支持客户端数据(data)和服务端数据(url)两种模式
- ✅ 更多功能请自行拓展
## 目录结构
```
table-filter/
├── js/
│ ├── lay-module/
│ │ ├── tableFilter/
│ │ │ ├── tableFilter.js # 核心文件
│ │ │ └── tableFilter.css # 样式文件
│ │ ├── searchFormTpl/
│ │ │ ├── searchFormTpl.js # 搜索表单模板模块
│ │ │ └── searchFormTpl.css # 搜索表单样式
│ │ └── toolbarTpl/
│ │ ├── toolbarTpl.js # 工具栏模板模块
│ │ └── toolbarTpl.css # 工具栏样式
│ └── lay-config.js # layui 扩展配置
├── lib/
│ └── layui-2.13.5/ # layui 框架
├── server.js # Node.js 服务端模拟接口
├── table-filter-demo.html # 客户端数据示例页面
├── search-page.html # 服务端数据示例页面（高级搜索）
└── README.md
```
## 快速开始
### 1. 引入文件
确保已引入 layui 框架，然后在 `lay-config.js` 中配置扩展：
```javascript
layui.config({
base: rootPath + "lay-module/",
version: true
}).extend({
tableFilter: 'tableFilter/tableFilter',
searchFormTpl: 'searchFormTpl/searchFormTpl',
toolbarTpl: 'toolbarTpl/toolbarTpl'
});
```
### 2. 基本使用
在 `table.render` 的 `done` 回调中调用 `tableFilter.render`：
**客户端数据模式（推荐）：**
```javascript
layui.use(['tableFilter', 'table'], function() {
var tableFilter = layui.tableFilter;
var table = layui.table;
var staticData = [
{id: 1, username: '张三', city: '北京', status: '正常'},
{id: 2, username: '李四', city: '上海', status: '正常'}
];
var cols = [[
{field: 'username', title: '用户名', filter: true},
{field: 'city', title: '城市', filter: true},
{field: 'status', title: '状态', filter: true}
]];
table.render({
elem: '#myTable',
id: 'myTable',
data: staticData,
cols: cols,
done: function(res, curr, count) {
tableFilter.render('myTable', cols, {data: staticData});
}
});
});
```
**服务端数据模式：**
```javascript
table.render({
elem: '#myTable',
id: 'myTable',
url: '/api/table-data',
page: true,
cols: cols,
done: function(res, curr, count) {
tableFilter.render('myTable', cols, {url: '/api/table-data'});
}
});
```
### 3. 启用列筛选
只需在列配置中添加 `filter: true` 即可为该列启用筛选功能：
```javascript
var cols = [[
{field: 'name', title: '名称', filter: true}, // 启用筛选
{field: 'status', title: '状态', filter: true}, // 启用筛选
{field: 'email', title: '邮箱'} // 不启用筛选
]];
```
## 启动项目
### 方式一：客户端数据模式（无需启动服务）
直接用浏览器打开 `table-filter-demo.html` 文件即可运行。
```javascript
// 客户端数据模式
tableFilter.render('demoTable1', cols1, {data: staticData});
```
### 方式二：服务端数据模式（需要启动 Node 服务）
**命令行启动：**
```bash
# 进入项目目录
cd table-filter
# 启动服务
node server.js
```
**VSCode 终端启动：**
1. 在 VSCode 中打开终端（Terminal -> New Terminal）
2. 输入以下命令启动服务：
```bash
node server.js
```
启动成功后会显示：
```
Server running at http://localhost:8080/
API endpoint: http://localhost:8080/api/table-data
Demo page: http://localhost:8080/
```
打开浏览器访问 http://localhost:8080/search-page.html
```javascript
// 服务端数据模式
tableFilter.render('dataTableFilter', cols1, {url: '/api/table-data'});
```
## API 文档
### tableFilter.render 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| tableId | String | 是 | 表格ID |
| cols | Array | 是 | 列配置数组 |
| options.data | Array | 否 | 客户端静态数据，与 url 二选一 |
| options.url | String | 否 | 服务端接口地址，与 data 二选一 |
### 方法列表
| 方法 | 参数 | 说明 |
|------|------|------|
| `init(options)` | Object | 初始化表格筛选实例 |
| `render(tableId, cols, options)` | String, Array, Object | 渲染筛选功能，在 table.render 的 done 回调中调用 |
| `clearFilter(tableId)` | String | 清除指定表格的所有筛选条件 |
| `getFilter(tableId)` | String | 获取当前筛选条件，返回 `{field: [values]}` |
| `setFilter(tableId, filterObj)` | String, Object | 手动设置筛选条件并应用 |
| `getInstance(tableId)` | String | 获取表格实例对象 |
| `destroy(tableId)` | String | 销毁实例，不传参数则销毁所有实例 |
### 方法示例
```javascript
// 清除筛选
tableFilter.clearFilter('myTable');
// 获取筛选条件
var filter = tableFilter.getFilter('myTable');
// 返回: {city: ['北京', '上海'], status: ['正常']}
// 设置筛选条件
tableFilter.setFilter('myTable', {city: ['北京', '上海']});
// 销毁实例
tableFilter.destroy('myTable');
```
## 完整示例
### 客户端数据示例（table-filter-demo.html）
```html
表格列筛选示例
```
### 服务端数据示例
```html
表格列筛选示例
```
## 服务端分页
### API 接口说明
| 参数 | 类型 | 说明 |
|------|------|------|
| page | Number | 当前页码 |
| limit | Number | 每页条数 |
| username | String | 用户名搜索（可选） |
**请求示例：**
```
GET /api/table-data?page=1&limit=10&username=用户1
```
**返回格式：**
```json
{
"code": 0,
"msg": "",
"count": 1000,
"data": [
{"id": 1, "username": "用户1", "city": "北京", "status": "正常"},
...
]
}
```
### 服务端分页配合表单搜索
```javascript
form.on('submit(searchForm)', function(data) {
tableFilter.clearFilter('demoTable1'); // 清除列筛选
table.reload('demoTable1', {
url: '/api/table-data',
where: {username: data.field.username},
page: {curr: 1}
});
return false;
});
```
## searchFormTpl 搜索表单模板模块
用于生成头部搜索表单和高级搜索抽屉表单。
### render 方法
渲染头部搜索表单，最多显示4个搜索条件 + 按钮组。
```javascript
/**
* @param {Array} data - 表单配置数据数组
* @param {string} data[].title - 表单项标题
* @param {string} data[].name - 表单项name属性
* @param {string} [data[].type='input'] - 类型：'input'|'select'|'date'|'xm-select'|'btnGroup'
* @param {string} [data[].placeholder] - 占位提示文字
* @param {string} [data[].className] - 自定义CSS类名
* @param {string} [data[].id] - 自定义元素ID
* @param {Array} [data[].options] - 下拉选项数组（select/xm-select类型）
* @param {Object} [data[].xmConfig] - xm-select额外配置
* @param {Array} [data[].buttons] - 按钮组配置（btnGroup类型）
* @param {string|HTMLElement} container - 表单容器
* @param {Function} [callback] - 渲染完成回调
*/
searchFormTpl.render(data, container, callback);
```
### renderDrawer 方法
渲染高级搜索抽屉表单，显示所有搜索条件（不包括按钮组）。
```javascript
searchFormTpl.renderDrawer(data, container, callback);
```
### 使用示例
```javascript
var searchFormData = [
{ title: '用户名', name: 'username', type: 'input' },
{ title: '状态', name: 'status', type: 'select', options: [
{value: '1', text: '正常'},
{value: '2', text: '禁用'}
]},
{ title: '部门', name: 'dept', type: 'xm-select', options: [
{value: '1', text: '技术部'},
{value: '2', text: '市场部'}
]},
{ type: 'btnGroup', buttons: [
{ text: '搜索', className: 'layui-btn', submit: 'searchForm' },
{ text: '重置', className: 'layui-btn layui-btn-primary', id: 'btnReset' },
{ text: '高级搜索', className: 'layui-btn layui-btn-normal', id: 'btnMore' }
]}
];
searchFormTpl.render(searchFormData, '#searchFormContainer', function() {
form.render();
});
searchFormTpl.renderDrawer(searchFormData, '#drawerFormContainer', function() {
form.render();
});
```
## toolbarTpl 工具栏模板模块
用于生成表格工具栏按钮，支持普通按钮和下拉按钮组。
### render 方法
```javascript
/**
* @param {Array} data - 按钮配置数据数组
* @param {string} data[].type - 按钮类型：'btn'|'dropdown'
* @param {string} data[].text - 按钮显示文字
* @param {string} [data[].btnClass] - 按钮CSS类名
* @param {string} [data[].event] - 按钮事件名称
* @param {Array} [data[].items] - 下拉菜单项（dropdown类型）
* @param {string} data[].items[].text - 菜单项文字
* @param {string} data[].items[].event - 菜单项事件
* @param {Function} callback - 渲染完成回调
*/
toolbarTpl.render(data, callback);
```
### 使用示例
```javascript
var toolbarData = [
{ type: "btn", text: "添加", event: "add", btnClass: "layui-btn-xs" },
{ type: "btn", text: "删除", event: "delete", btnClass: "layui-btn-xs layui-btn-danger" },
{
type: "dropdown",
text: "更多操作",
event: "moreAction",
btnClass: "layui-btn-xs",
items: [
{ text: "导出", event: "export" },
{ text: "导入", event: "import" }
]
}
];
toolbarTpl.render(toolbarData, function(html) {
$('.toolbar-container').append(html);
});
```
## 注意事项
1. **数据来源**：
- 客户端模式：使用 `data` 参数传入静态数据
- 服务端模式：使用 `url` 参数指定接口地址
2. **分页支持**：筛选后会自动跳转到第一页
3. **排序兼容**：筛选功能与 layui table 的排序功能兼容
4. **性能建议**：大数据量时建议使用服务端模式
## 依赖
- layui >= 2.x
- layui table 模块
- layui form 模块
- layui layer 模块
- jQuery（layui 内置）
- xm-select（可选，用于多选下拉）
## 浏览器支持
- Chrome
- Firefox
- Safari
- Edge
- IE11+
## 许可证
[MIT](LICENSE)
## 更新日志
### v1.0.0
- 初始版本发布
- 支持多表格实例
- 支持多选筛选、搜索、全选、清空、反选
- 支持手动设置/获取筛选条件
- 支持客户端数据(data)和服务端数据(url)两种模式
- 新增 searchFormTpl 搜索表单模板模块
- 新增 toolbarTpl 工具栏模板模块