组件详情 — smart-filter-vue

FilterField配置驱动分发器

筛选栏每一行的统一入口：按 field.componentType 渲染对应组件，统一透传 props、统一转发事件。优先读 componentType，缺省回退 type，再缺省按 text_input；无法识别时渲染禁用占位。

Props

prop	类型	默认	说明
`field`	Object	必填	字段配置对象（完整键见配置 Schema 文档）
`modelValue`	String / Array / Object / Number / Boolean	—	当前值，配合 v-model；结构随组件类型而定
`disabled`	Boolean	false	是否禁用
`isApplied`	Boolean	false	是否已生效（供外层标记样式）

事件

事件	载荷	说明
`update:modelValue`	同 modelValue	值变化（v-model）
`criteria-change`	Criteria 节点 / null	筛选语义变化，空值为 null
`ai-loading`	Boolean	AI 解析开始/结束（仅 AI 组件）
`ai-error`	Error	AI 解析失败（仅 AI 组件）
`mode-change`	String	输入模式切换（仅 time_calc / number_calc）

用法

<FilterField
  v-model="values[f.field]"
  :field="f"
  @criteria-change="onCriteriaChange(f.field, $event)"
  @mode-change="onModeChange(f.field, $event)"
/>

智能选项 FilterSmartOptionsmart_option

可枚举字段的选择组件：选项来自配置或数据库去重扫描，输入时对已加载选项做本地字面匹配过滤，不查库。自动区分精确（选项内值）与模糊（自定义输入）。

Props

prop	类型	默认	说明
`modelValue`	String / Array	''	单选字符串，多选字符串数组
`field`	String	必填	字段名
`options`	Array	[]	静态选项列表
`optionSource`	Object	{ type: 'static' }	选项来源：static / distinct_scan / api
`multiple`	Boolean	false	是否多选
`likeMode`	String	'multi_like'	multi_like / single_like / no_like
`placeholder`	String	'请选择'	占位符
`disabled`	Boolean	false	是否禁用

事件

事件	载荷	说明
`update:modelValue`	String / Array	值变化
`criteria-change`	节点 / null	operator 自动判定：eq / in / like / mixed

模式与交互

选项合并：distinct_scan 挂载时调 getFieldOptions 加载库中选项；配置多出的项置灰带"配置"标记仍可选；未配置接口时降级为仅配置选项。
本地过滤：输入即对选项做包含匹配（不区分大小写），纯前端，不发请求。
operator 自动判定：全部点选 → eq/in；全部回车自定义 → like；混合 → mixed（value 为 { exact, fuzzy }）。
重名双份：回车输入与选项同名的值仍按 like 处理（弹提示）；精确匹配请下拉点选。
likeMode：single_like 仅允许一个自定义值；no_like 禁止自定义输入。
UI 差异化：精确值蓝色标签、自定义值橙色标签带 🔍；问号面板显示匹配模式与自定义值列表。

配置示例

{
  field: 'department', label: '部门',
  componentType: 'smart_option', operator: 'in',
  options: ['研发部', '市场部', '人事部', '财务部'],
  optionSource: { type: 'static' },
  componentProps: { multiple: true },
}

Criteria 输出

{ field: 'department', componentType: 'smart_option',
  operator: 'mixed', value: { exact: ['研发部'], fuzzy: ['临'] } }

智能文本 FilterTextInputtext_input

文本 LIKE 模糊搜索：防抖调用数据库 LIKE 接口返回参考片段，可点击上屏；无论输入来自手打还是点选，恒为 LIKE。

Props

prop	类型	默认	说明
`modelValue`	String	''	当前文本（参与 LIKE 的值）
`field`	String	''	字段名（为空不发起联想）
`placeholder`	String	''	占位符
`disabled`	Boolean	false	是否禁用
`searchable`	Boolean	true	是否启用数据库联想
`suggestLimit`	Number	5	参考结果条数上限
`debounceMs`	Number	500	输入防抖（毫秒）
`maxLength`	Number	—	最大输入长度
`selectable`	Boolean	true	参考结果是否可点击上屏
`contextBefore`	Number	3	片段前截取字数（传给适配器）
`contextAfter`	Number	8	片段后截取字数（传给适配器）

事件

事件	载荷	说明
`update:modelValue`	String	每次输入同步
`criteria-change`	节点 / null	恒为 like；空文本输出 null

模式与交互

