macOS QuickLook插件无法通过preparePreviewOfFile设置预览窗口尺寸
自定义QuickLook插件无法自适应预览尺寸的核心遗漏环节
首先要厘清的认知误区
QuickLook Preview Extension运行在独立沙箱进程中,并不持有实际的预览窗口实例——你在XIB中配置的窗口、代码中查找NSWindow对象的操作,全部作用在沙箱内的虚拟占位容器上,和真正由QuickLook宿主进程(QuickLookUIService)管理的预览窗口完全没有映射关系,这也是你无论在completionHandler前后调整布局,窗口尺寸始终不变的根本原因。系统内置插件的自适应尺寸,全部是通过QuickLook开放的官方接口上报的,不存在跨进程修改窗口的操作。
关键遗漏的实现逻辑
- 没有通过官方接口上报期望的内容尺寸
从macOS 10.15开始,QuickLook专门为Preview Extension提供了尺寸上报通道:在重写preparePreviewOfFile(at:completionHandler:)方法时,需要在文件内容加载完成后,构造带尺寸约束的QLPreviewContent对象作为completionHandler的返回值,而非仅返回错误信息。
构造对象时需要明确两个核心属性:preferredContentSize:基于文件内容计算的最优显示尺寸,单位为屏幕点(而非像素),需要匹配当前屏幕的缩放系数- 对于固定比例的内容(图片、PDF、矢量文件),必须额外设置
aspectRatio属性指定宽高比,避免系统仅按照默认800x600的窗口比例渲染内容
只有将带尺寸参数的QLPreviewContent返回给系统,宿主进程才会根据你的期望调整初始窗口尺寸,任何在视图生命周期(viewDidAppear等)里的尺寸调整操作,都无法触达真实窗口。
- 错误的尺寸上报时机触发了用户记忆覆盖
系统会自动将用户手动调整的QuickLook窗口尺寸,按插件的Bundle ID做持久化存储,正常逻辑下:- 首次打开某类文件时,插件上报内容自适应尺寸作为初始值
- 后续打开时,自动读取已存储的用户自定义尺寸作为初始值
如果你在每次加载预览时,都不管已有存储记录、强制上报固定的内容尺寸,就会直接覆盖系统存储的用户调整记录,这也是你关闭窗口重开后尺寸回落到800x600的原因之一。
- 扩展配置缺失导致尺寸记忆关联失效
检查扩展的Info.plist配置项:- 确保
NSExtensionPrincipalClass正确指向你自定义的QLPreviewController子类,而非模板默认的占位空类 - 确保
NSExtension节点下声明的支持文件UTI准确匹配你要处理的文件类型,否则系统无法将已存储的尺寸记录和你的插件关联,始终调用默认的800x600兜底尺寸。
- 确保
常见实现坑点
- 不要尝试在代码中获取、修改QuickLook宿主的
NSWindow实例,跨进程的窗口操作在沙箱环境下完全无效 - 不要混用旧版QuickLook Generator(基于
QLPreviewGenerator协议)和新版Preview Extension的API,旧版协议本身不支持尺寸上报能力,只能使用新版QLPreviewContent的上报通道 - 计算内容尺寸时不要直接使用像素值,必须转换为当前屏幕的点坐标,否则在Retina屏幕上会出现尺寸比例错位的问题
内容的提问来源于stack exchange,提问作者mbt
相关产品推荐
相关产品推荐

