fuzzball.js API 完整参考手册TypeScript 类型定义、全部选项与评分函数清单【免费下载链接】fuzzball.jsEasy to use and powerful fuzzy string matching, port of fuzzywuzzy.项目地址: https://gitcode.com/gh_mirrors/fu/fuzzball.jsfuzzball.js 是一个用于JavaScript 模糊字符串匹配Fuzzy String Matching的开源库是 Python 库 fuzzywuzzy / TheFuzz 的 JS 移植版。本文是它的API 完整参考手册基于随包附带的 TypeScript 类型定义文件逐一讲清33 个导出函数、全部 options 选项、批量搜索与模糊去重的用法以及 lite / ultra_lite 轻量版的差异帮助新手快速选对评分函数、配对口。一、项目结构与类型定义文件在哪里 写 TypeScript 项目时IDE 的智能提示全部来自仓库根目录的类型声明文件文件说明fuzzball.d.ts完整版类型定义入口package.json中types指向它lite/fuzzball_lite.js轻量版实现lite/esm/fuzzball_lite.esm.min.d.ts轻量版 ESM 类型定义ultra_lite/fuzzball_ultra_lite.js极简版实现ultra_lite/esm/fuzzball_ultra_lite.esm.min.d.ts极简版 ESM 类型定义jsdocs/fuzzball.md自动生成的 API 文档每个函数的参数表核心源码入口为 fuzzball.js字符串预处理逻辑在 lib/utils.js去重逻辑在 lib/process.js。npm install fuzzball // 安装完整包含类型定义二、评分函数完整清单10 个打分函数怎么选 所有评分函数签名一致函数名(str1, str2, opts?) → number分数 0~100distance除外。类型定义中每个函数对应的选项接口见 fuzzball.d.ts#L198-L210。函数作用典型场景ratio整体相似度默认 Levenshtein 距离计算两个短语整体打分distance原始 Levenshtein 编辑距离0 以上越小越像只需要差异大小partial_ratio长串中的最佳子串 vs 短串查询词是目标串的一部分token_sort_ratio按字母排序单词后再比词序不同但词相同token_set_ratio取交集/差值三种组合的最高分一侧多出若干词token_similarity_sort_ratio按相似度而非字母排序单词词首字母不同的近似词partial_token_sort_ratio子串 单词排序组合场景partial_token_set_ratio子串 token 集合组合场景partial_token_similarity_sort_ratio子串 相似度排序组合场景WRatio按两串长度比例自动加权取多个算法的最高分不知道用哪个时的通用选择 直觉示例fuzzy wuzzy was a bearvswuzzy fuzzy was a bearratio只得 91 分而token_sort_ratio得 100 分——词序混乱就交给 token 系函数。三、全部 Options 选项速查表 ⚙️选项通过第三个参数传入接口继承关系为FuzzballBaseOptions基础→ 各函数扩展接口。3.1 基础选项FuzzballBaseOptions所有函数可用选项类型 / 默认值说明full_processboolean /true打分前做清洗转小写、非字母数字变空格force_asciiboolean /false清洗时直接删除非 ASCII 字符需full_process为 truecollapseWhitespaceboolean /true连续空白合并为一个空格useCollatorboolean /false用Intl.Collator做 locale 敏感比较如ä匹配a有性能开销wildcardsstring指定通配符字符集如*x计算编辑距离时这些字符可匹配任意字符astralboolean /false正确处理 Emoji 等非 BMP星界符号否则会被当成多个字符normalizeboolean归一化 Unicode 表示astral: true时默认开启3.2 各函数专属选项接口选项默认值说明FuzzballRatioOptionsratio_alglevenshtein改用difflib算法基于匹配字符数非最短编辑距离FuzzballRatioOptionsautojunktruedifflib 的自动 junk启发式开关FuzzballTokenSetOptionstrySimple—把 simple/partial ratio 也纳入 token set 的打分组合FuzzballTokenSetOptionssortBySimilarity—token 按相似度排序而非字母序token_set_ratio也可用FuzzballExtractOptionsscorerratio自定义打分函数FuzzballExtractOptionsprocessor—从对象候选中提取用于打分的字符串FuzzballExtractOptionslimit/cutoff0 / 0最多返回条数 / 最低分数门槛FuzzballExtractOptionsreturnObjectsfalse返回{choice, score, key}对象数组而非元组FuzzballAsyncExtractOptionsabortController/cancelToken/asyncLoopOffset— / — / 256异步取消控制两次异步让出之间的循环次数FuzzballDedupeOptionskeepmapfalse去重结果附带每个唯一项的匹配明细类型定义中这些接口的完整声明见 fuzzball.d.ts#L1-L94。四、批量搜索 APIextract 三兄弟 从候选列表里找出最匹配的前 N 名三个入口类型签名见 fuzzball.d.ts#L212-L225函数风格说明extract(query, choices, opts)同步候选是字符串数组时返回[choice, score, index]是对象时返回[choice, score, key]extractAsync(query, choices, opts, callback)回调内部循环非阻塞适合大列表extractAsPromised(query, choices, opts)Promise支持abortController中途取消搜索fuzz.extract(mr. harry hood, [Hood, Harry, Mr. Minor, Mr. Henry Hood], { scorer: fuzz.token_set_ratio }); // [ [Hood, Harry, 100, 0], [Mr. Henry Hood, 85, 2], [Mr. Minor, 40, 1] ]五、模糊去重dedupe 选项与默认值 ✂️dedupe(contains_dupes, opts)用模糊匹配识别近似重复项保留每组中最长信息最全的一条。关键行为见 lib/process.js#L49-L62cutoff未指定时默认 70extract 的默认是 0limit在 dedupe 中会被忽略并打印警告注意反直觉点cutoff 越低 → 判定为重复的越多 → 结果列表越短keepmap: true时第三项返回该唯一项对应的全部extract匹配明细。六、预处理工具函数性能优化利器⚡函数作用full_process(str, opts?)独立执行清洗可对候选列表预先处理后设full_process: false提速process_and_sort(str)分词 排序 拼接配合proc_sorted: true复用unique_tokens(str, opts?)分词去重配合tokens: [t1, t2]传给 token_set 打分函数实现细节见 lib/utils.js#L18-L30。七、lite 与 ultra_lite类型定义的差异对比 三个版本压缩后体积约为15.1 kB / 6.3 kB / 4.0 kB。对照各.d.ts可知能力完整版liteultra_litepartial_ratio等 5 个 partial 函数✅❌❌token_similarity_sort_ratio/WRatio✅❌❌astralEmoji 安全✅❌❌useCollator排序比较✅✅❌dedupe✅✅❌非 ASCII 字母数字检查保留保留会剥离非 ASCII按需引入即可fuzzball/lite、fuzzball/ultra_liteexports 配置见 package.json#L9-L26。八、新手常见问题 FAQ ❓默认打分函数是什么extract未指定scorer时默认ratio想要万金油可显式传WRatio。打分偏低怎么办先确认full_process清洗是否帮你/害了你词序问题换token_sort_ratio子串场景换partial_ratio整体拿不准用WRatio。difflib 模式能开通配符吗不能ratio_alg: difflib时wildcards与useCollator均不支持。通配符大小写默认大小写不敏感full_process: false时敏感且astral: true时通配符整体不可用。 本手册与源码同步版本对应package.json中的 v2.2.6每个函数的完整参数表可查阅自动生成的 jsdocs/fuzzball.md。【免费下载链接】fuzzball.jsEasy to use and powerful fuzzy string matching, port of fuzzywuzzy.项目地址: https://gitcode.com/gh_mirrors/fu/fuzzball.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考