CumuloCumulo · CumuloCumulo · Nov 11, 2025 · Nov 11, 2025 · Nov 11, 2025 · Nov 11, 2025
diff --git a/BATCH_HIGHLIGHT_FEATURE.md b/BATCH_HIGHLIGHT_FEATURE.md
@@ -0,0 +1,303 @@
+# 🎯 批量高亮 + 选择器测试功能说明
+
+## 📋 功能概述
+
+**版本**: v2.4.0  
+**发布日期**: 2025-11-10
+
+新增"批量高亮"和"选择器类型选择"功能，允许用户：
+1. 一键高亮所有提取的元素或当前分类的元素
+2. 选择不同的选择器类型进行测试
+3. 查看实时统计反馈（成功/失败/不可用）
+
+## ✨ 核心特性
+
+### 1. 选择器类型选择
+支持 9 种选择器类型，用户可以自由切换测试：
+
+| 选择器类型 | 可靠性 | 说明 |
+|-----------|--------|------|
+| 🎯 智能优先 | - | 7级回退逻辑（默认） |
+| 🟢 Extract ID | 最高 | data-extract-id 属性 |
+| 🟢 CSS by ID | 高 | #element-id |
+| 🟡 XPath Short | 中 | 优化的 XPath |
+| 🟡 XPath Full | 中 | 完整 XPath 路径 |
+| 🟡 CSS Combined | 中 | 组合选择器 |
+| 🟡 CSS by Class | 中 | .class-name |
+| 🟡 CSS by Attribute | 中 | [name="value"] |
+| 🔴 CSS nth-child | 低 | :nth-child(n) |
+
+### 2. 批量高亮操作
+
+#### ✨ 高亮所有元素
+- 一次性高亮页面上所有提取的元素
+- 每个元素独立的覆盖层和动画
+- 10 秒后自动清除（比单个元素的 5 秒更长）
+
+#### 🎯 高亮当前分类
+- 只高亮当前标签页的元素
+- 例如：只高亮所有按钮、只高亮所有链接等
+
+#### ❌ 清除高亮
+- 手动清除所有高亮覆盖层
+- 清空统计信息
+
+### 3. 实时统计反馈
+
+高亮操作后，会显示详细的统计信息：
+```
+高亮结果：成功 45/200 | 无此选择器 120 | 定位失败 35
+```
+
+- **成功数/总数**: 成功高亮的元素数量
+- **无此选择器**: 元素没有该类型的选择器（例如没有 ID）
+- **定位失败**: 有选择器但无法在页面上定位到元素
+
+## 🎨 UI 设计
+
+### 界面布局
+
+```
+┌─────────────────────────────────────┐
+│ 📊 提取统计                          │
+│ [总计: 200] [页面: xxx] [时间: xxx] │
+├─────────────────────────────────────┤
+│ 🔍 搜索框                            │
+├─────────────────────────────────────┤
+│ 选择器类型: [🎯 智能优先 ▼]         │
+│                                      │
+│ ⚠️ 高亮结果：成功 45/200 | ...      │
+│                                      │
+│ [✨ 高亮所有] [🎯 当前分类] [❌ 清除]│
+├─────────────────────────────────────┤
+│ [按钮 50] [链接 80] [表单 10] ...   │
+├─────────────────────────────────────┤
+│ 元素列表...                          │
+└─────────────────────────────────────┘
+```
+
+### 按钮样式
+- **✨ 高亮所有**: 粉色到橙色渐变，全宽
+- **🎯 当前分类**: 紫色边框，轮廓样式
+- **❌ 清除**: 红色边框，轮廓样式
+
+## 🔧 技术实现
+
+### 架构设计
+
+```
+ElementsDisplay.tsx (UI层)
+    ↓ 发送消息
+content.ts (路由层)
+    ↓ 调用函数
+element-highlighter.ts (核心逻辑)
+    ├── locateElementBySelectorType() - 按类型定位
+    ├── highlightAllElements() - 批量高亮
+    └── clearAllHighlights() - 清除所有
+```
+
+### 核心函数
+
+#### 1. `locateElementBySelectorType()`
+```typescript
+function locateElementBySelectorType(
+  selectors: ElementSelectors, 
+  extractId: string | undefined,
+  selectorType: SelectorType
+): HTMLElement | null
+```
+- 根据指定的选择器类型定位元素
+- 支持 9 种选择器类型
+- 返回找到的元素或 null
+
+#### 2. `highlightAllElements()`
+```typescript
+export function highlightAllElements(
+  elementsData: Array<{ selectors: ElementSelectors; extractId?: string }>,
+  selectorType: SelectorType = 'auto'
+): { total: number; success: number; failed: number; unavailable: number }
+```
+- 批量高亮多个元素
+- 使用指定的选择器类型
+- 返回详细的统计信息
+
+#### 3. `clearAllHighlights()`
+```typescript
+export function clearAllHighlights(): void
+```
+- 停止所有动画
+- 移除所有覆盖层
+- 清理事件监听器
+
+### 数据结构
+
+#### 覆盖层管理
+```typescript
+let allHighlightOverlays: Map<string, {
+  overlay: HTMLDivElement;
+  element: HTMLElement;
+  animationId: number;
+}> = new Map();
+```
+
+#### 统计信息
+```typescript
+{
+  total: 200,        // 总元素数
+  success: 45,       // 成功高亮数
+  failed: 35,        // 定位失败数
+  unavailable: 120   // 无此选择器数
+}
+```
+
+### 消息通信
+
+#### 高亮所有元素
+```typescript
+chrome.runtime.sendMessage({
+  action: 'highlightAllElements',
+  elements: [{ selectors, extractId }, ...],
+  selectorType: 'cssById'
+})
+```
+
+#### 清除所有高亮
+```typescript
+chrome.runtime.sendMessage({
+  action: 'clearAllHighlights'
+})
+```
+
+## 📖 使用场景
+
+### 场景 1: 测试 CSS ID 的覆盖率
+```
+1. 选择"CSS by ID (#id)"
+2. 点击"高亮所有"
+3. 查看统计：成功 45/200，无此选择器 155
+   → 说明只有 22.5% 的元素有 ID
+```
+
+### 场景 2: 对比 XPath 和 CSS 的可靠性
+```
+1. 选择"XPath Short"，点击"高亮所有"
+   观察：成功 180/200
+
+2. 清除高亮
+
+3. 选择"CSS Combined"，点击"高亮所有"
+   观察：成功 170/200
+
+结论：XPath Short 更可靠（90% vs 85%）
+```
+
+### 场景 3: 验证提取的数据完整性
+```
+1. 选择"Extract ID"（应该 100% 成功）
+2. 点击"高亮所有"
+3. 如果有失败，说明提取过程有问题
+```
+
+### 场景 4: 测试特定分类的选择器
+```
+1. 切换到"按钮"标签页
+2. 选择"CSS by Class"
+3. 点击"🎯 当前分类"
+4. 查看按钮元素的 class 选择器覆盖率
+```
+
+## 🎯 性能优化
+
+### 动画性能
+- 使用 `requestAnimationFrame` 实现 60fps 动画
+- 每个覆盖层独立动画，避免阻塞
+
+### 内存管理
+- 使用 `Map` 存储覆盖层，O(1) 查找
+- 自动清理：10 秒后自动移除所有覆盖层
+- 手动清理：提供清除按钮立即释放资源
+
+### 事件优化
+- 使用事件委托
+- 防止事件冒泡 (`stopPropagation`)
+- 统一的 scroll/resize 监听器
+
+## ⚠️ 注意事项
+
+### 限制
+1. **大量元素**: 同时高亮 500+ 元素可能影响性能
+2. **动态页面**: SPA 页面动态加载的元素可能定位失败
+3. **iframe**: iframe 内的元素无法高亮
+
+### 最佳实践
+1. 优先使用"当前分类"而不是"所有元素"
+2. 测试完选择器后及时清除高亮
+3. 对于复杂页面，使用"智能优先"模式
+
+## 🔍 调试技巧
+
+### 查看控制台日志
+```javascript
+// content script 日志
+Highlighted 45/200 elements using cssById
+Unavailable: 120, Failed: 35
+
+// 单个元素定位日志
+Element found by CSS ID: #submit-button
+```
+
+### 测试选择器
+1. 打开开发者工具
+2. 使用 `document.querySelector()` 测试选择器
+3. 对比不同选择器的结果
+
+## 📊 数据分析
+
+### 统计报告示例
+```
+测试页面: https://example.com
+总元素数: 200
+
+选择器类型覆盖率：
+- Extract ID:    100% (200/200) ✅
+- CSS by ID:     22.5% (45/200)
+- XPath Short:   90% (180/200)
+- CSS Combined:  85% (170/200)
+- CSS by Class:  75% (150/200)
+
+结论：
+1. Extract ID 最可靠（提取时添加）
+2. XPath Short 覆盖率最高
+3. CSS by ID 覆盖率较低，建议使用其他选择器
+```
+
+## 🚀 未来规划
+
+### v2.5 可能的增强
+- [ ] 导出高亮统计报告（CSV/JSON）
+- [ ] 选择器性能对比（响应时间）
+- [ ] 自定义高亮颜色
+- [ ] 批量高亮的动画配置
+- [ ] 选择器自动推荐（根据覆盖率）
+
+## 📚 相关文档
+
+- [README.md](README.md) - 完整项目文档
+- [selector.md](selector.md) - 选择器生成原理
+- [element-highlighter.ts](src/content/element-highlighter.ts) - 核心实现
+
+## 🎉 总结
+
+v2.4.0 的批量高亮功能为用户提供了强大的选择器测试和验证工具：
+
+✅ **9种选择器类型** - 全面覆盖各种定位需求  
+✅ **实时统计反馈** - 清晰了解选择器可靠性  
+✅ **批量操作** - 提升测试效率  
+✅ **优雅的UI** - Material-UI 设计规范  
+
+---
+
+**开发者**: AI Assistant  
+**版本**: v2.4.0  
+**日期**: 2025-11-10
+