TextSearchUI 使用文档

一个功能完整的网页文本搜索组件，支持高亮显示、拖拽定位、主题切换等特性。

功能特性

🔍 实时搜索：输入即搜，快速定位文本
🎯 精准定位：自动滚动到匹配位置并高亮显示
🎨 主题支持：支持浅色、深色和自动主题切换
🖱️ 可拖拽：搜索框可自由拖动，支持触摸设备
⌨️ 快捷键：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：基础集成

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>文本搜索示例</title>
</head>
<body>
    <h1>页面标题</h1>
    <p>这是一段可以被搜索的文本内容...</p>

    <script src="TextSearchUI.js"></script>
    <script>
        // 初始化搜索功能
        const search = new TextSearchUI();
    </script>
</body>
</html>

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

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>主题切换示例</title>
</head>
<body>
    <button id="theme-light">浅色</button>
    <button id="theme-dark">深色</button>
    <button id="theme-auto">自动</button>

    <div class="content">
        <p>大量文本内容...</p>
    </div>

    <script src="TextSearchUI.js"></script>
    <script>
        // 初始化搜索（默认自动主题）
        const search = new TextSearchUI({ theme: 'auto' });

        // 主题切换按钮
        document.getElementById('theme-light').onclick = () => {
            search.setTheme('light');
        };
        
        document.getElementById('theme-dark').onclick = () => {
            search.setTheme('dark');
        };
        
        document.getElementById('theme-auto').onclick = () => {
            search.setTheme('auto');
        };
    </script>
</body>
</html>

示例 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']
});

主题说明

主题模式

light - 浅色主题
- 白色背景，深色文字
- 黄色高亮 (#ffeb3b)
dark - 深色主题
- 深色背景 (#2a2a2a)，浅色文字
- 琥珀色高亮 (#f9a825)
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;
}

注意事项

性能考虑：在超大页面（>10000个节点）上搜索可能会有短暂延迟
不支持跨iframe搜索：搜索范围仅限当前文档
避免样式冲突：组件使用高 z-index (10000)，确保不被其他元素遮挡
主题属性：组件会在 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