# 高级搜索与筛选

<cite>
**本文引用的文件**
- [packages/components/ProSearch.vue](file://packages/components/ProSearch.vue)
- [packages/core/src/components/ProSearch.vue](file://packages/core/src/components/ProSearch.vue)
- [packages/components/ProTypeItem/ProTypeItem.vue](file://packages/components/ProTypeItem/ProTypeItem.vue)
- [packages/components/ProTypeItem/comFillArr.js](file://packages/components/ProTypeItem/comFillArr.js)
- [packages/libs/util.js](file://packages/libs/util.js)
- [packages/mixin/locale.js](file://packages/mixin/locale.js)
- [packages/locale/index.js](file://packages/locale/index.js)
- [src/views/ProSearch.vue](file://src/views/ProSearch.vue)
- [packages/components/index.js](file://packages/components/index.js)
- [packages/core/src/components/ProTable.vue](file://packages/core/src/components/ProTable.vue)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 Pro-IVIEW V3 的高级搜索与筛选场景，系统性讲解如何使用 ProSearch 组件构建复杂搜索功能，覆盖多条件组合、动态筛选、搜索历史、快捷搜索等能力。文档重点说明搜索配置语法、条件组合逻辑、搜索结果处理流程，并提供可落地的实现建议与性能优化策略，帮助开发者快速满足范围搜索、模糊匹配、时间筛选等常见业务需求。

## 项目结构
围绕“高级搜索与筛选”的关键文件组织如下：
- ProSearch 核心组件：负责渲染搜索表单、处理按钮区、展开/收起、事件发射等
- ProTypeItem 渲染器：负责根据列配置动态渲染输入控件或自定义 JSX 片段
- 工具与国际化：提供通用格式化、表达式求值、国际化支持
- 示例页面：演示如何在业务页面中使用 ProSearch

```mermaid
graph TB
subgraph "组件层"
PS["ProSearch.vue"]
PTI["ProTypeItem.vue"]
CF["comFillArr.js"]
end
subgraph "工具与国际化"
U["util.js"]
L["locale/index.js"]
LM["mixin/locale.js"]
end
subgraph "示例与入口"
V["src/views/ProSearch.vue"]
IDX["packages/components/index.js"]
end
PS --> PTI
PTI --> U
PTI --> CF
PS --> LM
LM --> L
V --> PS
IDX --> PS
```

**图表来源**
- [packages/components/ProSearch.vue:1-271](file://packages/components/ProSearch.vue#L1-L271)
- [packages/components/ProTypeItem/ProTypeItem.vue:1-132](file://packages/components/ProTypeItem/ProTypeItem.vue#L1-L132)
- [packages/components/ProTypeItem/comFillArr.js:1-13](file://packages/components/ProTypeItem/comFillArr.js#L1-L13)
- [packages/libs/util.js:1-110](file://packages/libs/util.js#L1-L110)
- [packages/mixin/locale.js:1-18](file://packages/mixin/locale.js#L1-L18)
- [packages/locale/index.js:1-65](file://packages/locale/index.js#L1-L65)
- [src/views/ProSearch.vue:1-59](file://src/views/ProSearch.vue#L1-L59)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)

**章节来源**
- [packages/components/ProSearch.vue:1-271](file://packages/components/ProSearch.vue#L1-L271)
- [packages/core/src/components/ProSearch.vue:1-287](file://packages/core/src/components/ProSearch.vue#L1-L287)
- [packages/components/ProTypeItem/ProTypeItem.vue:1-132](file://packages/components/ProTypeItem/ProTypeItem.vue#L1-L132)
- [packages/libs/util.js:1-110](file://packages/libs/util.js#L1-L110)
- [packages/mixin/locale.js:1-18](file://packages/mixin/locale.js#L1-L18)
- [packages/locale/index.js:1-65](file://packages/locale/index.js#L1-L65)
- [src/views/ProSearch.vue:1-59](file://src/views/ProSearch.vue#L1-L59)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)

## 核心组件
- ProSearch：提供网格布局的搜索表单，支持标签位置、列数、展开/收起、按钮插槽、搜索与重置事件发射；通过 v-model 绑定查询参数对象
- ProTypeItem：根据列配置渲染标准输入或自定义组件，支持表达式求值、格式化包装、JSX 渲染
- 国际化与工具：统一 t 方法、表达式求值、JSON 序列化/反序列化、空值清理

关键点
- 列配置 columns 支持 renderSearch 字段以声明式渲染复杂输入控件
- 通过 beforeSearch/beforeReset 属性钩子实现搜索前置校验与重置前确认
- modelValue 作为查询参数载体，支持 format/formatWapper 实现值转换与包装

**章节来源**
- [packages/components/ProSearch.vue:114-217](file://packages/components/ProSearch.vue#L114-L217)
- [packages/core/src/components/ProSearch.vue:114-233](file://packages/core/src/components/ProSearch.vue#L114-L233)
- [packages/components/ProTypeItem/ProTypeItem.vue:26-50](file://packages/components/ProTypeItem/ProTypeItem.vue#L26-L50)
- [packages/libs/util.js:56-78](file://packages/libs/util.js#L56-L78)
- [packages/mixin/locale.js:4-17](file://packages/mixin/locale.js#L4-L17)

## 架构总览
ProSearch 与 ProTypeItem 协作，将列配置转换为可视化的搜索表单；通过事件与 v-model 将用户输入转化为查询参数对象，交由上层业务组件（如 ProTable）消费。

```mermaid
sequenceDiagram
participant View as "视图组件"
participant Search as "ProSearch"
participant TypeItem as "ProTypeItem"
participant Util as "util.js"
participant I18n as "locale/index.js"
View->>Search : 传入 columns / modelValue / 属性
Search->>TypeItem : 为每列渲染 renderSearch
TypeItem->>Util : 执行 format/formatWapper
Util-->>TypeItem : 返回格式化后的值
TypeItem-->>Search : 触发 update : modelValue 或 wapperInput
Search-->>View : 触发 search/reset 事件
View->>I18n : 使用 t 获取本地化文案
```

**图表来源**
- [packages/components/ProSearch.vue:41-58](file://packages/components/ProSearch.vue#L41-L58)
- [packages/components/ProTypeItem/ProTypeItem.vue:37-49](file://packages/components/ProTypeItem/ProTypeItem.vue#L37-L49)
- [packages/libs/util.js:56-78](file://packages/libs/util.js#L56-L78)
- [packages/locale/index.js:35-50](file://packages/locale/index.js#L35-L50)

## 详细组件分析

### ProSearch 组件
职责与行为
- 表单网格布局：根据 searchLineNum 控制每行列数，支持标签宽度与位置控制
- 条件渲染：支持 upDown 展开/收起，itemShow 决定可见列
- 事件发射：search/reset 事件，支持 beforeSearch/beforeReset 钩子
- 值更新：wapperInput 接收包装值并合并到 modelValue

关键实现要点
- 计算属性 downItemSapn 用于计算底部操作区占位，保证按钮区对齐
- enter 键触发搜索，便于快捷键操作
- 国际化文案通过 mixin 提供的 t 方法注入

```mermaid
flowchart TD
Start(["进入 ProSearch"]) --> Init["初始化 isDown = upDown"]
Init --> RenderGrid["按列渲染搜索项<br/>支持 renderSearch 与默认 Input"]
RenderGrid --> Interact{"用户交互"}
Interact --> |输入/选择| Update["update:modelValue 合并到 modelValue"]
Interact --> |点击搜索| EmitSearch["触发 search 事件"]
Interact --> |点击重置| EmitReset["触发 reset 事件"]
Update --> End(["结束"])
EmitSearch --> End
EmitReset --> End
```

**图表来源**
- [packages/components/ProSearch.vue:155-189](file://packages/components/ProSearch.vue#L155-L189)
- [packages/components/ProSearch.vue:194-216](file://packages/components/ProSearch.vue#L194-L216)

**章节来源**
- [packages/components/ProSearch.vue:114-217](file://packages/components/ProSearch.vue#L114-L217)
- [packages/core/src/components/ProSearch.vue:114-233](file://packages/core/src/components/ProSearch.vue#L114-L233)

### ProTypeItem 组件
职责与行为
- 根据 renderItem 类型渲染标准组件或自定义 JSX
- 支持 format/formatWapper 进行值转换与包装
- 支持 useExp/text/style/props/on/scopedSlots 等高级配置
- 自动处理 v-model 与 onUpdate:modelValue，确保外部双向绑定

实现细节
- commonToFn 将字符串或函数形式的 format 转换为可执行函数，统一处理值转换
- evalUse 支持 style 中的表达式求值
- isHTMLTag 判断是否为原生 HTML 标签，决定渲染方式

```mermaid
classDiagram
class ProTypeItem {
+props item
+props renderItem
+props modelValue
+evalUse(obj, value)
+input(value)
+render()
}
class Util {
+commonToFn(that, format, value)
+isHTMLTag(tag)
}
ProTypeItem --> Util : "调用"
```

**图表来源**
- [packages/components/ProTypeItem/ProTypeItem.vue:26-124](file://packages/components/ProTypeItem/ProTypeItem.vue#L26-L124)
- [packages/libs/util.js:56-78](file://packages/libs/util.js#L56-L78)
- [packages/libs/util.js:80-94](file://packages/libs/util.js#L80-L94)

**章节来源**
- [packages/components/ProTypeItem/ProTypeItem.vue:1-132](file://packages/components/ProTypeItem/ProTypeItem.vue#L1-L132)
- [packages/libs/util.js:1-110](file://packages/libs/util.js#L1-L110)
- [packages/components/ProTypeItem/comFillArr.js:1-13](file://packages/components/ProTypeItem/comFillArr.js#L1-L13)

### 搜索配置语法与条件组合逻辑
- 列配置 columns：每列包含 key/title/renderSearch 等字段
- renderSearch 支持以下形态：
  - 对象：type/props/scopedSlots/style/useExp/text/format/formatWapper 等
  - 函数：接收上下文并返回 JSX/VNode，自动挂载 v-model
- format/formatWapper：用于将原始输入转换为目标查询值或包装为复合对象
- 多条件组合：通过 modelValue 合并各列值，最终形成查询参数对象

示例路径参考
- [src/views/ProSearch.vue:22-54](file://src/views/ProSearch.vue#L22-L54)
- [packages/components/ProSearch.vue:41-58](file://packages/components/ProSearch.vue#L41-L58)
- [packages/components/ProTypeItem/ProTypeItem.vue:52-122](file://packages/components/ProTypeItem/ProTypeItem.vue#L52-L122)

**章节来源**
- [src/views/ProSearch.vue:17-58](file://src/views/ProSearch.vue#L17-L58)
- [packages/components/ProSearch.vue:114-189](file://packages/components/ProSearch.vue#L114-L189)
- [packages/components/ProTypeItem/ProTypeItem.vue:26-124](file://packages/components/ProTypeItem/ProTypeItem.vue#L26-L124)

### 搜索结果处理与业务集成
- ProTable 集成 ProSearch：通过 searchColumns 过滤列，将 form 与 searchForm 双向绑定，支持 autoFetch 自动拉取数据
- immutableSearchValue 保存初始查询快照，便于重置与对比
- 事件驱动：上层监听 ProSearch 的 search/reset 事件，发起数据请求或清空状态

```mermaid
sequenceDiagram
participant Table as "ProTable"
participant Search as "ProSearch"
participant Store as "数据源"
Table->>Search : 传入 columns / form / 属性
Search-->>Table : emit "search"
Table->>Store : 发起查询请求(携带 modelValue)
Store-->>Table : 返回数据
Table->>Table : 更新 total / 数据列表
```

**图表来源**
- [packages/core/src/components/ProTable.vue:394-422](file://packages/core/src/components/ProTable.vue#L394-L422)
- [packages/core/src/components/ProTable.vue:429-442](file://packages/core/src/components/ProTable.vue#L429-L442)

**章节来源**
- [packages/core/src/components/ProTable.vue:385-442](file://packages/core/src/components/ProTable.vue#L385-L442)

### 典型高级场景实现建议
- 范围搜索（日期/数值）
  - 使用 renderSearch.type 指定范围组件（如日期范围），通过 formatWapper 将数组转换为 { start, end } 结构
  - 示例路径参考：[src/views/ProSearch.vue:26-36](file://src/views/ProSearch.vue#L26-L36)
- 模糊匹配
  - 在 format 中拼接通配符或调用后端接口进行模糊过滤
  - 建议结合防抖策略避免频繁请求
- 时间筛选
  - 使用日期/时间组件配合 format/formatWapper 统一时间格式
- 快捷搜索
  - 在按钮插槽中添加常用条件按钮，点击时通过 update:modelValue 设置预设值
- 搜索历史
  - 在父组件维护历史列表，点击回填至 modelValue，再触发 search 事件

**章节来源**
- [src/views/ProSearch.vue:17-58](file://src/views/ProSearch.vue#L17-L58)
- [packages/components/ProSearch.vue:75-99](file://packages/components/ProSearch.vue#L75-L99)

## 依赖关系分析
- ProSearch 依赖 ProTypeItem 进行列渲染，依赖 mixin/locale.js 提供国际化方法
- ProTypeItem 依赖 util.js 提供的格式化与表达式求值能力
- 示例页面 src/views/ProSearch.vue 引入 ProSearch 并传入 columns 与 v-model
- packages/components/index.js 汇总导出组件，便于统一引入

```mermaid
graph LR
V["src/views/ProSearch.vue"] --> PS["ProSearch.vue"]
PS --> PTI["ProTypeItem.vue"]
PTI --> U["util.js"]
PS --> LM["mixin/locale.js"]
LM --> L["locale/index.js"]
IDX["packages/components/index.js"] --> PS
```

**图表来源**
- [src/views/ProSearch.vue:1-16](file://src/views/ProSearch.vue#L1-L16)
- [packages/components/ProSearch.vue:114-118](file://packages/components/ProSearch.vue#L114-L118)
- [packages/components/ProTypeItem/ProTypeItem.vue:1-6](file://packages/components/ProTypeItem/ProTypeItem.vue#L1-L6)
- [packages/libs/util.js:1-6](file://packages/libs/util.js#L1-L6)
- [packages/mixin/locale.js:1-4](file://packages/mixin/locale.js#L1-L4)
- [packages/locale/index.js:1-6](file://packages/locale/index.js#L1-L6)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)

**章节来源**
- [src/views/ProSearch.vue:1-59](file://src/views/ProSearch.vue#L1-L59)
- [packages/components/ProSearch.vue:114-118](file://packages/components/ProSearch.vue#L114-L118)
- [packages/components/ProTypeItem/ProTypeItem.vue:1-6](file://packages/components/ProTypeItem/ProTypeItem.vue#L1-L6)
- [packages/libs/util.js:1-6](file://packages/libs/util.js#L1-L6)
- [packages/mixin/locale.js:1-4](file://packages/mixin/locale.js#L1-L4)
- [packages/locale/index.js:1-6](file://packages/locale/index.js#L1-L6)
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)

## 性能考量
- 防抖与节流
  - 在高频输入（如文本框）场景，建议在父组件对 search 事件进行防抖，减少请求次数
- 请求去重
  - 对相同查询参数的请求进行缓存或取消上一次未完成请求
- 渲染优化
  - 使用 upDown 折叠非首屏列，降低初始渲染压力
  - 合理设置 searchLineNum，避免过多列导致布局与渲染开销增大
- 值转换成本
  - format/formatWapper 中避免复杂计算，必要时在父组件预处理
- 国际化与样式
  - 文案统一通过 t 方法，减少重复资源加载

[本节为通用指导，无需特定文件引用]

## 故障排查指南
- 输入值未生效
  - 检查列配置中是否正确设置 renderSearch 或默认 Input
  - 确认 v-model 是否正确绑定到父组件
  - 参考路径：[packages/components/ProSearch.vue:41-58](file://packages/components/ProSearch.vue#L41-L58)
- 值转换异常
  - 检查 format/formatWapper 的表达式是否正确，必要时使用 commonToFn 辅助调试
  - 参考路径：[packages/components/ProTypeItem/ProTypeItem.vue:37-49](file://packages/components/ProTypeItem/ProTypeItem.vue#L37-L49)、[packages/libs/util.js:56-78](file://packages/libs/util.js#L56-L78)
- 按钮事件未触发
  - 确认是否正确监听 search/reset 事件，或是否被 beforeSearch/beforeReset 阻断
  - 参考路径：[packages/components/ProSearch.vue:181-189](file://packages/components/ProSearch.vue#L181-L189)
- 文案显示异常
  - 检查 locale 初始化与 t 方法调用
  - 参考路径：[packages/mixin/locale.js:4-17](file://packages/mixin/locale.js#L4-L17)、[packages/locale/index.js:35-50](file://packages/locale/index.js#L35-L50)
- 布局错位
  - 检查 searchLineNum 与列的 searchLineNum 配置，确保网格计算正确
  - 参考路径：[packages/components/ProSearch.vue:194-216](file://packages/components/ProSearch.vue#L194-L216)

**章节来源**
- [packages/components/ProSearch.vue:41-58](file://packages/components/ProSearch.vue#L41-L58)
- [packages/components/ProTypeItem/ProTypeItem.vue:37-49](file://packages/components/ProTypeItem/ProTypeItem.vue#L37-L49)
- [packages/libs/util.js:56-78](file://packages/libs/util.js#L56-L78)
- [packages/components/ProSearch.vue:181-189](file://packages/components/ProSearch.vue#L181-L189)
- [packages/mixin/locale.js:4-17](file://packages/mixin/locale.js#L4-L17)
- [packages/locale/index.js:35-50](file://packages/locale/index.js#L35-L50)
- [packages/components/ProSearch.vue:194-216](file://packages/components/ProSearch.vue#L194-L216)

## 结论
ProSearch 通过声明式列配置与 ProTypeItem 动态渲染，提供了强大的高级搜索能力。结合 beforeSearch/beforeReset、format/formatWapper、国际化与网格布局，能够灵活支撑范围搜索、模糊匹配、时间筛选等复杂场景。建议在实际项目中配合防抖、缓存与合理的布局配置，持续优化性能与用户体验。

[本节为总结性内容，无需特定文件引用]

## 附录
- 组件导出入口：packages/components/index.js
- 示例页面：src/views/ProSearch.vue
- ProTable 集成点：searchColumns/form 双向绑定

**章节来源**
- [packages/components/index.js:1-23](file://packages/components/index.js#L1-L23)
- [src/views/ProSearch.vue:1-59](file://src/views/ProSearch.vue#L1-L59)
- [packages/core/src/components/ProTable.vue:394-422](file://packages/core/src/components/ProTable.vue#L394-L422)