为什么 QuickLook 里按不了 Cmd+F?揭秘 FluxMarkdown 搜索启动方案的设计思路

原创2026-10-13 22:13:391,381 阅读

为什么 QuickLook 里按不了 Cmd+F?揭秘 FluxMarkdown 搜索启动方案的设计思路

FluxMarkdown 是一款 macOS Markdown 预览工具:在 Finder 里选中文件按空格,QuickLook 面板立刻渲染出带 Mermaid 图表、KaTeX 公式和目录的精美预览。可当你在预览里习惯性按下 ⌘F 时,搜索框纹丝不动。这篇文章带你弄清楚 QuickLook 搜索为什么失灵,以及 FluxMarkdown 的 QuickLook 搜索启动方案是如何一步步破局的。

FluxMarkdown QuickLook 预览效果演示

QuickLook 预览为什么不能直接搜索?

很多用户都会遇到这个困惑:预览界面里明明能看到搜索入口,为什么就是输入不了文字?

原因不在 FluxMarkdown,而在 macOS 的架构限制:

  • QuickLook 扩展运行在强沙盒中:预览扩展(Sources/MarkdownPreview/)没有普通 App 的权限,很多常规操作被系统直接拒绝;
  • 键盘焦点不归扩展管:QuickLook 面板的宿主是 Finder,系统会明确警告"Quick Look 扩展的视图不应成为第一响应者(first responder)",所以预览里的 HTML 搜索框收不到任何键盘输入;
  • 直接拉起主应用的路也被堵死:早期尝试在扩展内直接调用系统打开文件接口,全部返回失败错误(如 NSOSStatus -54)。

项目调试档案把这些过程完整记录了下来:DEBUG_QUICKLOOK_SEARCH_INPUT.md、DEBUG_SEARCH_LAUNCH_BROKER.md。

结论很明确:与其在 QuickLook 里造一个"假搜索框",不如设计一条可靠的搜索启动链路,一键把搜索交给主应用。

方案核心:一键搜索启动链路

FluxMarkdown 的 QuickLook 搜索启动方案由三块组成:一个看得见的搜索按钮、一个按需启动的 XPC 服务、一份窗口定位信息。

搜索按钮:看得见的出口

预览工具栏右上角有一个放大镜按钮(makeSearchButton()),本地化文案就叫"在 FluxMarkdown 中搜索"。关键点在于:

button.keyEquivalent = "f"
button.keyEquivalentModifierMask = .command

它把 ⌘F 注册为按钮快捷键。这样无论用户是按 ⌘F、点按钮,还是通过 Finder 菜单触发"查找"动作,都会被 QuickLookFindShortcut 捕获,统一进入搜索启动流程。

XPC 启动服务:绕过沙盒限制的关键

扩展内直接调用打不开主应用,于是项目把"启动主应用"这件事交给一个独立的 XPC 服务:SearchLauncher。

它的身份验证非常严格,连接方必须同时满足(SearchLaunchPolicy):

  • 同一用户、进程签名校验通过;
  • 扩展标识符精确等于 com.xykong.Markdown.QuickLook;
  • 可执行文件路径精确匹配预览扩展本身。

请求本身也受限:只接受 markdownpreview://open?path=…&find=1 形式的本地文件搜索请求,仅限 Markdown 类扩展名,总长不超过 8KB。客户端(SearchLaunchClient)还设置了 8 秒超时,失败就立即放弃并走兜底。

窗口定位:让搜索窗口"出现在你眼前"

多显示器用户最怕主应用窗口跑到别的屏幕。SearchWindowPlacement 会把预览窗口的位置和所在屏幕 ID 一起编码进 URL,主应用打开文档后在同一屏幕的同一位置落窗,搜索框自动聚焦——你甚至感觉不到中间发生过"跳转"。

兜底提示:失败时绝不装死

如果系统拒绝打开主应用,预览只会弹出一条 8 秒的本地化提示(showSearchLaunchFailure()):

双击打开文件后,按 ⌘F 搜索。

不展示任何无法输入的 HTML 输入框,不谎报成功——这也是该方案在 openspec 规格 里被反复强调的验收标准。

一次 ⌘F 到底发生了什么?

把整条链路串起来看:

  1. 触发:在 QuickLook 预览中按 ⌘F,或点击"在 FluxMarkdown 中搜索"按钮;
  2. 校验:请求编码为带 find=1 与窗口位置信息的 URL,经签名验证交给 XPC 启动服务;
  3. 启动:SearchLauncher 通过 NSWorkspace 用主应用打开当前文件(冷启动、热启动均可);
  4. 定位:主应用在相同屏幕位置打开文档,自动聚焦搜索框;
  5. 就绪:直接开始输入关键词,重复点击会保留已有查询词;
  6. 兜底:若系统拒绝打开,显示 8 秒操作指引,搜索链路随时可用。

全程零额外权限:没有 Accessibility 授权、没有全局键盘监听、没有登录项、没有削弱任何沙盒规则。早期考虑过的"全局快捷键拦截助手"方案因需要辅助功能权限且不可靠,已在设计文档中明确放弃(design.md)。

总结

QuickLook 的键盘限制是系统级的,谁也绕不过去;FluxMarkdown 的思路很务实——

  • 接受限制:不在预览里硬造输入框;
  • 设计一条安全、可验证、有兜底的搜索启动链路,让 ⌘F 的心智模型依然成立:按键 → 搜索;
  • 用最小权限(标准沙盒 XPC 服务 + 签名校验)换取最大的体验完整性。

这也是该方案在 Release 版本中通过 entitlements 白名单校验的原因:启动服务只有沙盒与只读访问两项权限,绝不越界。下次在 QuickLook 里按下 ⌘F,你知道背后发生了什么。

更多细节可查阅:SearchLaunchClient.swift、SearchWindowPlacement.swift、SearchLauncher/main.swift 与 SEARCH_LAUNCH_POLICY 测试。

登录后查看全文
flux-markdown