Easydict 词典服务架构解析:Apple 系统词典与 MDict 离线词典的查询、渲染与资源处理链路

  • 桌面应用
  • AI 应用

【免费下载链接】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.

项目地址: https://gitcode.com/gh_mirrors/ea/Easydict
点击查看 免费下载

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)的核心行为:

  1. 过滤掉空白内容的 section;
  2. 对每个可见 section 生成 <details open><summary>词典标题</summary><iframe class="custom-iframe-container" srcdoc="..."></iframe></details> 结构,并在第一个 section 前插入大标题 <h2 class="big-word-title">;
  3. 把生成的 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:):

  1. 先调用 removeLegacyHTMLDirectories() 清理历史遗留的 HTML 输出目录(Dict HTML、.Dict HTML、easydict-apple-dictionary-html、.easydict-apple-dictionary-html.noindex);
  2. 为每个激活的词典调用 queryEntryHTMLs,其中 dictionary.entries(forSearchTerm:) 单次查询约耗时 10ms;
  3. 对每个条目的 HTML 调用 embedAudioResources 把音频转为 data URL 内嵌;
  4. 非空词典内容组装为 DictionaryHTMLSection(title: dictionary.shortName, html: ...);
  5. 最终交给 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:) 按如下顺序查找:

  1. 精确查询:mdxReader.lookupAll(word);若词库声明大小写不敏感且无命中,再尝试小写与首字母大写;
  2. 词形变化:无命中时遍历 MDictInflection.candidates(for:) 的候选;
  3. 搜索索引兜底:仍无命中且词库条目数不超过 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 列表、CSS url(...)、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):

常量值含义
maxMDictCachedDataURIBytes32MBdata URI 缓存总预算(LRU 淘汰)
maxMDictCachedSingleDataURIBytes8MB单个 data URI 上限
maxMDictResolvedDataURIBytesPerLookup1536KB单次查询解析出的 data URI 总字节预算
maxMDictResolvedDataURICountPerLookup96单次查询解析的资源个数上限
maxMDictCachedCSSBytes / maxMDictCachedCSSEntryBytes4MB / 2MBCSS 内联缓存预算
maxMDictMissingResourceCount512缺失资源 key 记录上限(防无限增长)
maxMDictSearchIndexEntryCount200_000超过该条目数不再构建搜索索引
maxMDictLinkResolutionDepth8@@@LINK= 最大递归深度

reserveDataURIBudget 同时校验单个大小、个数与总量三个维度,任一超限即跳过该资源并记录 dataURIBudgetMissCount。MDD 资源 key 会生成多种候选形式(原始 / 反斜杠化 / 去前缀斜杠 / 补前缀斜杠),以兼容不同词库的路径写法。

MDictReader:二进制格式读取层

MDictReader 目录承载 MDX/MDD 二进制格式读取,各文件职责见 mdict-reader-overview.md 与 mdict-reader-architecture.svg:

初始化:元数据优先

初始化先尝试复用同 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),分别承担音频/锚点/高度上报与按需样式适配。

与 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 二分与严格资源预算在"大词库可用性"与"内存/性能安全"之间取得平衡。理解这条从查询到渲染的完整链路,是排查词典类问题与扩展新离线词典格式的起点。

  • 桌面应用
  • AI 应用

【免费下载链接】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.

项目地址: https://gitcode.com/gh_mirrors/ea/Easydict
点击查看 免费下载

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值