【免费下载链接】Easydict
一个简洁优雅的词典翻译 macOS App。开箱即用,支持离线 OCR 识别,支持有道词典,🍎 苹果系统词典,🍎 苹果系统翻译,OpenAI,Gemini,DeepL,Google,Bing,腾讯,百度,阿里,小牛,彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.
Easydict 的 Dictionary 模块聚合了以本地或系统词典条目为核心的查询能力,为 Apple 系统词典与 MDict 离线词典(MDX/MDD)提供统一的 HTML 结果渲染基础设施。本文以 dictionary-overview.md 为主线,结合模块源码逐层拆解目录职责、数据流、核心实现与调试入口,帮助读者掌握如何在结果面板中组装多词典 HTML section,以及遇到词典未命中、资源缺失、样式异常等问题时如何定位。
模块定位与职责边界
Dictionary 目录只包含以本地或系统词典条目为核心的查询能力,不包含 Apple 翻译、OCR、语音或语言检测等平台能力。这两类能力被明确切分:
Dictionary(本模块):负责查词、解析离线词典文件、组装结果 HTML;Service/Apple:保留 Apple 平台能力(翻译、OCR、语音、语言检测),例如 AppleService.swift 系列文件。
这种边界设计让词典服务可以专注于"查词 + 产出 HTML",而把系统级能力隔离在另一侧,避免职责耦合。
模块目录结构(见 Dictionary 目录):
Dictionary/
├── AppleDictionary/ # Apple 系统词典服务
├── MDict/ # MDict/MDX/MDD 离线词典服务
├── DictionaryRendering/ # 共享 HTML 结果壳和 iframe 渲染
├── dictionary-overview.md # 本目录说明
└── dictionary-architecture.svg
整体架构参见 dictionary-architecture.svg,它描绘了各词典服务产出 section、共享渲染层组装模板、最终由结果面板 WKWebView 加载的完整链路。
三大子模块的职责划分
- AppleDictionary:调用系统 Dictionary Services(通过
TTTDictionary封装)获取 macOS 内置词典条目,负责条目查询、headword 有效性过滤与音频资源内嵌; - MDict:负责导入、解析和查询 MDX/MDD 文件,处理词条内
@@@LINK=跳转、CSS/JS/图片/音频等词典资源,并生成 MDict 专用 WebView 外壳; - DictionaryRendering:接收各词典服务产出的
DictionaryHTMLSection,组装结果面板模板dictionary-result.html。
三者的协作关系是:服务负责"查"与"资源处理",渲染层只负责"装壳"。
主要数据流:从查询到结果面板
用户查询进入具体词典服务后,服务产出 DictionaryHTMLSection(一个包含 title 与 html 的可发送结构体,定义见 DictionaryHTMLRenderer.swift)。共享渲染层把多个 section 组装到 dictionary-result.html 模板中,最终由结果面板的 WKWebView 加载。
渲染入口 DictionaryHTMLRenderer.render(word:sections:)(DictionaryHTMLRenderer.swift)的核心行为:
- 过滤掉空白内容的 section;
- 对每个可见 section 生成
<details open><summary>词典标题</summary><iframe class="custom-iframe-container" srcdoc="..."></iframe></details>结构,并在第一个 section 前插入大标题<h2 class="big-word-title">; - 把生成的 iframe 片段注入
dictionary-result.html的</body>之前,返回完整 HTML 字符串。
DictionaryHTMLSection 的设计让 Apple Dictionary 与 MDict 共用同一套结果壳、details 折叠布局与 iframe 转义行为,服务方只需提供已解析好的条目 HTML。
AppleDictionary:系统词典查询服务
源码位于 AppleDictionary.swift,对外暴露为 EZAppleDictionary,继承自 QueryService 且标记为 @unchecked Sendable(查询被派发到后台队列)。
查询能力声明
serviceType()返回.appleDictionary,apiKeyRequirement()返回.none(系统词典无需 API Key);supportedQueryType()与intelligentQueryTextType()均为[.dictionary, .sentence];wordLink生成dict://<encodedText>格式的链接;- 支持语言为
EZLanguageManager.shared().allLanguages的全部语言。
核心查询链路
translate(_:from:to:)(AppleDictionary.swift)通过 withCheckedThrowingContinuation 把查询派发到 DispatchQueue.global(qos: .default) 后台队列,调用 queryAllIframeHTMLResult(ofWord:fromToLanguages:inDictionaries:):
- 先调用
removeLegacyHTMLDirectories()清理历史遗留的 HTML 输出目录(Dict HTML、.Dict HTML、easydict-apple-dictionary-html、.easydict-apple-dictionary-html.noindex); - 为每个激活的词典调用
queryEntryHTMLs,其中dictionary.entries(forSearchTerm:)单次查询约耗时 10ms; - 对每个条目的 HTML 调用
embedAudioResources把音频转为 data URL 内嵌; - 非空词典内容组装为
DictionaryHTMLSection(title: dictionary.shortName, html: ...); - 最终交给
DictionaryHTMLRenderer.render生成完整 HTML。整轮查询所有词典的耗时约为 200ms(源码注释cost ~0.2s,实际以日志输出为准)。
Headword 有效性过滤
isValidHeadword(_:queryWord:language:)(AppleDictionary.swift)负责过滤系统词典返回的干扰条目:
- 先做大小写与重音归一化(
foldedString()); - 过滤形如
-log、log-这类查询log时出现的残缺条目; - 中文场景:单字直接放行,多字则比较简体化后的包含关系;
- 英文场景:
LaTeX == latex这种忽略大小写的完全匹配放行;对于queryViewController --> query这类"头词是查询词的前缀"情形会被过滤。
音频资源内嵌
embedAudioResources 用正则匹配 new Audio(...) 与 <audio src=...> 两种形式,把词典内的音频路径解析为本地文件后转成 data:audio/...;base64,... URL。常量约束(AppleDictionary.swift):
kMaxEmbeddedAudioSize = 8MB:单个音频文件大小上限;kMaxEmbeddedAudioBytesPerQuery = 16MB:单次查询内嵌音频总字节预算,超出后不再内嵌。
同时通过 FilePath 词法归一化做路径校验,确保只读取词典 Contents 目录内的资源,且对已内嵌音频有去重缓存(AudioEmbeddingState)。
语言检测
detectText 利用 TTTDictionary.languageToDictionaryNameMap 逐个语言尝试 queryDictionary(forText:language:),命中第一个能查到条目的语言即返回;全部未命中返回 .auto。这为 Apple 系统词典提供了廉价的本地方言检测能力。
MDict:离线 MDX/MDD 词典服务
MDict 子模块是 Dictionary 中最复杂的部分,覆盖"导入管理 → 二进制读取 → 词条查询 → 资源解析 → WebView 渲染"全链路。分层结构如下:
MDict/
├── MDictReader/ # MDX/MDD 二进制格式读取层
├── MDictManager.swift # 导入、持久化、启停与排序
├── MDictDictionary.swift # 词条查询、@@@LINK= 跳转、资源重写
├── MDictService.swift # QueryService 入口与 WebView 外壳
├── MDictConfigurationView.swift# 配置视图
├── MDictEntryScript.js # 音频 / 锚点 / 高度脚本
├── MDictStyleScript.js # 按需启用的样式适配脚本
└── mdict-architecture.svg
整体组件与数据流可参考 mdict-architecture.svg。
MDictManager:导入与生命周期
MDictManager(MDictManager.swift)是 @MainActor 单例,通过 Defaults 键 MDictManager_importedDictionaries 持久化 MDictDictionaryRecord(记录 mdxPath、mddPaths、enabled、title)。核心能力:
- 导入:
importDictionary(mdxURL:)按扩展名分发——.mdx走importMDX,.mdd走importMDD,其他格式抛MDictError.invalidFormat;重复导入时合并 MDD 路径并触发重载; - 伴生 MDD 自动发现:
discoverMDDFiles扫描同目录下与 MDX 同名(支持.数字后缀,如dict.mdd、dict.2.mdd)的 MDD 文件; - 查询去重:
dictionariesForLookup()只加载 enabled 记录中尚未加载的部分,重复查询复用loadingTasks中的 in-flight Task; - 启停与排序:
setEnabled、moveDictionary、removeDictionary变更后通过persist()写回 Defaults 并广播MDictManagerDidChange通知; - 记录归一化:启动时
normalizePersistedRecords会把历史上被误存为独立记录的 MDD 合并回对应 MDX 记录。
MDictDictionary:词条查询与资源解析
MDictDictionary(MDictDictionary.swift)封装一个 MDX 文件与若干可选 MDD 资源文件,提供 lookup(_:) 与 lookupResource(_:)。
查询策略
lookupDefinitions(for:visitedWords:depth:) 按如下顺序查找:
- 精确查询:
mdxReader.lookupAll(word);若词库声明大小写不敏感且无命中,再尝试小写与首字母大写; - 词形变化:无命中时遍历
MDictInflection.candidates(for:)的候选; - 搜索索引兜底:仍无命中且词库条目数不超过
maxMDictSearchIndexEntryCount = 200_000时,构建MDictSearchIndex生成候选词再查询。
@@@LINK= 跳转解析(linkedKeyword)最多递归 8 层(maxMDictLinkResolutionDepth = 8),并携带 visitedWords 集合防止环形引用死循环。
资源重写与预算控制
resolveLinks(in:) 是资源处理的核心,依次执行多步正则替换:
entry://→mdict-entry://(词条跳转协议重写);<script src>外链脚本 → 内联<script nonce="easydict-mdict">(剥离原 nonce 属性、转义</script);<link rel="stylesheet">→ 内联<style>;src/poster属性、srcset列表、CSSurl(...)、new Audio(...)、sound:///mdict-sound://链接 → 全部替换为 data URI;- 若存在同目录
.css文件(localStylesheetText),追加为内联样式。
替换前通过 shouldResolveResource 白名单过滤:data:、http(s)://、file:、about:、#、mdict-entry://、x-dictionary: 均不处理。MIME 类型由扩展名映射(png/jpeg/gif/webp/svg/avif/apng、mp3/wav/aac/m4a/ogg 等)。
资源内嵌有严格的预算控制(MDictDictionary.swift):
| 常量 | 值 | 含义 |
|---|---|---|
maxMDictCachedDataURIBytes | 32MB | data URI 缓存总预算(LRU 淘汰) |
maxMDictCachedSingleDataURIBytes | 8MB | 单个 data URI 上限 |
maxMDictResolvedDataURIBytesPerLookup | 1536KB | 单次查询解析出的 data URI 总字节预算 |
maxMDictResolvedDataURICountPerLookup | 96 | 单次查询解析的资源个数上限 |
maxMDictCachedCSSBytes / maxMDictCachedCSSEntryBytes | 4MB / 2MB | CSS 内联缓存预算 |
maxMDictMissingResourceCount | 512 | 缺失资源 key 记录上限(防无限增长) |
maxMDictSearchIndexEntryCount | 200_000 | 超过该条目数不再构建搜索索引 |
maxMDictLinkResolutionDepth | 8 | @@@LINK= 最大递归深度 |
reserveDataURIBudget 同时校验单个大小、个数与总量三个维度,任一超限即跳过该资源并记录 dataURIBudgetMissCount。MDD 资源 key 会生成多种候选形式(原始 / 反斜杠化 / 去前缀斜杠 / 补前缀斜杠),以兼容不同词库的路径写法。
MDictReader:二进制格式读取层
MDictReader 目录承载 MDX/MDD 二进制格式读取,各文件职责见 mdict-reader-overview.md 与 mdict-reader-architecture.svg:
- MDictReader.swift:reader 状态、初始化、
lookup/lookupAll/lookupDataAPI; - MDictMetadataCache.swift:把 header、key block range、record block range 持久化到 Application Support,按文件路径、大小、修改时间与 schema version 失效;
- MDictHeaderParser.swift:解析 header XML 中的版本、标题、编码、格式、大小写敏感与加密标记;
- MDictKeyBlocks.swift / MDictKeyIndex.swift:key block 边界二分、block 内精确过滤与按需 entry 解析;
- MDictRecords.swift:record block 定位、按需解压与缓存;
- MDictBinary.swift:big-endian 读取、范围校验、LZO/zlib 解压与 key info 解密;
- MDictRIPEMD128.swift:Encrypted=2 时 key index 解密用 RIPEMD-128。
初始化:元数据优先
初始化先尝试复用同 schema 的 metadata cache;cache miss 或 schema 变化才重新读取文件并解析 header。随后只解析 key block info 的首尾 key、entry 数量与压缩尺寸,并读取 record block metadata 生成 RecordBlockRange——不会解压全部 key block,也不为整本词典建立全量 key index,这是大词库能秒级打开的关键。
查询:边界二分 + block 内精确过滤
lookup/lookupAll 先用 key block 边界二分定位候选 block,只解压这些 block,再在 block 内线性过滤完全匹配的 entries——这样既只扫描一两个小 block,又兼容部分词库不满足的 block 内排序假设。若二分候选未命中,则线性扫描轻量 key block 边界兜底,避免直接退回全量索引。随后根据相邻 entry 计算 record span,定位 record block、按需解压并读取 record bytes,最后按 header encoding 解码为字符串。查询 MDD 资源的 lookupData 走同一流程但直接返回原始 Data。
安全与兼容性约束
MDictReader拒绝所有 key-header encrypted bit 被置位的文件;- 解压一律由 8 字节 block header 判定 none/zlib/LZO,避免 size 启发式误判压缩块;
- Encrypted=2 的 key block info 用 RIPEMD-128 派生 key 解密。
MDictService:查询入口与 WebView 外壳
MDictService(MDictService.swift)是 QueryService 子类:
translate从MDictManager.shared.dictionariesForLookup()取启用词典,逐个dict.lookup(text);内容非空的 section 才加入列表,HTML 词库直接用原始 HTML,纯文本词库经plainTextToHTML转义为<p>/<br>结构;renderWebViewHTML把 section 组装为<details class="mdict-section" open><summary>...</summary><div class="mdict-entry">...</div></details>,并注入 CSP、样式与页面脚本:- CSP:
default-src 'none',仅放行img-src/media-src的data: blob:、font-src data:,脚本与样式'unsafe-inline'; - 样式:
webViewStyle使用 CSS 变量 +prefers-color-scheme做浅色/深色适配,对mdict-sound://、sound://、data:audio链接统一渲染为 24px 发音按钮,深色模式下强制修正文本与背景色(filter: none !important); - 脚本:依次内联
darkreader.min、MDictStyleScript、MDictEntryScript(见 MDictEntryScript.js 与 MDictStyleScript.js),分别承担音频/锚点/高度上报与按需样式适配。
- CSP:
与 Apple Dictionary 的 iframe 方案不同,MDict 把词条直接嵌入可折叠 section,让 WebKit 直接处理外观、尺寸与链接行为,省去 iframe 高度补偿逻辑。
共享渲染层:DictionaryRendering
DictionaryRendering 只负责把已经查到、已完成资源处理的词典条目组装成可加载 HTML,不负责查词、网络请求、资源解析或服务配置(详见 dictionary-rendering-overview.md)。
- DictionaryHTMLRenderer.swift 提供
entryStyle(bodyMargin:extraCSS:)与render(word:sections:baseHTML:):前者生成含深色模式invert + hue-rotate + saturate + brightness滤镜适配的通用样式;后者负责 iframe 组装与模板注入; - dictionary-result.html 是 WKWebView 加载的外层模板,内置折叠分组样式、iframe 高度更新脚本、深色模式颜色适配与字体缩放脚本;
- Apple Dictionary 与 MDict 仍各自拥有查词、资源定位、链接处理与服务级错误处理,本目录只提供两者共用的"展示壳"。
调试入口与常见问题排查
按 dictionary-overview.md 提供的调试线索,结合源码给出可操作的排查路径:
系统词典未命中
- 检查 AppleDictionary.swift 中
queryEntryHTMLs的dictionary.entries(forSearchTerm:)返回值,以及isValidHeadword过滤是否误杀(重点看中文多字包含判断与英文前缀过滤逻辑); - 音频未内嵌时检查
embedAudioResources的正则匹配与audioDataURL的路径校验、大小上限(单文件 8MB / 单次查询 16MB)。
MDict 未命中或资源缺失
- 未命中:沿
MDictDictionary.lookupDefinitions检查精确查询 → 词形变化 → 搜索索引兜底三层链路,以及MDictReader.lookupAll的边界二分与 block 内过滤; - 资源缺失:检查
resolveLinks的替换顺序、shouldResolveResource白名单、resourceKeyCandidates的路径变体,以及reserveDataURIBudget是否因预算耗尽而跳过(dataURIBudgetMissCount); - 加载失败:从
MDictManager.loadErrors与MDictReader(url:)初始化错误入手,重点看 metadata cache 是否因 schema 变化被丢弃。
结果高度或样式异常
- 检查 dictionary-result.html 中的 iframe 高度更新脚本;
- MDict 样式异常检查
MDictService.webViewStyle的深色模式覆盖与MDictStyleScript是否按需启用; - 某词典内容缺少图片、音频或链接行为时,回到具体服务的资源解析代码排查(Apple Dictionary 看音频内嵌,MDict 看资源重写)。
小结
Easydict 的 Dictionary 模块通过"服务查词 + 共享渲染"的分层设计,让 Apple 系统词典与 MDict 离线词典复用同一套结果面板壳:DictionaryHTMLSection 作为服务与渲染层之间的稳定契约,DictionaryHTMLRenderer + dictionary-result.html 提供 iframe/折叠/深色模式/字体缩放等展示能力。MDict 侧则进一步下钻出 MDictReader 二进制层、MDictManager 生命周期层与 MDictDictionary 资源解析层,用 metadata cache、按需解压、block 二分与严格资源预算在"大词库可用性"与"内存/性能安全"之间取得平衡。理解这条从查询到渲染的完整链路,是排查词典类问题与扩展新离线词典格式的起点。
【免费下载链接】Easydict
一个简洁优雅的词典翻译 macOS App。开箱即用,支持离线 OCR 识别,支持有道词典,🍎 苹果系统词典,🍎 苹果系统翻译,OpenAI,Gemini,DeepL,Google,Bing,腾讯,百度,阿里,小牛,彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



