94 lines
2.5 KiB
Markdown
94 lines
2.5 KiB
Markdown
# 搜索增强模块
|
||
|
||
## 概述
|
||
搜索增强模块提供自动补全、搜索历史、键盘导航和搜索结果高亮，全面提升搜索体验和效率。
|
||
|
||
---
|
||
|
||
## 搜索自动补全 🆕
|
||
|
||
### API
|
||
|
||
| 路由 | 方法 | 功能 |
|
||
|------|------|------|
|
||
| /api/search/autocomplete | GET | 搜索自动补全建议 |
|
||
|
||
- Query: `q` (搜索关键词), `type` (tool/skill/all)
|
||
- 返回: `{ suggestions: [{ text, type, slug }] }`
|
||
- 基于工具名称、技能名称、标签前缀匹配
|
||
- 最多返回 8 条建议
|
||
- 响应时间 < 100ms（内存缓存）
|
||
|
||
### 前端组件
|
||
|
||
#### SearchBox 重写 🆕
|
||
- **文件**: `src/components/common/SearchBox.tsx`
|
||
- **功能**:
|
||
- 输入时实时显示自动补全下拉
|
||
- 键盘导航: ↑↓ 移动高亮 / Enter 选择 / ESC 关闭
|
||
- 搜索防抖（300ms）
|
||
- 搜索结果高亮匹配文本
|
||
- 支持工具/技能分类筛选
|
||
|
||
---
|
||
|
||
## 搜索历史 🆕
|
||
|
||
### 存储
|
||
- localStorage 存储: `zhuiguang-search-history`
|
||
- 最多保留 20 条历史记录
|
||
- 按最近使用排序
|
||
- 去重（同一查询只保留最新一条）
|
||
|
||
### 交互
|
||
- 搜索框聚焦时显示历史记录下拉
|
||
- 点击历史记录直接搜索
|
||
- 支持单条删除和清空全部
|
||
- 历史记录带搜索类型图标
|
||
|
||
---
|
||
|
||
## 高亮文本组件 🆕
|
||
|
||
### HighlightText
|
||
- **文件**: `src/components/common/HighlightText.tsx`
|
||
- Props: `{ text: string, keyword: string, className?: string }`
|
||
- 功能: 将文本中匹配的关键词包裹在 `<mark>` 标签中
|
||
- 样式: 黄色高亮背景 `bg-yellow-200 dark:bg-yellow-800`
|
||
- 不区分大小写匹配
|
||
|
||
### 使用场景
|
||
- 搜索结果列表中的工具名称/描述
|
||
- 自动补全下拉中的建议文本
|
||
- 评论/话题搜索
|
||
|
||
---
|
||
|
||
## 搜索框语义化
|
||
|
||
### WCAG 合规
|
||
- `<form role="search">` 包裹搜索表单
|
||
- `<label>` 关联搜索输入框（视觉隐藏）
|
||
- `<input type="search" name="search">` 语义输入
|
||
- `aria-label="搜索AI工具"` 辅助标签
|
||
- 自动补全列表 `role="listbox"` + `aria-activedescendant`
|
||
|
||
---
|
||
|
||
## 搜索参数规范
|
||
|
||
### 标准搜索参数
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| search | string | 搜索关键词 |
|
||
| page | number | 页码（默认1） |
|
||
| pageSize | number | 每页条数（默认20） |
|
||
| categoryId | number | 分类筛选 |
|
||
| pricingModel | string | 定价筛选 |
|
||
| sort | string | 排序（latest/popular/rating） |
|
||
|
||
### URL 搜索参数同步
|
||
- 搜索关键词同步到 URL query string
|
||
- 支持浏览器前进/后退导航
|
||
- 分享搜索结果 URL 可直接还原搜索状态
|