FilterBuilder 高级筛选

avue-filter-builder 用于构建包含逻辑关系和规则列表的筛选条件。通过 v-model 获取的值可在业务层转换为后端查询参数。

基础用法

效果预览可直接操作下方示例

正在加载示例…

<template>
  <avue-filter-builder v-model="filter" :fields="fields" @change="handleChange" />
  <p>当前筛选条件：</p>
  <pre>{{ JSON.stringify(filter, null, 2) }}</pre>
</template>

<script setup>
import { ref } from 'vue'

const fields = [
  { label: '订单编号', value: 'orderNo', type: 'text', placeholder: '请输入订单编号' },
  {
    label: '订单状态',
    value: 'status',
    type: 'select',
    options: [
      { label: '待支付', value: 'pending' },
      { label: '处理中', value: 'processing' },
      { label: '已完成', value: 'completed' },
      { label: '已取消', value: 'cancelled' }
    ]
  },
  { label: '订单金额', value: 'amount', type: 'number', precision: 2, step: 10 },
  { label: '创建日期', value: 'createdAt', type: 'daterange' },
  { label: '是否开票', value: 'invoiced', type: 'boolean' }
]

const filter = ref({
  logic: 'and',
  rules: [
    { id: 'status_rule', field: 'status', operator: 'eq', value: 'processing' },
    { id: 'date_rule', field: 'createdAt', operator: 'between', value: ['2026-01-01', '2026-01-31'] }
  ]
})

function handleChange(value) {
  console.log('筛选条件已更新', value)
}
</script>

<style scoped>
pre {
  max-height: 300px;
  padding: 16px;
  overflow: auto;
  color: #d6e4ff;
  background: #1e293b;
  border-radius: 6px;
}
</style>

字段配置

fields 中每一项至少包含 label 与 value。可根据字段类型配置 type、options（或 dicData）、operators、multiple、placeholder、precision、step 等属性。内置支持 text、number、select、date、datetime、daterange、boolean 等常用类型。

const fields = [
  {
    label: '订单状态',
    value: 'status',
    type: 'select',
    options: [
      { label: '待支付', value: 'pending' },
      { label: '已完成', value: 'completed' }
    ],
    operators: ['eq', 'ne', 'in']
  }
]

Attributes

参数	说明	类型	默认值
modelValue / v-model	筛选数据，结构为 { logic, rules }	object	{ logic: 'and', rules: [] }
fields	可筛选字段配置	array	[]
disabled	是否禁用编辑	boolean	false
emptyText	没有筛选条件时的提示文字	string	暂未添加筛选条件

数据结构

{
  logic: 'and', // and：满足全部条件；or：满足任一条件
  rules: [
    {
      id: 'status_rule',
      field: 'status',
      operator: 'eq',
      value: 'pending'
    }
  ]
}

Events

事件名	说明	参数
update:modelValue / change	逻辑关系或规则改变时触发	{ logic, rules }；每次返回新的规则数组

Fields 配置

参数	说明	默认值
label / value	字段显示名 / 唯一字段标识	—
type	text / number / select / boolean / date / datetime / daterange	text
operators	可用运算符数组；支持标识字符串或 { label, value }	按类型使用下表
options / dicData	下拉选项，支持基础值数组或 { label, value } 数组；优先使用 options	[]
multiple	select 字段是否允许多选；in / notIn 也会启用多选	false
placeholder	文本输入框提示	输入值
precision / step	数字输入精度 / 步长	无固定精度 / 1

自定义运算符建议传 { label, value }，以同时明确显示文字和提交标识。内置“不等于”标识为 ne。

类型与运算符

类型	内置运算符	value 结构
text	eq / ne / contains / notContains / isEmpty / isNotEmpty	string
number	eq / ne / gt / gte / lt / lte / isEmpty / isNotEmpty	number；未填写时可为空
select	eq / ne / in / notIn / isEmpty / isNotEmpty	单个选项值；多选时为数组
boolean	eq / ne	boolean
date	eq / lt / gt / isEmpty / isNotEmpty	YYYY-MM-DD 字符串
datetime	eq / lt / gt / isEmpty / isNotEmpty	YYYY-MM-DD HH:mm:ss 字符串
daterange	between / notBetween	起止日期字符串数组

isEmpty / isNotEmpty 隐藏值输入框，提交时业务应忽略该规则的 value。修改字段会重置该规则的运算符和值，修改运算符不会自动转换旧值；从单选切换多选后应保证值与后端约定一致。

当前数据结构是一层 and / or 规则列表，不支持嵌套分组，也不负责生成 SQL 或校验后端字段。接口提交前由业务校验有效字段、运算符和值类型。

Methods 与 Slots

方法	参数	说明
addRule	无	使用第一字段和默认运算符新增规则，并触发更新事件
removeRule	id	按规则 ID 删除，并触发更新事件
clearRules	无	清空规则，保留逻辑关系，并触发更新事件
getValue	无	返回 { logic, rules } 的副本，规则中的数组值也会复制
setValue	{ logic, rules }	规范化并替换条件，同时触发更新事件

通过组件 ref 调用上述方法；disabled 控制界面编辑，不拦截业务代码主动调用方法。组件没有插槽。