Class Highlighter

文本高亮器类

提供在指定DOM元素中高亮显示关键词的功能，支持导航到不同的匹配项。可以配置高亮样式、标签类型，并提供前进/后退导航功能。

Example

// 基本用法（单个关键词）
const container = document.getElementById('content')
const highlighter = new Highlighter(container)
highlighter.apply('搜索关键词')

// 多个关键词高亮
highlighter.apply(['JavaScript', 'TypeScript', 'React'])

// 使用配置对象
const highlighter = new Highlighter(container, {
  highlightTag: 'span',
  highlightClass: 'my-highlight',
  activeClass: 'my-active',
  skipTags: ['SCRIPT', 'STYLE', 'CODE'],
  smartScroll: true,      // 启用智能滚动
  scrollPadding: 100      // 设置视口内边距为100px
})

// 带回调的高级用法
const highlighter = new Highlighter(container, {
  highlightClass: 'search-result'
}, {
  onHighlightApplied: (count, keywords) => {
    console.log(`找到 ${count} 个 "${keywords}" 的匹配项`)
  },
  onNavigate: (index, total, element) => {
    console.log(`当前: ${index + 1}/${total}`)
  }
})

// 高级选项（多个关键词）
highlighter.apply(['JavaScript', 'API'], {
  caseSensitive: true,  // 区分大小写
  wholeWord: true       // 只匹配完整单词
})

// 导航功能
highlighter.next()     // 下一个匹配项
highlighter.previous() // 上一个匹配项
highlighter.jumpTo(5)  // 跳转到第6个匹配项

Constructors

constructor

new Highlighter(
    targetNode: HTMLElement,
    config?: HighlighterConfig,
    callbacks?: HighlightCallbacks,
): Highlighter

创建一个新的高亮器实例

Parameters

targetNode: HTMLElement
要进行高亮操作的目标DOM元素
config: HighlighterConfig = {}
高亮器配置选项
callbacks: HighlightCallbacks = {}
事件回调函数

Returns Highlighter

Example

const container = document.getElementById('content')

// 使用默认配置
const highlighter1 = new Highlighter(container)

// 自定义配置
const highlighter2 = new Highlighter(container, {
  highlightTag: 'span',
  highlightClass: 'search-highlight',
  activeClass: 'current-match',
  skipTags: ['SCRIPT', 'STYLE', 'CODE'],
  scrollOptions: { behavior: 'auto', block: 'nearest' },
  smartScroll: false,     // 禁用智能滚动
  scrollPadding: 30       // 设置较小的视口内边距
})

// 带回调的配置
const highlighter3 = new Highlighter(container, {
  highlightClass: 'result'
}, {
  onHighlightApplied: (count) => console.log(`找到 ${count} 个匹配项`),
  onNavigate: (index, total) => console.log(`${index + 1}/${total}`)
})

Methods

apply

apply(keywords: string | string[], options?: HighlightOptions): Promise<number>
应用高亮到指定关键词（异步版本）

在目标元素中搜索并高亮显示指定的关键词。会自动清理之前的高亮，并为新的匹配项设置高亮样式。完成后会自动定位到第一个匹配项。异步版本支持性能优化，适合处理大文档。
Parameters
- keywords: string | string[]
  要高亮的关键词，可以是单个字符串或字符串数组，空字符串或仅包含空白字符的字符串将被忽略
- options: HighlightOptions = {}
  高亮选项配置
Returns Promise<number>
匹配项的数量
Example
```
const highlighter = new Highlighter(document.body)

// 基本高亮（单个关键词）
const count1 = await highlighter.apply('JavaScript')

// 多个关键词高亮
const count2 = await highlighter.apply(['JavaScript', 'TypeScript', 'React'])

// 区分大小写的高亮
const count3 = await highlighter.apply(['JavaScript', 'API'], { caseSensitive: true })

// 只匹配完整单词
const count4 = await highlighter.apply(['script', 'code'], { wholeWord: true })

// 组合选项
const count5 = await highlighter.apply(['API', 'SDK'], {
  caseSensitive: true,
  wholeWord: true
})
```
Remarks
- 该方法会跳过配置中指定的标签内的文本
- 不会在已经高亮的元素内进行嵌套高亮
- 使用TreeWalker遍历文本节点以确保性能
- 关键词中的正则表达式特殊字符会被自动转义
- 支持性能优化，在处理大量节点时会分批处理避免阻塞UI
- 多个关键词会被组合成一个正则表达式进行匹配
- Defined in src/modules/dom/highlighter/index.ts:358

