QueryFilter 查询过滤器

一个基于配置的查询过滤器组件，支持多种类型的查询条件。

功能特点

• 支持多种查询类型：input(输入框)、inputNumber(数字范围)、date(日期)、dateTime(日期时间)、dateRange(日期范围)、dateTimeRange(日期时间范围)、select(选择器)、apiSelect(远程搜索选择器)
• 支持自定义查询条件布局
• 支持展开/收起功能
• 支持重置和查询操作
• 支持自定义样式和宽度

基础用法

文档中宽度可能会显示挤压。容器宽度合适下不会出现此情况

姓名

状态

请选择状态

搜索值： { "name": "", "age": [], "date": "", "time": "", "datetime": "", "multiple": [], "dateTimeRange": [] }

改为切换/enter搜索

复制代码

查看代码

<template>
 <s-query-filter
      :fields="fields"
      :values="searchValues"
      :col="8"
      @search="handleSearch"
      :search-when-change="searchWhenChange"
    />
    <a-flex vertical :gap="10">
      <a-space> 搜索值： {{ searchValues }} </a-space>
      <a-space>
        改为切换/enter搜索
        <a-switch v-model:checked="searchWhenChange" />
      </a-space>
    </a-flex>
</template>

<script setup lang="ts">
import { ref, computed } from "vue";
import type { IFieldType } from "@/components/QueryFilter/type";
import { message } from "ant-design-vue";
const searchWhenChange = ref(false);
// 搜索配置
const fields = computed<IFieldType[]>(() => {
  return [
    {
      label: "姓名",
      fieldKey: "name",
      fieldType: "input",
      props: {
        placeholder: "请输入姓名",
      },
    },
    {
      label: "状态",
      fieldKey: "status",
      fieldType: "select",
      props: {
        options: [
          { label: "处理中", value: "1" },
          { label: "已完成", value: "2" },
          { label: "已取消", value: "3" },
        ],
      },
    },
    {
      label: "年龄",
      fieldKey: "age",
      fieldType: "inputNumber",
      props: {
        placeholder: "请输入年龄",
      },
    },
    {
      label: "用户",
      fieldKey: "user",
      fieldType: "apiSelect",
      props: {
        placeholder: "请选择用户",
        fetchOptions: {
          params: {
            page: 1,
            pageSize: 10,
          },
          // key为必须值
          search: {
            key: "name",
          },
          // 支持自行处理结构
          afterRes: (res: any[]) => {
            return res.map((item: any) => ({
              label: item.name,
              value: item.id,
            }));
          },
        },
        fetchFunc: async (params: any) => {
          // 模拟远程搜索(默认会处理 { data: []},这种响应)
          return new Promise((resolve) => {
            setTimeout(() => {
              resolve({
                data: params?.name
                  ? [
                      { name: "用户1", id: "1" },
                      { name: "用户2", id: "2" },
                      { name: "用户3", id: "3" },
                    ].filter((item) => item.name.includes(params.name))
                  : [
                      { name: "用户1", id: "1" },
                      { name: "用户2", id: "2" },
                      { name: "用户3", id: "3" },
                    ],
              });
            }, 500);
          });
        },
        fieldNames: {
          label: "label",
          value: "value",
        },
      },
    },
    {
      label: "日期",
      fieldKey: "date",
      fieldType: "date",
    },
    {
      label: "时间",
      fieldKey: "time",
      fieldType: "time",
      props: {
        valueFormat: "HH:mm:ss",
      },
    },
    {
      fieldKey: "datetime",
      label: "日期时间",
      fieldType: "dateTime",
      props: {
        valueFormat: "YYYY-MM-DD HH:mm:ss",
      },
    },
    {
      fieldKey: "dateTimeRange",
      label: "日期时间范围",
      fieldType: "dateTimeRange",
      props: {
        valueFormat: "YYYY-MM-DD HH:mm:ss",
      },
    },
    {
      fieldKey: "multiple",
      label: "多选",
      fieldType: "select",
      props: {
        mode: "multiple",
        options: [
          { label: "选项1", value: "1" },
          { label: "选项2", value: "2" },
          { label: "选项3", value: "3" },
        ],
      },
    },
  ];
});

// 默认搜索条件
const searchValues = ref<Record<string, any>>({
  name: "",
  age: [],
  status: undefined,
  user: undefined,
  date: "",
  time: "",
  datetime: "",
  multiple: [],
  dateTimeRange: [],
});

// 搜索回调
const handleSearch = (values: Record<string, any>) => {
  console.log("搜索条件:", values);
  searchValues.value = values;
  // TODO: 搜索逻辑
  message.success("触发搜素");
};
</script>

简洁版

请选择状态

-

搜索值： { "name": "", "age": [], "date": "", "time": "", "datetime": "", "multiple": [], "dateTimeRangeStart": "", "dateTimeRangeEnd": "" }

