# TextSearchUI 使用文档一个功能完整的网页文本搜索组件，支持高亮显示、拖拽定位、主题切换等特性。 ![image.png](https://scriptcat.org/api/v2/resource/image/2jR8Y4l8vlwrfFsU) ## 功能特性 * 🔍 **实时搜索**：输入即搜，快速定位文本 * 🎯 **精准定位**：自动滚动到匹配位置并高亮显示 * 🎨 **主题支持**：支持浅色、深色和自动主题切换 * 🖱️ **可拖拽**：搜索框可自由拖动，支持触摸设备 * ⌨️ **快捷键**：`Ctrl+F` / `Cmd+F` 快速唤起 * 📱 **响应式**：适配桌面和移动设备 *** ## 快速开始 ### 基础用法 ``` // 创建搜索实例（使用默认配置） const search = new TextSearchUI(); // 指定搜索范围（默认整个网页） const search = new TextSearchUI({ scope: '#content' }); ``` ### 带主题配置 ``` // 浅色主题 const search = new TextSearchUI({ theme: 'light' }); // 深色主题 const search = new TextSearchUI({ theme: 'dark' }); // 自动主题（跟随系统） const search = new TextSearchUI({ theme: 'auto' }); ``` *** ## 配置选项 ### Constructor Options ``` new TextSearchUI(options) ``` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | `options.theme` | `'light'` \| `'dark'` \| `'auto'` | `'auto'` | 初始主题模式 | | `options.beforeShow` | `callback` | `null` | 在对话框显示前被回调| *** ## API 方法 ### `show()` 显示搜索框并自动聚焦输入框。 ``` search.show(); ``` ### `hide()` 隐藏搜索框并清除所有高亮。 ``` search.hide(); ``` ### `search(searchTerm)` 执行搜索并高亮所有匹配项。 ``` search.search('关键词'); ``` **参数：** * `searchTerm` (string): 要搜索的文本 ### `findNext()` 跳转到下一个匹配项。 ``` search.findNext(); ``` ### `findPrevious()` 跳转到上一个匹配项。 ``` search.findPrevious(); ``` ### `clear()` 清除所有高亮和搜索结果。 ``` search.clear(); ``` ### `setScope` 动态修改搜索范围。 ``` search.setScope('.article'); // 或 search.setScope(document.querySelector('.article')); ``` ### `setTheme(theme)` 动态切换主题。 ``` // 切换到深色模式 search.setTheme('dark'); // 切换到浅色模式 search.setTheme('light'); // 切换到自动模式 search.setTheme('auto'); ``` **参数：** * `theme` (`'light'` \| `'dark'` \| `'auto'`): 新主题模式 *** ## 快捷键 | 快捷键 | 功能 | | --- | --- | | `Ctrl+F` / `Cmd+F` | 打开搜索框 | | `Enter` | 执行搜索 / 跳转到下一个 | | `Shift+Enter` | 跳转到上一个 | | `Esc` | 关闭搜索框 | *** ## 使用示例 ### 示例 1：基础集成 ``` 文本搜索示例

页面标题

这是一段可以被搜索的文本内容...

``` ### 示例 2：带主题切换的实现 ``` 主题切换示例

大量文本内容...

``` ### 示例 3：程序化控制 ``` // 创建实例 const search = new TextSearchUI({ theme: 'light' }); // 程序化打开并搜索 search.show(); search.search('JavaScript'); // 导航匹配项 setTimeout(() => search.findNext(), 1000); setTimeout(() => search.findPrevious(), 2000); // 3秒后清除并关闭 setTimeout(() => { search.clear(); search.hide(); }, 3000); ``` ### 示例 4：与页面主题同步 ``` // 监听页面主题变化并同步 const themeObserver = new MutationObserver((mutations) => { mutations.forEach((mutation) => { if (mutation.attributeName === 'data-theme') { const pageTheme = document.body.dataset.theme; search.setTheme(pageTheme); } }); }); const search = new TextSearchUI(); // 监听body的data-theme属性 themeObserver.observe(document.body, { attributes: true, attributeFilter: ['data-theme'] }); ``` *** ## 主题说明 ### 主题模式 1. **`light`** \- 浅色主题 * 白色背景，深色文字 * 黄色高亮 (#ffeb3b) 2. **`dark`** \- 深色主题 * 深色背景 (#2a2a2a)，浅色文字 * 琥珀色高亮 (#f9a825) 3. **`auto`** \- 自动主题 * 根据系统 `prefers-color-scheme` 自动切换 * 跟随操作系统的明暗模式设置 ### CSS 变量组件使用 CSS 变量实现主题，可以通过覆盖变量自定义样式： ``` /* 自定义浅色主题颜色 */ :root { --search-highlight-bg: #your-color; --search-highlight-current-bg: #your-color; } /* 自定义深色主题颜色 */ body[data-search-theme="dark"] { --search-highlight-bg: #your-color; --search-highlight-current-bg: #your-color; } ``` *** ## 样式定制 ### 修改搜索框位置 ``` .text-search-container { top: 100px !important; left: 20px !important; right: auto !important; } ``` ### 自定义高亮颜色 ``` /* 普通高亮 */ mark.search-highlight { background-color: lime !important; color: black !important; } /* 当前高亮 */ mark.search-highlight.current { background-color: orange !important; color: white !important; } ``` ### 调整搜索框大小 ``` .text-search-container { min-width: 400px !important; padding: 20px !important; } ``` *** ## 注意事项 1. **性能考虑**：在超大页面（>10000个节点）上搜索可能会有短暂延迟 2. **不支持跨iframe搜索**：搜索范围仅限当前文档 3. **避免样式冲突**：组件使用高 z-index (10000)，确保不被其他元素遮挡 4. **主题属性**：组件会在 `body` 上添加 `data-search-theme` 属性，请避免冲突 *** ## 浏览器兼容性 * ✅ Chrome/Edge 90+ * ✅ Firefox 88+ * ✅ Safari 14+ * ✅ 移动端浏览器（支持触摸拖拽） *** ## 常见问题 ### Q: 如何禁用实时搜索？ A: 修改 `bindEvents()` 方法，移除 `input` 事件监听器，只保留 Enter 键和按钮搜索。 ### Q: 可以自定义快捷键吗？ A: 修改 `addKeyboardShortcut()` 方法中的按键判断逻辑： ``` if ((e.ctrlKey || e.metaKey) && e.key === 'k') { // 改为 Ctrl+K e.preventDefault(); this.show(); } ``` ### Q: 如何排除某些区域不被搜索？ A: 在 `highlightText()` 方法的 `acceptNode` 中添加过滤规则： ``` if (node.parentElement.closest('script, style, .text-search-container, .no-search')) { return NodeFilter.FILTER_REJECT; } ``` 然后给不想被搜索的元素添加 `.no-search` 类。 *** ## License MIT License

Version History

1.0.2

1.0.1

1.0.0