筛选插件

VTable 提供了功能强大的筛选插件，支持按值筛选和按条件筛选两种模式，帮助用户快速过滤和查找表格数据。

功能特性

按值筛选：从列的所有唯一值中选择要显示的数据
按条件筛选：使用操作符设置筛选条件（等于、大于、包含等）
多种操作符：支持文本、数值、布尔值等不同类型的筛选操作
列级别控制：可以为特定列启用或禁用筛选功能
状态持久化：支持筛选状态的保存和恢复
智能图标：自动显示筛选状态图标

筛选插件配置选项

FilterPlugin 筛选插件可以配置以下参数：

export interface FilterOptions {
  /** 筛选器 ID，用于唯一标识筛选器 */
  id?: string;
  /** 筛选器图标 */
  filterIcon?: VTable.TYPES.ColumnIconOption;
  /** 筛选器激活图标 */
  filteringIcon?: VTable.TYPES.ColumnIconOption;
  /** 筛选功能启用钩子函数，返回指定列是否启用筛选功能 */
  enableFilter?: (field: number | string, column: VTable.TYPES.ColumnDefine) => boolean;
  /** 默认是否启用筛选（当 enableFilter 未定义时使用） */
  defaultEnabled?: boolean;
  /** 筛选模式：按值筛选、按条件筛选 */
  filterModes?: FilterMode[];
  /**
   * 筛选器样式
   * 如果样式配置更新, 需在更新图表之前额外调用 `filterPlugin.updateStyles`
   * */
  styles?: FilterStyles;
  /** 自定义筛选分类 */
  conditionCategories?: FilterOperatorCategoryOption[];
  /** 自定义筛选选项展示格式 */
  checkboxItemFormat?: (rawValue: any, formatValue: any) => any;
  /** 多个筛选器之间是否联动
   * @default true
   */
  syncFilterItemsState?: boolean;
  /** 筛选记录结束回调 */
  onFilterRecordsEnd?: (records: any[]) => void;
}

配置参数说明

参数名	类型	默认值	说明
`id`	string	`filter-${Date.now()}`	插件实例唯一标识符
`filterIcon`	ColumnIconOption	默认筛选图标	未激活状态的筛选图标
`filteringIcon`	ColumnIconOption	默认激活图标	激活状态的筛选图标
`enableFilter`	function	-	自定义列筛选启用逻辑
`defaultEnabled`	boolean	true	默认是否启用筛选
`filterModes`	FilterMode[]	['byValue', 'byCondition']	支持的筛选模式
`styles`	FilterStyles	-	自定义筛选器样式
`conditionCategories`	FilterOperatorCategoryOption[]	-	自定义筛选分类
`checkboxItemFormat`	(rawValue: any, formatValue: any) => any	-	自定义筛选选项展示格式
`syncFilterItemsState`	boolean	true	多个筛选器之间是否联动
`onFilterRecordsEnd`	(records: any[]) => void	-	筛选记录结束回调

筛选操作符

插件支持以下筛选操作符：

通用操作符

equals - 等于
notEquals - 不等于

数值操作符

greaterThan - 大于
lessThan - 小于
greaterThanOrEqual - 大于等于
lessThanOrEqual - 小于等于
between - 介于
notBetween - 不介于

文本操作符

contains - 包含
notContains - 不包含
startsWith - 开始于
notStartsWith - 不开始于
endsWith - 结束于
notEndsWith - 不结束于

布尔操作符

isChecked - 已选中
isUnchecked - 未选中

使用示例

基本使用

import * as VTable from '@visactor/vtable';
import { FilterPlugin } from '@visactor/vtable-plugins';

// 创建筛选插件
const filterPlugin = new FilterPlugin({});

// 创建表格配置
const option = {
  records: data,
  columns: [
    { field: 'name', title: '姓名', width: 120 },
    { field: 'age', title: '年龄', width: 100 },
    { field: 'department', title: '部门', width: 150 },
    { field: 'salary', title: '薪资', width: 120 }
  ],
  plugins: [filterPlugin]
};

// 创建表格实例
const tableInstance = new VTable.ListTable(document.getElementById('container'), option);

高级配置

// 自定义筛选启用逻辑
const filterPlugin = new FilterPlugin({
  // 自定义哪些列启用筛选
  enableFilter: (field, column) => {
    // ID 列不启用筛选
    return field !== 'id' && column.title;
  },

  // 只启用按值筛选
  filterModes: ['byValue'],

  // 自定义图标
  filterIcon: {
    name: 'custom-filter',
    type: 'svg',
    width: 16,
    height: 16,
    svg: '<svg>...</svg>'
  }
});

列级别筛选控制

const columns = [
  { field: 'name', title: '姓名', width: 120 }, // 默认启用筛选
  { field: 'age', title: '年龄', width: 100, filter: false }, // 禁用筛选
  { field: 'department', title: '部门', width: 150 } // 默认启用筛选
];

状态持久化

// 获取当前筛选状态
const filterState = filterPlugin.getFilterState();

// 保存到本地存储
localStorage.setItem('tableFilterState', JSON.stringify(filterState));

// 从本地存储恢复
const savedState = JSON.parse(localStorage.getItem('tableFilterState'));
if (savedState) {
  filterPlugin.setFilterState(savedState);
}