某些少量搜索场景

复制代码

查看代码

<template>
 <s-query-filter
      :fields="fields"
      :values="lettleSearchMode ? searchValues2 : searchValues"
      @search="handleSearch"
      mode="simple"
      :showOpt="!lettleSearchMode"
      :search-when-change="true"
    />
    <a-flex vertical :gap="10">
      <a-space v-if="lettleSearchMode"> 搜索值： {{ searchValues2 }} </a-space>
      <a-space v-else> 搜索值： {{ searchValues }} </a-space>
      <a-space>
        某些少量搜索场景
        <a-switch v-model:checked="lettleSearchMode" />
      </a-space>
    </a-flex>
</template>

<script setup lang="ts">
import { ref, computed } from "vue";
import type { IFieldType } from "@/components/QueryFilter/type";
import { message } from "ant-design-vue";
const lettleSearchMode = ref(false);
// 搜索配置
const fields = computed<IFieldType[]>(() => {
  if (lettleSearchMode.value) {
    // 一些少量搜素
    return [
      {
        label: "状态",
        fieldKey: "status",
        fieldType: "select",
        props: {
          options: [
            { label: "处理中", value: "1" },
            { label: "已完成", value: "2" },
            { label: "已取消", value: "3" },
          ],
        },
      },
      {
        label: "姓名",
        fieldKey: "name",
        fieldType: "input",
        props: {
          placeholder: "请输入姓名",
          itemWidth: 200,
          hasSearchIcon: true,
          whenChangeTrigger: "input", // 修改触发方式为输入
        },
      },
    ];
  }
  return [
    {
      label: "姓名",
      fieldKey: "name",
      fieldType: "input",
      props: {
        placeholder: "请输入姓名",
      },
    },
    {
      label: "状态",
      fieldKey: "status",
      fieldType: "select",
      props: {
        options: [
          { label: "处理中", value: "1" },
          { label: "已完成", value: "2" },
          { label: "已取消", value: "3" },
        ],
      },
    },
    {
      label: "年龄",
      fieldKey: "age",
      fieldType: "inputNumber",
      props: {
        placeholder: "请输入年龄",
      },
    },
    {
      label: "用户",
      fieldKey: "user",
      fieldType: "apiSelect",
      props: {
        placeholder: "请选择用户",
        fetchOptions: {
          params: {
            page: 1,
            pageSize: 10,
          },
          // key为必须值
          search: {
            key: "name",
          },
          // 支持自行处理结构
          afterRes: (res: any) => {
            return res.data.map((item: any) => ({
              label: item.name,
              value: item.id,
            }));
          },
        },
        fetchFunc: async (params: any) => {
          // 模拟远程搜索(默认会处理 { data: []},这种响应)
          return new Promise((resolve) => {
            setTimeout(() => {
              resolve({
                data: params?.name
                  ? [
                      { name: "用户1", id: "1" },
                      { name: "用户2", id: "2" },
                      { name: "用户3", id: "3" },
                    ].filter((item) => item.name.includes(params.name))
                  : [
                      { name: "用户1", id: "1" },
                      { name: "用户2", id: "2" },
                      { name: "用户3", id: "3" },
                    ],
              });
            }, 500);
          });
        },
        fieldNames: {
          label: "label",
          value: "value",
        },
      },
    },
    {
      label: "日期",
      fieldKey: "date",
      fieldType: "date",
    },
    {
      label: "时间",
      fieldKey: "time",
      fieldType: "time",
      props: {
        valueFormat: "HH:mm:ss",
      },
    },
    {
      fieldKey: "datetime",
      label: "日期时间",
      fieldType: "dateTime",
      props: {
        valueFormat: "YYYY-MM-DD HH:mm:ss",
      },
    },
    {
      fieldKey: "dateTimeRange",
      label: "日期时间范围",
      fieldType: "dateTimeRange",
      props: {
        valueFormat: "YYYY-MM-DD HH:mm:ss",
        transform2Params: ["dateTimeRangeStart", "dateTimeRangeEnd"],
      },
    },
    {
      fieldKey: "multiple",
      label: "多选",
      fieldType: "select",
      props: {
        mode: "multiple",
        options: [
          { label: "选项1", value: "1" },
          { label: "选项2", value: "2" },
          { label: "选项3", value: "3" },
        ],
      },
    },
  ];
});

// 默认搜索条件
const searchValues = ref<Record<string, any>>({
  name: "",
  age: [],
  status: undefined,
  user: undefined,
  date: "",
  time: "",
  datetime: "",
  multiple: [],
  dateTimeRangeStart: "",
  dateTimeRangeEnd: "",
});
const searchValues2 = ref<Record<string, any>>({
  name: "",
  status: undefined,
  user: undefined,
});
// 搜索回调
const handleSearch = (values: Record<string, any>) => {
  console.log("搜索条件:", values);
  if (lettleSearchMode.value) {
    searchValues2.value = values;
  } else {
    searchValues.value = values;
  }
  // TODO: 搜索逻辑
  message.success("触发搜素");
};
</script>

