fuzzball.js API 完整参考手册：TypeScript 类型定义、全部选项与评分函数清单-平芜编程栈

fuzzball.js API 完整参考手册：TypeScript 类型定义、全部选项与评分函数清单

【免费下载链接】fuzzball.jsEasy to use and powerful fuzzy string matching, port of fuzzywuzzy.项目地址: https://gitcode.com/gh_mirrors/fu/fuzzball.js

fuzzball.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~100（distance除外）。类型定义中每个函数对应的选项接口见 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 bear"vs"wuzzy fuzzy was a bear"，ratio只得 91 分，而token_sort_ratio得 100 分——词序混乱就交给 token 系函数。

三、全部 Options 选项速查表 ⚙️

选项通过第三个参数传入，接口继承关系为FuzzballBaseOptions（基础）→ 各函数扩展接口。

3.1 基础选项（FuzzballBaseOptions，所有函数可用）

选项	类型 / 默认值	说明
`full_process`	boolean /`true`	打分前做清洗：转小写、非字母数字变空格
`force_ascii`	boolean /`false`	清洗时直接删除非 ASCII 字符（需`full_process`为 true）
`collapseWhitespace`	boolean /`true`	连续空白合并为一个空格
`useCollator`	boolean /`false`	用`Intl.Collator`做 locale 敏感比较（如`ä`匹配`a`），有性能开销
`wildcards`	string	指定通配符字符集（如`"*x"`），计算编辑距离时这些字符可匹配任意字符
`astral`	boolean /`false`	正确处理 Emoji 等非 BMP（星界）符号，否则会被当成多个字符
`normalize`	boolean	归一化 Unicode 表示；`astral: true`时默认开启

3.2 各函数专属选项

接口	选项	默认值	说明
`FuzzballRatioOptions`	`ratio_alg`	`"levenshtein"`	改用`"difflib"`算法（基于匹配字符数，非最短编辑距离）
`FuzzballRatioOptions`	`autojunk`	`true`	difflib 的"自动 junk"启发式开关
`FuzzballTokenSetOptions`	`trySimple`	—	把 simple/partial ratio 也纳入 token set 的打分组合
`FuzzballTokenSetOptions`	`sortBySimilarity`	—	token 按相似度排序而非字母序（`token_set_ratio`也可用）
`FuzzballExtractOptions`	`scorer`	`ratio`	自定义打分函数
`FuzzballExtractOptions`	`processor`	—	从对象候选中提取用于打分的字符串
`FuzzballExtractOptions`	`limit`/`cutoff`	0 / 0	最多返回条数 / 最低分数门槛
`FuzzballExtractOptions`	`returnObjects`	`false`	返回`{choice, score, key}`对象数组而非元组
`FuzzballAsyncExtractOptions`	`abortController`/`cancelToken`/`asyncLoopOffset`	— / — / 256	异步取消控制；两次异步让出之间的循环次数
`FuzzballDedupeOptions`	`keepmap`	`false`	去重结果附带每个唯一项的匹配明细

类型定义中这些接口的完整声明见 fuzzball.d.ts#L1-L94。

四、批量搜索 API：extract 三兄弟 🔍

从候选列表里找出最匹配的前 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-L62）：

cutoff未指定时默认 70（extract 的默认是 0）；
limit在 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可知：

能力	完整版	lite	ultra_lite
`partial_ratio`等 5 个 partial 函数	✅	❌	❌
`token_similarity_sort_ratio`/`WRatio`	✅	❌	❌
`astral`（Emoji 安全）	✅	❌	❌
`useCollator`排序比较	✅	✅	❌
`dedupe`	✅	✅	❌
非 ASCII 字母数字检查	保留	保留	会剥离非 ASCII

按需引入即可：fuzzball/lite、fuzzball/ultra_lite（exports 配置见 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时通配符整体不可用。