implementing-search-filter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Search & Filter Implementation

搜索与筛选功能实现

Implement search and filter interfaces with comprehensive frontend components and backend query optimization.

实现包含全面前端组件与后端查询优化的搜索与筛选界面。

Purpose

用途

This skill provides production-ready patterns for implementing search and filtering functionality across the full stack. It covers React/TypeScript components for the frontend (search inputs, filter UIs, autocomplete) and Python patterns for the backend (SQLAlchemy queries, Elasticsearch integration, API design). The skill emphasizes performance optimization, accessibility, and user experience.

本技能提供了全栈搜索与筛选功能的生产级实现模式，涵盖前端React/TypeScript组件（搜索输入框、筛选UI、自动补全）以及后端Python模式（SQLAlchemy查询、Elasticsearch集成、API设计）。本技能重点关注性能优化、可访问性与用户体验。

When to Use

适用场景

Building product search with category and price filters
Implementing autocomplete/typeahead search
Creating faceted search interfaces with dynamic counts
Adding search to data tables or lists
Building advanced boolean search for power users
Implementing backend search with SQLAlchemy or Django ORM
Integrating Elasticsearch for full-text search
Optimizing search performance with debouncing and caching
Creating accessible search experiences

构建带有分类与价格筛选的商品搜索
实现自动补全/联想搜索
创建带有动态计数的分面搜索界面
为数据表格或列表添加搜索功能
为高级用户构建布尔搜索
使用SQLAlchemy或Django ORM实现后端搜索
集成Elasticsearch实现全文搜索
通过防抖与缓存优化搜索性能
创建可访问的搜索体验

Core Components

核心组件

Frontend Search Patterns

前端搜索模式

Search Input with Debouncing

Implement 300ms debounce for performance
Show loading states during search
Clear button (X) for resetting
Keyboard shortcuts (Cmd/Ctrl+K)
See
```
references/search-input-patterns.md
```

Autocomplete/Typeahead

Suggestion dropdown with keyboard navigation
Highlight matched text in suggestions
Recent searches and popular items
Prevent request flooding with debouncing
See
```
references/autocomplete-patterns.md
```

Filter UI Components

Checkbox filters for multi-select
Range sliders for numerical values
Dropdown filters for single selection
Filter chips showing active selections
See
```
references/filter-ui-patterns.md
```

带防抖的搜索输入框

实现300ms防抖以提升性能
搜索过程中显示加载状态
提供清除按钮（X）重置输入
支持键盘快捷键（Cmd/Ctrl+K）
参考：
```
references/search-input-patterns.md
```

自动补全/联想搜索

支持键盘导航的建议下拉框
在建议中高亮匹配文本
显示最近搜索与热门条目
通过防抖防止请求泛滥
参考：
```
references/autocomplete-patterns.md
```

筛选UI组件

用于多选的复选框筛选器
用于数值范围的滑块筛选器
用于单选的下拉筛选器
显示已选条件的筛选标签
参考：
```
references/filter-ui-patterns.md
```

Backend Query Patterns

后端查询模式

Database Query Building

Dynamic query construction with SQLAlchemy
Django ORM filter chaining
Index optimization for search columns
Full-text search in PostgreSQL
See
```
references/database-querying.md
```

Elasticsearch Integration

Document indexing strategies
Query DSL for complex searches
Faceted aggregations
Relevance scoring and boosting
See
```
references/elasticsearch-integration.md
```

API Design

RESTful search endpoints
Query parameter validation
Pagination with cursor/offset
Response caching strategies
See
```
references/api-design.md
```

数据库查询构建

使用SQLAlchemy构建动态查询
Django ORM筛选链式调用
为搜索列创建合适的索引
PostgreSQL全文搜索
参考：
```
references/database-querying.md
```

Elasticsearch集成

文档索引策略
用于复杂搜索的查询DSL
分面聚合
相关性评分与权重提升
参考：
```
references/elasticsearch-integration.md
```

API设计

RESTful搜索端点
查询参数验证
基于游标/偏移量的分页
响应缓存策略
参考：
```
references/api-design.md
```

Implementation Workflows

实现流程

Client-Side Search (<1000 items)

客户端搜索（数据量<1000条）

Load data into memory
Implement filter functions in JavaScript
Apply debounced search on text input
Update results instantly
Maintain filter state in React

将数据加载至内存
在JavaScript中实现筛选函数
为文本输入框应用防抖搜索
即时更新结果
在React中维护筛选状态

Server-Side Search (>1000 items)

服务端搜索（数据量>1000条）

Design search API endpoint
Validate and sanitize query parameters
Build database query dynamically
Apply pagination
Return results with metadata
Cache frequent queries

设计搜索API端点
验证并清洗查询参数
动态构建数据库查询
应用分页
返回包含元数据的结果
缓存频繁查询结果

Hybrid Approach

混合方案

Use client-side filtering for immediate feedback
Fetch server results in background
Merge and deduplicate results
Update UI progressively
Cache recent searches locally

使用客户端筛选提供即时反馈
在后台获取服务端结果
合并并去重结果
渐进式更新UI
在本地缓存最近搜索记录

Performance Optimization

性能优化

Frontend Optimization

前端优化

Debouncing Implementation

Use
```
debounce
```
from lodash or custom implementation
Cancel pending requests on new input
Show skeleton loaders during fetch
Script:
```
scripts/debounce_calculator.js
```

Query Parameter Management

Sync filters with URL for shareable searches
Use React Router or Next.js for URL state
Compress complex queries