复合版(特定场景)

提示

此模式下，参数配置相对固定(最好与后端协商字段)。与普通搜索组件有以下区别
1.内置了组件连接符类型匹配（见尾部）
2.搜索出参/默认参数设置结构为对象数组形式。{fieldKey: 字段名, fieldVal: 字段值,fieldRel: 连接条件}[]

姓名

包含

状态

等于

请选择状态

搜索值： []

复制代码

查看代码

<template>
 <s-query-filter
      :fields="fields"
      :values="searchValues"
      :col="8"
      @search="handleSearch"
      mode="complex"
      :search-when-change="searchWhenChange"
    />
    <a-flex vertical :gap="10">
      <a-space> 搜索值： {{ searchValues }} </a-space>
    </a-flex>
</template>

<script setup lang="ts">
import { ref, computed } from "vue";
import type { IFieldType } from "@/components/QueryFilter/type";
import { message } from "ant-design-vue";
const searchWhenChange = ref(false);
// 搜索配置
const fields = computed<IFieldType[]>(() => {
  return [
    {
      label: "姓名",
      fieldKey: "name",
      fieldType: "input",
      fieldRel: "search",
      props: {
        placeholder: "请输入姓名",
      },
    },
    {
      label: "状态",
      fieldKey: "status",
      fieldType: "select",
      props: {
        options: [
          { label: "处理中", value: "1" },
          { label: "已完成", value: "2" },
          { label: "已取消", value: "3" },
        ],
      },
    },
    {
      label: "年龄",
      fieldKey: "age",
      fieldType: "inputNumber",
      props: {
        placeholder: "请输入年龄",
      },
    },
    {
      label: "用户",
      fieldKey: "user",
      fieldType: "apiSelect",
      props: {
        placeholder: "请选择用户",
        fetchOptions: {
          params: {
            page: 1,
            pageSize: 10,
          },
          // key为必须值
          search: {
            key: "name",
          },
          // 支持自行处理结构
          afterRes: (res: any) => {
            return res.data.map((item: any) => ({
              label: item.name,
              value: item.id,
            }));
          },
        },
        fetchFunc: async (params: any) => {
          // 模拟远程搜索(默认会处理 { data: []},这种响应)
          return new Promise((resolve) => {
            setTimeout(() => {
              resolve({
                data: params?.name
                  ? [
                      { name: "用户1", id: "1" },
                      { name: "用户2", id: "2" },
                      { name: "用户3", id: "3" },
                    ].filter((item) => item.name.includes(params.name))
                  : [
                      { name: "用户1", id: "1" },
                      { name: "用户2", id: "2" },
                      { name: "用户3", id: "3" },
                    ],
              });
            }, 500);
          });
        },
        fieldNames: {
          label: "label",
          value: "value",
        },
      },
    },
    {
      label: "日期",
      fieldKey: "date",
      fieldType: "date",
    },
    {
      label: "时间",
      fieldKey: "time",
      fieldType: "time",
      props: {
        valueFormat: "HH:mm:ss",
      },
    },
    {
      fieldKey: "datetime",
      label: "日期时间",
      fieldType: "dateTime",
      props: {
        valueFormat: "YYYY-MM-DD HH:mm:ss",
      },
    },
    {
      fieldKey: "dateTimeRange",
      label: "日期时间范围",
      fieldType: "dateTimeRange",
      props: {
        valueFormat: "YYYY-MM-DD HH:mm:ss",
      },
    },
    {
      fieldKey: "multiple",
      label: "多选",
      fieldType: "select",
      props: {
        mode: "multiple",
        options: [
          { label: "选项1", value: "1" },
          { label: "选项2", value: "2" },
          { label: "选项3", value: "3" },
        ],
      },
    },
  ];
});

// 搜索条件
const searchValues = ref<Record<string, any>>([]);

// 搜索回调
const handleSearch = (values: Record<string, any>) => {
  console.log("搜索条件:", values);
  searchValues.value = values;
  // TODO: 搜索逻辑
  message.success("触发搜素");
};
</script>

API

Props

参数	说明	类型	默认值
fields	查询字段配置	IFieldType[]	[]
values	查询值	Record<string, any>	{}
col	每行显示的列数（24的约数）,简易模式下无效	number	6
gutter	列间距	number	20
showOpt	是否显示操作按钮	boolean	true

IFieldType 类型

