Fuse.js中includeMatches选项的高亮实现原理与使用方法

Fuse.js的模糊匹配引擎的索引生成逻辑，是基于字符级的高置信连续匹配拆分的，不会把跨模糊容错间隔的非连续匹配合并为单个大索引段。
比如搜索"nxtjs"匹配原文"Next.js"时，引擎的模糊容错会跳过中间不匹配的t.部分，单独标记Nex和js两段连续的高置信匹配为独立索引，不会生成覆盖全字符串的单一区间。同时如果你配置了多字段搜索（比如同时匹配标题、正文、标签），每个字段下的独立匹配段都会生成对应的from/to记录，最终整体索引数量看起来会远多于预想的连续匹配片段，这是引擎的正常设计，不是返回值错误。

每个match对象的核心结构为：

• key: 匹配对应的字段名，和初始化Fuse时配置的搜索字段一一对应
• value: 该字段下被匹配的完整原始文本，所有indices的下标都是基于这个文本计算的
• indices: 数组格式，每一项为[from, to]，对应一段连续匹配片段的字符起止位置

按照以下步骤处理即可实现稳定的高亮效果：

1. 对索引做预处理
   • 先把所有索引按起始位置升序排序，避免乱序导致文本拆分错位
   • 合并相邻/重叠的索引段：如果两个匹配段存在重叠，或者间隔不超过1个字符，就合并为单个高亮区间，避免渲染出细碎割裂的高亮块
   • 注意：Fuse返回的to是闭区间，即to位置的字符属于匹配范围，和JS字符串方法的半开区间规则存在1个字符的偏移差
2. 基于预处理后的索引拆分文本
   遍历原始文本，依次拆分出高亮区间之前的普通文本块、需要高亮的文本块，直到遍历完所有匹配区间，最后拼接剩余的普通文本即可。
3. 渲染时分别给普通文本和高亮文本套用不同的样式

以下是Next.js + TypeScript环境下的可复用实现示例：

interface FuseMatch {
  key: string;
  value: string;
  indices: [number, number][];
}

// 将原始匹配索引转换为可渲染的文本片段
function getHighlightParts(rawText: string, indices: [number, number][]) {
  // 索引排序
  const sortedIndices = [...indices].sort((a, b) => a[0] - b[0]);
  // 合并相邻/重叠索引
  const merged: [number, number][] = [];
  for (const interval of sortedIndices) {
    const last = merged.at(-1);
    if (last && interval[0] <= last[1] + 1) {
      last[1] = Math.max(last[1], interval[1]);
    } else {
      merged.push([...interval]);
    }
  }
  // 拆分文本片段
  const parts: Array<{ text: string; isHighlight: boolean }> = [];
  let cursor = 0;
  for (const [start, end] of merged) {
    // 高亮前的普通文本
    if (cursor < start) {
      parts.push({
        text: rawText.slice(cursor, start),
        isHighlight: false
      });
    }
    // 高亮文本，注意闭区间偏移
    parts.push({
      text: rawText.slice(start, end + 1),
      isHighlight: true
    });
    cursor = end + 1;
  }
  // 剩余普通文本
  if (cursor < rawText.length) {
    parts.push({
      text: rawText.slice(cursor),
      isHighlight: false
    });
  }
  return parts;
}

在客户端组件中调用该工具函数即可完成渲染：

'use client';
import { getHighlightParts, FuseMatch } from './utils';

interface SearchResultProps {
  matches: FuseMatch[];
}

export function SearchResultItem({ matches }: SearchResultProps) {
  return (
    <div className="p-4 border-b">
      {matches.map((match) => {
        const parts = getHighlightParts(match.value, match.indices);
        return (
          <div key={match.key} className="mb-2">
            <span className="text-sm text-gray-500">{match.key}: </span>
            {parts.map((part, idx) => (
              <span
                key={idx}
                className={part.isHighlight ? "bg-yellow-200 rounded px-0.5" : ""}
              >
                {part.text}
              </span>
            ))}
          </div>
        )
      })}
    </div>
  )
}

• 不要直接使用原始索引渲染：未做合并的原始索引会把文本拆得过于细碎，视觉体验割裂，合并相邻索引是必要的优化步骤
• 注意区间偏移问题：Fuse的索引是闭区间，直接将to值作为JSslice的结束参数时，会漏掉匹配的最后一个字符，需要手动偏移1位
• 跨字段不要混用索引：每个match条目的索引只对应当前条目下的value文本，跨字段拼接索引一定会出现字符错位
• 可通过Fuse初始化配置减少多余索引：设置minMatchCharLength参数，指定最小匹配字符长度，即可过滤掉单字符的细碎匹配段，减少返回的索引数量

内容的提问来源于stack exchange，提问作者Jon Th