applyRegex

applyRegex(regex: RegExp): Promise<number>
使用自定义正则表达式应用高亮（异步版本）

使用提供的正则表达式在目标元素中搜索并高亮显示匹配的文本。会自动清理之前的高亮，并为新的匹配项设置高亮样式。异步版本支持性能优化，适合处理大文档。
Parameters
- regex: RegExp
  用于匹配的正则表达式，必须包含全局标志 'g'
Returns Promise<number>
匹配项的数量
Example
```
const highlighter = new Highlighter(document.body)

// 高亮所有邮箱地址
const emailRegex = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g
const count1 = await highlighter.applyRegex(emailRegex)

// 高亮日期格式 YYYY-MM-DD
const dateRegex = /\d{4}-\d{2}-\d{2}/g
const count2 = await highlighter.applyRegex(dateRegex)

// 高亮 "Chapter" 或 "Section" 后跟数字
const chapterRegex = /(Chapter|Section)\s+\d+/gi
const count3 = await highlighter.applyRegex(chapterRegex)
```
Throws
如果传入的正则表达式没有 'g' 标志，则会抛出错误
Remarks
- 该方法会跳过配置中指定的标签内的文本
- 不会在已经高亮的元素内进行嵌套高亮
- 使用TreeWalker遍历文本节点以确保性能
- 支持性能优化，在处理大量节点时会分批处理避免阻塞UI
- 正则表达式必须包含全局标志 'g' 以确保能匹配所有实例
- Defined in src/modules/dom/highlighter/index.ts:510

applyRegexSync

applyRegexSync(regex: RegExp): number
使用自定义正则表达式应用高亮（同步版本）

使用提供的正则表达式在目标元素中搜索并高亮显示匹配的文本。会自动清理之前的高亮，并为新的匹配项设置高亮样式。同步版本不包含性能优化，适合处理小到中等大小的文档。
Parameters
- regex: RegExp
  用于匹配的正则表达式，必须包含全局标志 'g'
Returns number
匹配项的数量
Example
```
const highlighter = new Highlighter(document.body)

// 高亮所有邮箱地址
const emailRegex = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g
const count1 = highlighter.applyRegexSync(emailRegex)

// 高亮日期格式 YYYY-MM-DD
const dateRegex = /\d{4}-\d{2}-\d{2}/g
const count2 = highlighter.applyRegexSync(dateRegex)
```
Throws
如果传入的正则表达式没有 'g' 标志，则会抛出错误
Remarks
- 该方法会跳过配置中指定的标签内的文本
- 不会在已经高亮的元素内进行嵌套高亮
- 使用TreeWalker遍历文本节点以确保性能
- 同步执行，不会分批处理，适合小到中等大小的文档
- 正则表达式必须包含全局标志 'g' 以确保能匹配所有实例
- Defined in src/modules/dom/highlighter/index.ts:586

applySync

applySync(keywords: string | string[], options?: HighlightOptions): number
应用高亮到指定关键词（同步版本）

在目标元素中搜索并高亮显示指定的关键词。会自动清理之前的高亮，并为新的匹配项设置高亮样式。完成后会自动定位到第一个匹配项。同步版本不包含性能优化，适合处理小到中等大小的文档。
Parameters
- keywords: string | string[]
  要高亮的关键词，可以是单个字符串或字符串数组，空字符串或仅包含空白字符的字符串将被忽略
- options: HighlightOptions = {}
  高亮选项配置
Returns number
匹配项的数量
Example
```
const highlighter = new Highlighter(document.body)

// 基本高亮（单个关键词）
const count1 = highlighter.applySync('JavaScript')

// 多个关键词高亮
const count2 = highlighter.applySync(['JavaScript', 'TypeScript', 'React'])

// 区分大小写的高亮
const count3 = highlighter.applySync(['JavaScript', 'API'], { caseSensitive: true })

// 只匹配完整单词
const count4 = highlighter.applySync(['script', 'code'], { wholeWord: true })

// 组合选项
const count5 = highlighter.applySync(['API', 'SDK'], {
  caseSensitive: true,
  wholeWord: true
})
```
Remarks
- 该方法会跳过配置中指定的标签内的文本
- 不会在已经高亮的元素内进行嵌套高亮
- 使用TreeWalker遍历文本节点以确保性能
- 关键词中的正则表达式特殊字符会被自动转义
- 同步执行，不会分批处理，适合小到中等大小的文档
- 多个关键词会被组合成一个正则表达式进行匹配
- Defined in src/modules/dom/highlighter/index.ts:447