See

references/query-parameter-management.md

防抖实现

使用lodash的
```
debounce
```
或自定义实现
新输入时取消待处理请求
数据获取期间显示骨架加载器
脚本：
```
scripts/debounce_calculator.js
```

查询参数管理

将筛选条件与URL同步以支持可分享的搜索链接
使用React Router或Next.js管理URL状态
压缩复杂查询

参考：

references/query-parameter-management.md

Backend Optimization

后端优化

Query Optimization

Create appropriate database indexes
Use query analyzers to identify bottlenecks
Implement query result caching
Script:
```
scripts/generate_filter_query.py
```

Validation & Security

Sanitize all search inputs
Prevent SQL injection
Rate limit search endpoints
Script:
```
scripts/validate_search_params.py
```

查询优化

创建合适的数据库索引
使用查询分析器识别性能瓶颈
实现查询结果缓存
脚本：
```
scripts/generate_filter_query.py
```

验证与安全

清洗所有搜索输入
防止SQL注入
对搜索端点进行限流
脚本：
```
scripts/validate_search_params.py
```

Accessibility Requirements

可访问性要求

ARIA Patterns

ARIA模式

Use
```
role="search"
```
for search regions
Implement
```
aria-live
```
for result updates
Provide clear labels for filters
Support keyboard-only navigation

为搜索区域使用
```
role="search"
```
为结果更新实现
```
aria-live
```
为筛选器提供清晰的标签
支持纯键盘导航

Keyboard Support

键盘支持

Tab through all interactive elements
Arrow keys for autocomplete navigation
Escape to close dropdowns
Enter to select/submit

可通过Tab键遍历所有交互元素
使用方向键导航自动补全列表
使用Escape键关闭下拉框
使用Enter键选择/提交

Technology Stack

技术栈

Frontend Libraries

前端库

Primary: Downshift (Autocomplete)

Accessible autocomplete primitives
Headless/unstyled for flexibility
WAI-ARIA compliant
Install:
```
npm install downshift
```

Alternative: React Select

Full-featured select/filter component
Built-in async search
Multi-select support

首选：Downshift（自动补全）

可访问的自动补全基础组件
无头/无样式设计，灵活性高
符合WAI-ARIA标准
安装命令：
```
npm install downshift
```

备选：React Select

功能完整的选择/筛选组件
内置异步搜索
支持多选

Backend Technologies

后端技术

Python/SQLAlchemy

Dynamic query building
Relationship loading optimization
Query result pagination

Python/Django

Django Filter backend
Django REST Framework filters
Full-text search with PostgreSQL

Elasticsearch (Python)

elasticsearch-py client
elasticsearch-dsl for query building

Python/SQLAlchemy

动态查询构建
关联加载优化
查询结果分页

Python/Django

Django Filter后端
Django REST Framework筛选器
PostgreSQL全文搜索

Elasticsearch（Python）

elasticsearch-py客户端
使用elasticsearch-dsl构建查询

Bundled Resources

配套资源

References

参考文档

```
references/search-input-patterns.md
```
- Input implementations
```
references/autocomplete-patterns.md
```
- Typeahead patterns
```
references/filter-ui-patterns.md
```
- Filter components
```
references/database-querying.md
```
- SQL query patterns
```
references/elasticsearch-integration.md
```
- Elasticsearch setup
```
references/api-design.md
```
- API endpoint patterns
```
references/performance-optimization.md
```
- Performance tips
```
references/library-comparison.md
```
- Library evaluation

```
references/search-input-patterns.md
```
- 输入框实现方案
```
references/autocomplete-patterns.md
```
- 联想搜索模式
```
references/filter-ui-patterns.md
```
- 筛选组件方案
```
references/database-querying.md
```
- SQL查询模式
```
references/elasticsearch-integration.md
```
- Elasticsearch集成指南
```
references/api-design.md
```
- API端点设计模式
```
references/performance-optimization.md
```
- 性能优化技巧
```
references/library-comparison.md
```
- 库对比评估

Scripts

脚本

```
scripts/generate_filter_query.py
```
- Build SQL/ES queries
```
scripts/validate_search_params.py
```
- Validate inputs
```
scripts/debounce_calculator.js
```
- Calculate debounce timing

```
scripts/generate_filter_query.py
```
- 构建SQL/ES查询
```
scripts/validate_search_params.py
```
- 验证输入参数
```
scripts/debounce_calculator.js
```
- 计算防抖时长

Examples

示例

```
examples/product-search.tsx
```
- E-commerce search
```
examples/autocomplete-search.tsx
```
- Autocomplete implementation
```
examples/sqlalchemy_search.py
```
- SQLAlchemy patterns
```
examples/fastapi_search.py
```
- FastAPI search endpoint
```
examples/django_filter_backend.py
```
- Django filters

```
examples/product-search.tsx
```
- 电商搜索示例
```
examples/autocomplete-search.tsx
```
- 自动补全实现示例
```
examples/sqlalchemy_search.py
```
- SQLAlchemy模式示例
```
examples/fastapi_search.py
```
- FastAPI搜索端点示例
```
examples/django_filter_backend.py
```
- Django筛选器后端示例

Assets

资源文件

```
assets/filter-config-schema.json
```
- Filter configuration
```
assets/search-api-spec.json
```
- OpenAPI specification

```
assets/filter-config-schema.json
```
- 筛选配置 schema
```
assets/search-api-spec.json
```
- OpenAPI 规范