企业官网建设流程全解析

• 桌面应用
• AI 应用
• 插件系统

Wox 的 Selection（选中内容）系统插件提供了一项类似 macOS Quick Look 的「空格快速预览」（Space Quick Look）能力：在 Windows 文件资源管理器或打开/保存对话框中选中单个文件后，按下空格键即可让 Wox 打开一个专注的预览面板，无需启动完整的关联应用程序。本文以官方博客 did-you-know-selection-space-quick-look.md 为主线，结合 selection.go 等源码，完整讲解该功能的开启方式、使用步骤、按键防误触机制、底层触发链路与平台限制，让你既能上手使用，也能理解其实现原理。

功能定位：为什么需要「空格快速预览」

在日常工作中，我们经常需要在打开文档、图片、压缩包或配置文件之前先「瞄一眼」内容。传统做法是双击文件启动关联应用，看完再关闭，既打断工作流，也白白消耗系统资源。Wox 的空格快速预览正是为了解决这个痛点：

• 不切换应用：预览面板由 Wox 渲染，文件仍停留在原位置，不启动完整关联程序；
• 不干扰结果列表：预览命令会把 Wox 的结果列表收起来，让预览内容独占可用空间，看得更清楚；
• 入口最快：文件已经处于选中状态时，按一个空格键即可预览，比打开 Wox 再输入查询更快。

官方博客用一句话概括了这个流程：Windows 用户可以通过 Selection 插件获得 Quick Look 风格的体验——选中一个文件，按下空格，Wox 打开聚焦的文件预览。

开启方法：两步开启，Windows 专属

1. 打开 Selection 插件设置

进入 Wox 的设置 -> 插件 -> Selection，找到如下设置项并启用：

在中文语言包中，该项的文案为「启用空格快速预览」，提示文案为「启用后，在 Windows 文件资源管理器或打开/保存对话框中按空格键，用 Wox 预览选中的文件」（见 zh_CN.json）。

2. 从受支持的 Windows 文件选择界面使用

开启后，即可在 Windows 的两类文件选择场景中使用：

1. 在Windows 文件资源管理器（File Explorer）中选中一个文件；
2. 或在任何应用弹出的打开/保存对话框（open/save dialog）中选中一个文件；
3. 按下空格键（Space）；
4. Wox 随即为该文件打开一个仅含预览的面板。

该功能非常适合快速查看文档、图片、压缩包或配置文件，确认内容后按任意键/关闭面板即可回到原上下文，无需进入完整关联应用。

与常规 Selection 动作的关系

开启空格快速预览并不会破坏 Selection 插件原有的能力。在选中文件后通过选择热键触发 Wox，你依然可以使用常规动作：

• 复制路径（复制选中文件的完整路径）；
• 打开所在文件夹；
• 常规预览结果（带创建时间、修改时间、大小等元数据标签的预览）；
• 保存到 Notes、在该目录执行 Shell 命令等。

空格快速预览只是「文件已经选中」这一场景下最快的入口；selection preview查询命令同样只返回文件预览结果。换句话说，快速预览与完整动作集是互补关系而非替代关系，官方文档也明确说明：空格快速预览是文件已被选中时最快的入口，常规动作依然可用。

源码级原理：从设置开关到预览面板

下面结合源码拆解该功能的完整实现链路，文件均位于 wox.core/plugin/system/selection.go。

1. 设置项定义：复选框 + 平台禁用

设置项在插件元数据中声明，类型为复选框（CheckBox）：