destroy

destroy(): void
销毁高亮器实例

清理所有内部状态、引用和事件监听器（如果有）。在组件卸载时调用此方法以防止内存泄漏。

Returns void
- Defined in src/modules/dom/highlighter/index.ts:1084

findNextOffscreenIndex

findNextOffscreenIndex(): number
查找下一个在视口外的匹配项的索引

Returns number
找到的元素的索引，如果所有元素都在视口内则返回 -1
- Defined in src/modules/dom/highlighter/index.ts:1028

findPreviousOffscreenIndex

findPreviousOffscreenIndex(): number
查找上一个在视口外的匹配项的索引

Returns number
找到的元素的索引，如果所有元素都在视口内则返回 -1
- Defined in src/modules/dom/highlighter/index.ts:1036

getAllHighlights

getAllHighlights(): HTMLElement[]

获取所有高亮元素

Returns HTMLElement[]

所有高亮元素的数组副本

Example

const highlighter = new Highlighter(document.body)
highlighter.apply('JavaScript')
const allHighlights = highlighter.getAllHighlights()
console.log(`总共有 ${allHighlights.length} 个高亮元素`)

getCurrentElement

getCurrentElement(): null | HTMLElement

获取当前激活的高亮元素

Returns null | HTMLElement

当前激活的高亮元素，如果没有则返回null

Example

const highlighter = new Highlighter(document.body)
highlighter.apply('JavaScript')
const activeElement = highlighter.getCurrentElement()
if (activeElement) {
  console.log('当前激活元素的文本:', activeElement.textContent)
}

getCurrentIndex

getCurrentIndex(): number
获取当前激活项的索引

返回当前激活的高亮项在所有匹配项中的索引位置（从0开始）。如果没有匹配项，返回-1。

Returns number
当前激活项的索引，如果没有匹配项则返回-1
Example
```
const highlighter = new Highlighter(document.body)
highlighter.apply('JavaScript')
console.log(`当前是第 ${highlighter.getCurrentIndex() + 1} 个匹配项`)
```
- Defined in src/modules/dom/highlighter/index.ts:767

getCurrentKeyword

getCurrentKeyword(): string
获取当前高亮的关键词（兼容性方法）

Returns string
当前高亮的关键词字符串，多个关键词用逗号分隔，如果没有高亮则返回空字符串
Deprecated
建议使用 getCurrentKeywords() 方法
Example
```
const highlighter = new Highlighter(document.body)
highlighter.apply(['JavaScript', 'TypeScript'])
console.log(`当前高亮关键词: ${highlighter.getCurrentKeyword()}`)
```
- Defined in src/modules/dom/highlighter/index.ts:825

getCurrentKeywords

getCurrentKeywords(): string[]
获取当前高亮的关键词

Returns string[]
当前高亮的关键词数组，如果没有高亮则返回空数组
Example
```
const highlighter = new Highlighter(document.body)
highlighter.apply(['JavaScript', 'TypeScript'])
console.log(`当前高亮关键词: ${highlighter.getCurrentKeywords().join(', ')}`)
```
- Defined in src/modules/dom/highlighter/index.ts:783

getCurrentPattern

getCurrentPattern(): RegExp | string[]

获取当前高亮的模式

Returns RegExp | string[]

当前高亮的模式，可能是关键词数组或正则表达式

Example

const highlighter = new Highlighter(document.body)

// 使用关键词高亮
await highlighter.apply(['JavaScript', 'tutorial'])
console.log(highlighter.getCurrentPattern()) // ['JavaScript', 'tutorial']

// 使用正则表达式高亮
const emailRegex = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g
await highlighter.applyRegex(emailRegex)
console.log(highlighter.getCurrentPattern()) // RegExp object

getMatchCount

getMatchCount(): number
获取匹配总数

返回当前高亮关键词的匹配项总数。

Returns number
匹配项的总数
Example
```
const highlighter = new Highlighter(document.body)
highlighter.apply('JavaScript')
console.log(`找到 ${highlighter.getMatchCount()} 个匹配项`)
```
- Defined in src/modules/dom/highlighter/index.ts:748

jumpTo(index: number): boolean
跳转到指定索引的高亮项

直接跳转到指定索引位置的高亮项。索引从0开始计算。
Parameters
- index: number
  目标索引（从0开始）