联想：防抖后调 suggestFieldValues(field, keyword, { limit, contextBefore, contextAfter })；请求序列化，旧响应不覆盖新结果。
点击上屏：selectable 默认 true，点击片段填入输入框（自动剔除首尾省略号），仍可修改，仍为 LIKE。
降级：未配置 suggestFieldValues 或 searchable=false 时不弹下拉，输入与输出完全正常。
问号面板：组件介绍、当前关键词、最近搜索关键词、匹配模式（恒 LIKE）、搜索状态。

配置示例

{
  field: 'name', label: '姓名',
  componentType: 'text_input', operator: 'like',
  componentProps: { suggestLimit: 5, debounceMs: 500, selectable: true },
}

智能语义搜索 FilterSemanticSearchsemantic_search

输入关键词，AI 扩充为正向词（包含）与反向词（排除）标签集合，适合"一个词难以概括"的文本字段。

Props

prop	类型	默认	说明
`modelValue`	Object	{ positive: [], negative: [] }	正/反向词集合
`field`	String	必填	字段名
`fieldLabel`	String	''	字段标签（供 AI 理解；FilterField 自动取 label）
`placeholder`	String	'输入关键词，AI自动扩充'	占位符
`disabled`	Boolean	false	是否禁用

事件

事件	载荷	说明
`update:modelValue`	{ positive, negative }	值变化
`criteria-change`	节点 / null	恒为 like；两列均空输出 null
`ai-loading`	Boolean	AI 扩充开始/结束
`ai-error`	Error	AI 扩充失败

模式与交互

触发方式：点击魔法棒 / 回车 / 失焦自动（有文本 + 未生成 + 非解析中）。
魔法棒三态：灰（待生成）→ 蓝旋转（解析中）→ 蓝发光（已生成）；改关键词回到待生成。
标签编辑：正/反向词标签可逐个删除，不可手工添加；面板提供"重新生成"与"清除全部"。
降级：未配置 semanticExpand 时提示"未配置 AI 接口"；输入框联想用 suggestFieldValues（可选）。

配置示例

{
  field: 'skills', label: '技能',
  componentType: 'semantic_search', operator: 'like',
}

Criteria 输出

{ field: 'skills', componentType: 'semantic_search', operator: 'like',
  value: { positive: ['Vue', 'Vue.js'], negative: ['实习'] } }

智能时间计算 FilterTimeCalctime_calc

把"年龄 ≥ 35"这类虚拟字段条件换算成真实日期列区间。AI 对话 / 规则 / 直接三模式共享同一份日期值，自由切换。

Props

prop	类型	默认	说明
`modelValue`	Object	—	{ rawInput, start, end, description, resolved, operator }
`field`	String	必填	字段名（虚拟字段名，如 age）
`targetField`	String	''	真实日期列（如 birth_date）
`targetFieldLabel`	String	''	真实字段标签（直接模式行标签）
`fieldLabel`	String	''	虚拟字段标签（FilterField 自动取 label）
`placeholder`	String	'输入自然语言（如：30岁以上）'	占位符
`disabled`	Boolean	false	是否禁用
`dateType`	String	'month'	year / month / date 精度
`inputMode`	String	'ai_dialog'	初始模式：ai_dialog / expression / direct
`defaultOperator`	String	'gte'	默认算符（取字段配置 operator）
`locale`	String	'zh'	日历语言 zh / en

事件

事件	载荷	说明
`update:modelValue`	Object	值变化
`criteria-change`	节点 / null	V 侧语义节点，含 targetField 与 resolved
`ai-loading` / `ai-error`	Boolean / Error	AI 解析状态
`mode-change`	String	模式切换，外层据此切换行标签（双标签联动）

三种输入模式

AI 对话 ai_dialog：输入自然语言，失焦/回车/魔法棒调 timeParse；面板日历改日期反向调 timeParseReverse 回填文本；改文字则清空已解析日期。
规则 expression：算符下拉 + 数值框，回车/失焦本地规则计算日期范围（不调 AI）。
直接 direct：算符下拉 + 日历选择器直接挑真实字段日期；面板显示虚拟字段表达式（如"年龄 ≥ 35"）。
切换：点击面板左上角模式名循环切换，不触发 AI；expression ↔ 其余两模式时算符自动翻转（V 侧 ⇄ D 侧），日期值保留。
双标签：AI/规则模式行标签为虚拟标签（年龄），直接模式监听 mode-change 切为真实字段标签（出生日期）。
降级：未配置 timeParse 时 AI 对话提示降级；规则/直接模式纯本地始终可用。