type IFieldType = {
  label: string; // 字段标签
  fieldKey: string; // 字段标识
  fieldRel?: string; // 条件连接符
  fieldType:
    | "input"
    | "time"
    | "inputNumber"
    | "select"
    | "apiSearch"
    | "dateRange"
    | "dateTimeRange"
    | "date"
    | "dateTime"; // 字段类型
  props?: IPropType; // 字段属性
};

IPropType 类型

type IFetchOptions = {
  params?: Record<string, any>;
  afterRes?: Function;
};
type IPropType = {
  placeholder?: string | string[]; // 占位符
  options?: DefaultOptionType[]; // 选项列表（select类型）
  searchWhenChange?: boolean; // 值变化时是否触发搜索
  itemWidth?: number; // 表单项宽度
  showSearch?: boolean; // 是否显示搜索框（select类型）
  transform2Params?: string[]; // 值转换（范围类型）
  valueFormat?: string; // 日期格式
  mode?: "multiple"; // select 的模式
  whenChangeTrigger?: "input"; // 触发方式(input生效)
  hasSearchIcon?: boolean; // 是否显示搜索图标
  fieldNames?: { label: string; value: string }; // 字段映射（selectSearch类型）
  fetchOptions?: IFetchOptions; // 远程搜索配置
  fetchFunc?: Function; // 远程搜索方法（selectSearch类型）
  search?: {
    key: string // 搜索字段名
  }
};

Events

事件名	说明	回调参数
search	点击查询按钮时触发	(values: Record<string, any>)

注意事项

1. col 属性必须是 24 的约数（如：6、8、12、24）
2. 日期类型支持自定义格式，默认格式：
   • 日期：YYYY-MM-DD
   • 日期时间：YYYY-MM-DD HH:mm:ss
3. 范围类型（日期范围、数字范围）支持值转换（如果后端是采用的两个值存储），通过 transform2Params 配置，如：createTime => ['createTimeStart','createTimeEnd']
4. 选择器类型支持远程搜索，通过 fetchFunc 和 fetchOptions 配置

内置连接匹配规则

组件内置了以下类型的连接符匹配规则：

文本类型 (input)

• 包含 (search)
• 等于 (eq)
• 不等于 (neq)
• 开头是 (startWith)

数字类型 (inputNumber)

• 范围 (scope)
• 等于 (eq)
• 不等于 (neq)
• 大于 (gt)
• 小于 (lt)
• 大于等于 (gte)
• 小于等于 (lte)

日期类型 (date, dateTime, time)

• 范围 (scope)
• 等于 (eq)
• 不等于 (neq)
• 早于 (gt)
• 晚于 (lt)

日期范围类型 (dateRange, dateTimeRange, timeRange)

• 等于 (eq)
• 不等于 (neq)

单选类型 (select, apiSelect)

• 等于 (eq)
• 不等于 (neq)

多选类型 (selectMultiple)

• 等于任意一个 (in)
• 不等于任意一个 (nin)

提示

1.你可以通过传入props下relOptions对内置连接项进行覆盖（这里仅支持包含在已有连接项的选项传入，自定义项无效）
2. 对于 select 和 apiSelect 类型，当设置 props.mode="multiple" 时，会自动使用多选类型的连接符规则
3. number,select 传入的relOptions 需添加defaultValue,

完整的relOptions:

// ["input"]
[
  { value: "search", label: "包含" },
  { value: "eq", label: "等于" },
  { value: "neq", label: "不等于" },
  { value: "startWith", label: "开头是" },
],
  // ["inputNumber"]
  [
    { value: "scope", label: "范围", defaultValue: [] },
    { value: "eq", label: "等于", defaultValue: undefined },
    { value: "neq", label: "不等于", defaultValue: undefined },
    { value: "gt", label: "大于", defaultValue: undefined },
    { value: "lt", label: "小于", defaultValue: undefined },
    { value: "gte", label: "大于等于", defaultValue: undefined },
    { value: "lte", label: "小于等于", defaultValue: undefined },
  ],
  // ["selectMultiple"]
  [
    { value: "eq", label: "等于" },
    { value: "neq", label: "不等于" },
  ],
  // ["date", "dateTime", "time"], 这里需要传入defaultValue
  [
    { value: "scope", label: "范围", defaultValue: [] },
    { value: "eq", label: "等于", defaultValue: undefined },
    { value: "neq", label: "不等于", defaultValue: undefined },
    { value: "gt", label: "早于", defaultValue: undefined },
    { value: "lt", label: "晚于", defaultValue: undefined },
  ],
  // ["select", "apiSelect"]
  [
    { value: "eq", label: "等于" },
    { value: "neq", label: "不等于" },
  ],
  //["dateRange", "dateTimeRange", "timeRange"]
  [
    { value: "eq", label: "等于" },
    { value: "neq", label: "不等于" },
  ];