SettingDefinitions: definition.PluginSettingDefinitions{ { Type: definition.PluginSettingDefinitionTypeCheckBox, Value: &definition.PluginSettingValueCheckBox{ Key: enableSpaceQuickLookSettingKey, // "enableSpaceQuickLook" Label: "i18n:plugin_selection_setting_enable_space_quick_look", Tooltip: "i18n:plugin_selection_setting_enable_space_quick_look_tips", DefaultValue: "false", }, DisabledInPlatforms: []util.Platform{util.PlatformMacOS, util.PlatformLinux}, IsPlatformSpecific: true, }, },

关键点：

• 默认值为false，即默认不启用，需要用户手动打开；
• DisabledInPlatforms明确在macOS 和 Linux 上禁用该设置项，这也是为什么它只在 Windows 出现；
• IsPlatformSpecific: true表示这是一个平台相关的设置，会按平台分别存储。

插件初始化时（Init方法）会读取该设置并动态挂载/卸载按键监听，同时通过OnSettingChanged监听设置变更，做到无需重启即可热启停：

i.updateSpaceQuickLookListener(ctx, i.api.GetSetting(ctx, enableSpaceQuickLookSettingKey) == "true") i.api.OnSettingChanged(ctx, func(callbackCtx context.Context, key string, value string) { if key == enableSpaceQuickLookSettingKey { i.updateSpaceQuickLookListener(callbackCtx, value == "true") } })

2. 按键监控：双通道原始按键订阅

启用后，插件通过 quickjump 包注册两类原始按键（RawKey）监听，分别覆盖两类界面：

explorerSub, explorerErr := quickjump.AddExplorerRawKeyListener(state.handleRawKey) // 文件资源管理器 dialogSub, dialogErr := quickjump.AddExplorerOpenSaveRawKeyListener(state.handleRawKey) // 打开/保存对话框

在 Windows 实现 monitor_windows.go 中，这两类监听被分别存入explorerRawKeyListeners与dialogRawKeyListeners两个 map，由统一的handleExplorerRawKeyEvent在每次按键时：

1. 刷新原生 Explorer/对话框前台状态（空格键事件会传入allowDesktop=1）；
2. 检查前台是否为 Explorer 文件列表或对话框；
3. 将事件分发给所有已注册的 raw-key 监听器，任一监听器返回true即视为消费该按键。

监听器的关闭通过返回的ExplorerRawKeySubscription完成，插件卸载时（OnUnload）会关闭全部订阅，避免残留监听。

3. 空格键状态机：防误触的核心设计

直接监听空格键会带来误触风险——用户在 Explorer 中打字、按修饰键组合、或上下移动光标时都可能碰到空格。为此，插件实现了一个小型的按键状态机（selectionSpaceQuickLookState），包含spaceDown、spaceConsumed、invalidUntil三个关键状态，规则如下：

• 仅处理纯空格键按下：若按下空格时带有任意修饰键（Ctrl/Shift/Alt/Win），直接放行不消费，避免干扰系统快捷键；
• 打字后 1 秒抑制：recordInvalidKeyIfNeeded会在用户按下非导航类普通按键后，将invalidUntil设为当前时间加 1 秒；在此窗口内按下空格不会触发预览，防止 Explorer 中打字后误触发；
• 导航/功能键豁免：方向键、回车、Esc、F5、F11 等导航类按键，以及修饰键本身，不会重置抑制窗口，保证正常的文件浏览不受影响；
• 防止按键重复：spaceConsumed标记保证一次按下只触发一次预览，按住空格不会重复弹出；
• 按键抬起复位：空格键抬起时清空状态，为下一次按下做准备。

4. 触发预览：独立次要实例

空格事件通过校验后，triggerSpaceQuickLook会先读取当前系统选中内容，并做严格的前置检查：

selected, err := selection.GetSelected(ctx) if selected.Type != selection.SelectionTypeFile || len(selected.FilePaths) != 1 { return } if !util.IsFileExists(selected.FilePaths[0]) { return }

即必须是恰好一个文件（文本选中、多个文件、或文件已不存在都不会触发），随后通过OpenWoxInstance打开一个命名次要实例（Secondary Role）：

OpenWoxInstance(ctx, common.OpenWoxInstanceRequest{ Role: common.WoxInstanceRoleSecondary, InstanceName: quickLookInstanceName, // "selection-quicklook" Query: common.PlainQuery{ QueryType: plugin.QueryTypeSelection, QuerySelection: selected, QueryScope: ... // 限定为 Selection 插件 + preview 命令 }, ShowApp: common.ShowContext{ HideQueryBox: true, HideToolbar: true, ShowPreviewTitleBar: true, WindowWidth: 1000, MaxResultCount: 12, }, })

这段代码解释了几个可观察到的行为：

• 查询框和工具栏被隐藏（HideQueryBox/HideToolbar），面板几乎就是纯粹的预览内容；
• 预览窗口宽度固定为 1000，显示标题栏以便关闭；
• 使用独立的命名实例selection-quicklook，与选择热键会话相互隔离，预览窗口永远不会覆盖主启动器的查询状态；关闭该窗口即销毁次要实例，下次预览会为新选中文件打开全新窗口。

5. 只返回预览结果：preview 命令 + 宽度比

预览面板为什么没有动作列表？原因有两层：

1. 查询限定命令：触发时查询作用域被限定为 Selection 插件 +preview命令（selectionCommandPreview）。在queryForSelectionFile中，当query.Command == selectionCommandPreview时，直接走queryForFilePreviewOnly，只返回一个文件预览结果，跳过复制路径、打开文件夹等动作；
2. 命令级宽度比：插件声明了MetadataFeatureResultPreviewWidthRatio特性，WidthRatio: 0.0且限定在preview命令作用域内——把结果列表宽度压为 0，让预览独占面板。注释特别说明这是刻意为之：如果把WidthRatio设为插件全局 0，会连普通选择查询的结果列表一起隐藏，因此采用命令级作用域。

预览结果本身基于WoxPreviewTypeFile渲染，走 Wox 统一的文件预览管线，主题感知地支持文本、图片、PDF 与 Office 等文件类型（详见 预览指南）。

6. 平台差异：为什么只有 Windows

官方博客与代码均明确：空格快速预览目前仅支持 Windows。原因如下：

• macOS：Finder 自带原生 Quick Look，且 monitor_darwin.go 中AddExplorerRawKeyListener与AddExplorerOpenSaveRawKeyListener被刻意实现为「不支持」，直接返回空订阅，Wox 不会为 Selection 预览安装 macOS 空格键监听器；
• Linux：同样在设置层面被禁用（DisabledInPlatforms包含 Linux），文件管理器生态与快捷键约定差异较大，暂未提供该能力；
• Windows：通过快速跳转（QuickJump）模块的原生监控能力，实现对资源管理器与系统文件对话框的可靠监听。

因此该设置在 macOS 上始终保持禁用状态，避免与 Finder 原生 Quick Look 重复。

使用建议与注意事项

• 一次性选中单个文件：空格快速预览只响应「恰好选中一个文件」的场景；选中多个文件或文件夹时不触发，请改用常规 Selection 动作；
• 避免打字后立刻按空格：状态机会在普通输入后抑制约 1 秒，这是防止误触的有意设计，稍作停顿即可；
• 修饰键组合不受影响：带 Ctrl/Shift/Alt/Win 的空格组合会被放行给系统，不会弹出预览；
• 预览窗口独立：预览打开在独立次要实例中，不会打断主启动器的当前查询，关闭后下一次按键会为新文件重新打开窗口；
• 与其他预览入口互补：在 Wox 结果列表中高亮结果后按空格同样可以预览（支持预览的结果类型见 预览指南）；若经常预览固定内容，还可结合「预览查询」热键预设隐藏查询框与工具栏，让面板主要呈现预览内容。

参考资源

• 官方博客：www/docs/blog/did-you-know-selection-space-quick-look.md
• Selection 插件文档：www/docs/guide/plugins/system/selection.md
• 预览功能指南：www/docs/guide/usage/preview.md
• 功能演示视频：screenshots/selection_quick_look.mp4
• 核心实现：wox.core/plugin/system/selection.go
• Windows 按键监控：wox.core/plugin/system/quickjump/monitor_windows.go
• macOS 按键监控（刻意不支持）：wox.core/plugin/system/quickjump/monitor_darwin.go
• 设置项文案：wox.core/resource/lang/zh_CN.json

• 桌面应用
• AI 应用
• 插件系统