配置示例

{
  field: 'age', label: '年龄',
  componentType: 'time_calc', operator: 'gte',
  targetField: 'birth_date', targetFieldLabel: '出生日期',
  componentProps: { dateType: 'month', inputMode: 'ai_dialog', locale: 'zh' },
}

Criteria 输出

{ field: 'age', componentType: 'time_calc', operator: 'gte', value: 35,
  targetField: 'birth_date', fieldLabel: '年龄',
  resolved: { field: 'birth_date', start: null, end: '1991-07' } }

智能数值计算 FilterNumberCalcnumber_calc

数值比较筛选：规则模式（算符 + 1~2 个数值框）与 AI 对话模式（自然语言解析）一键切换。

Props

prop	类型	默认	说明
`modelValue`	Object	—	{ operator: 'eq', value, value2, rawInput: '' }
`field`	String	''	字段名
`fieldLabel`	String	''	字段标签（供 AI 解析）
`placeholder`	String	'输入数值或自然语言'	占位符
`disabled`	Boolean	false	是否禁用
`inputMode`	String	'expression'	expression / ai_dialog
`operators`	Array	全部 6 个	允许的算符；between 始终自动补入

事件

事件	载荷	说明
`update:modelValue`	Object	值变化
`criteria-change`	节点 / null	失焦/回车/AI 落地时发出
`ai-loading` / `ai-error`	Boolean / Error	AI 解析状态
`mode-change`	String	'expression' / 'ai_dialog'

模式与交互

规则模式：算符下拉（> ≥ < ≤ = 区间）+ 数值框；between 时两个数值框 ~ 分隔；失焦清理无效输入。
AI 对话：输入"大于8000"，失焦/回车/魔法棒调 numberParse 解析回填。
切换：面板左上角模式名互切，值保留并转换形式，不触发 AI。
降级：未配置 numberParse 时 AI 模式提示降级；规则模式纯本地。

配置示例

{
  field: 'salary', label: '月薪',
  componentType: 'number_calc', operator: 'gte',
  componentProps: { inputMode: 'expression' },
}

Criteria 输出

{ field: 'salary', componentType: 'number_calc',
  operator: 'between', value: { start: 8000, end: 15000 } }

布尔开关 FilterBooleanSwitchboolean_switch

二值字段的三态开关：开 / 关 / 未设置（不参与筛选），标签可自定义。

Props

prop	类型	默认	说明
`modelValue`	String / Boolean / null	null	开/关为标签字符串（兼容布尔回显）
`field`	String	必填	字段名
`disabled`	Boolean	false	是否禁用
`trueLabel`	String	'是'	开标签（即开状态输出的值）
`falseLabel`	String	'否'	关标签（即关状态输出的值）
`triState`	Boolean	true	是否支持三态

事件

事件	载荷	说明
`update:modelValue`	String / null	值变化
`criteria-change`	节点 / null	恒为 eq；未设置输出 null

模式与交互

点击：开 ↔ 关，立即输出对应标签的 eq 节点。
重置：双击或长按 ≥500ms 回到"未设置"（null，不参与筛选）；triState=false 时仅二态。
输出约定：value 是标签字符串（'是'/'否' 或自定义），与业务库常见的字符串存储对齐；列为布尔/数值时用自定义标签或适配层映射。

配置示例

{
  field: 'is_active', label: '在职状态',
  componentType: 'boolean_switch', operator: 'eq',
  componentProps: { trueLabel: '在职', falseLabel: '离职' },
}

精确ID输入 FilterIdInputid_input

单个标识码精确查询：一个可清空的输入框，固定 eq。

Props

prop	类型	默认	说明
`modelValue`	String	''	单个标识码
`field`	String	必填	字段名
`placeholder`	String	'输入标识码'	占位符
`disabled`	Boolean	false	是否禁用

事件

事件	载荷	说明
`update:modelValue`	String	每次输入同步
`criteria-change`	节点 / null	固定 eq；清空输出 null

模式与交互

输入即生效（无防抖），点 × 或删空立即输出 null。
仅支持单值 eq：不支持多值（无 in），不支持模糊（无 like）；多 ID 请外层组合条件。
无联想、无魔法棒、无问号面板。

配置示例

{
  field: 'emp_no', label: '工号',
  componentType: 'id_input', operator: 'eq',
  placeholder: '输入工号',
}

Criteria 输出

{ field: 'emp_no', componentType: 'id_input',
  operator: 'eq', value: 'E100231' }