为什么 QuickLook 里按不了 Cmd+F?揭秘 FluxMarkdown 搜索启动方案的设计思路
为什么 QuickLook 里按不了 Cmd+F?揭秘 FluxMarkdown 搜索启动方案的设计思路
FluxMarkdown 是一款 macOS Markdown 预览工具:在 Finder 里选中文件按空格,QuickLook 面板立刻渲染出带 Mermaid 图表、KaTeX 公式和目录的精美预览。可当你在预览里习惯性按下 ⌘F 时,搜索框纹丝不动。这篇文章带你弄清楚 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 到底发生了什么?
把整条链路串起来看:
- 触发:在 QuickLook 预览中按 ⌘F,或点击"在 FluxMarkdown 中搜索"按钮;
- 校验:请求编码为带
find=1与窗口位置信息的 URL,经签名验证交给 XPC 启动服务; - 启动:SearchLauncher 通过 NSWorkspace 用主应用打开当前文件(冷启动、热启动均可);
- 定位:主应用在相同屏幕位置打开文档,自动聚焦搜索框;
- 就绪:直接开始输入关键词,重复点击会保留已有查询词;
- 兜底:若系统拒绝打开,显示 8 秒操作指引,搜索链路随时可用。
全程零额外权限:没有 Accessibility 授权、没有全局键盘监听、没有登录项、没有削弱任何沙盒规则。早期考虑过的"全局快捷键拦截助手"方案因需要辅助功能权限且不可靠,已在设计文档中明确放弃(design.md)。
总结
QuickLook 的键盘限制是系统级的,谁也绕不过去;FluxMarkdown 的思路很务实——
- 接受限制:不在预览里硬造输入框;
- 设计一条安全、可验证、有兜底的搜索启动链路,让 ⌘F 的心智模型依然成立:按键 → 搜索;
- 用最小权限(标准沙盒 XPC 服务 + 签名校验)换取最大的体验完整性。
这也是该方案在 Release 版本中通过 entitlements 白名单校验的原因:启动服务只有沙盒与只读访问两项权限,绝不越界。下次在 QuickLook 里按下 ⌘F,你知道背后发生了什么。
更多细节可查阅:SearchLaunchClient.swift、SearchWindowPlacement.swift、SearchLauncher/main.swift 与 SEARCH_LAUNCH_POLICY 测试。