Returns boolean
是否成功跳转
Example
```
const highlighter = new Highlighter(document.body)
highlighter.apply('JavaScript')
const success = highlighter.jumpTo(5) // 跳转到第6个匹配项
```
- Defined in src/modules/dom/highlighter/index.ts:721

jumpToNextOffscreen

jumpToNextOffscreen(): boolean
跳转到下一个在视口外的匹配项

如果找到了屏幕外的匹配项，则直接跳转到那里。如果所有匹配项都在视口内，则行为与 next() 相同，以确保总有反馈。

Returns boolean
是否成功执行了跳转或导航操作
- Defined in src/modules/dom/highlighter/index.ts:1047

jumpToPreviousOffscreen

jumpToPreviousOffscreen(): boolean
跳转到上一个在视口外的匹配项

如果找到了屏幕外的匹配项，则直接跳转到那里。如果所有匹配项都在视口内，则行为与 previous() 相同，以确保总有反馈。

Returns boolean
是否成功执行了跳转或导航操作
- Defined in src/modules/dom/highlighter/index.ts:1066

next(): boolean
跳转到下一个高亮项

将当前激活的高亮项切换到下一个匹配项。如果当前是最后一个，则循环到第一个。会自动滚动到目标元素并更新激活状态。

Returns boolean
是否成功跳转
Example
```
const highlighter = new Highlighter(document.body)
highlighter.apply('JavaScript')
const success = highlighter.next() // 跳转到下一个匹配项
```
- Defined in src/modules/dom/highlighter/index.ts:683

previous(): boolean
跳转到上一个高亮项

将当前激活的高亮项切换到上一个匹配项。如果当前是第一个，则循环到最后一个。会自动滚动到目标元素并更新激活状态。

Returns boolean
是否成功跳转
Example
```
const highlighter = new Highlighter(document.body)
highlighter.apply('JavaScript')
const success = highlighter.previous() // 跳转到上一个匹配项
```
- Defined in src/modules/dom/highlighter/index.ts:702

remove

remove(): void
移除所有高亮

清除目标元素中的所有高亮标记，将高亮的文本恢复为普通文本。同时重置内部状态，包括高亮元素列表和当前索引。

Returns void
Example
```
const highlighter = new Highlighter(document.body)
highlighter.apply('JavaScript')
// ... 一些操作后
highlighter.remove() // 清除所有高亮
```
- Defined in src/modules/dom/highlighter/index.ts:624

updateCallbacks

updateCallbacks(newCallbacks: Partial<HighlightCallbacks>): void
更新回调函数

动态更新事件回调函数。
Parameters
- newCallbacks: Partial<HighlightCallbacks>
  新的回调函数
Returns void
Example
```
const highlighter = new Highlighter(document.body)
highlighter.updateCallbacks({
  onNavigate: (index, total) => {
    console.log(`导航到: ${index + 1}/${total}`)
  }
})
```
- Defined in src/modules/dom/highlighter/index.ts:904

updateConfig

updateConfig(newConfig: Partial<HighlighterConfig>): void
更新配置

动态更新高亮器的配置。注意：某些配置更改可能需要重新应用高亮才能生效。
Parameters
- newConfig: Partial<HighlighterConfig>
  新的配置选项
Returns void
Example
```
const highlighter = new Highlighter(document.body)
highlighter.updateConfig({
  highlightClass: 'new-highlight-class',
  scrollOptions: { behavior: 'auto' }
})
```
- Defined in src/modules/dom/highlighter/index.ts:883

Class Highlighter

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns Highlighter

Example

Methods

apply

Parameters

Returns Promise<number>

Example

Remarks

applyRegex

Parameters

Returns Promise<number>

Example

Throws

Remarks

applyRegexSync

Parameters

Returns number

Example

Throws

Remarks

applySync

Parameters

Returns number

Example

Remarks

destroy

Returns void

findNextOffscreenIndex

Returns number

findPreviousOffscreenIndex

Returns number

getAllHighlights

Returns HTMLElement[]

Example

getCurrentElement

Returns null | HTMLElement

Example

getCurrentIndex

Returns number

Example

getCurrentKeyword

Returns string

Deprecated

Example

getCurrentKeywords

Returns string[]

Example

getCurrentPattern

Returns RegExp | string[]

Example

getMatchCount

Returns number

Example

jumpTo

Parameters

Returns boolean

Example

jumpToNextOffscreen

Returns boolean

jumpToPreviousOffscreen

Returns boolean

next

Returns boolean

Example

previous

Returns boolean

Example

remove

Returns void

Example

updateCallbacks

Parameters