# Windows 指南

Windows 默认使用原生托盘宿主，提供托盘菜单、悬浮指示器、全局快捷键、开机启动和配置入口。也可以显式使用不带托盘界面的 [Headless 宿主](HEADLESS.md)。

## 安装与配置

发布包支持 Windows x64 和 ARM64：

- Setup 安装版将程序安装到当前用户目录，并创建开始菜单和卸载入口；
- Portable 压缩包解压后即可使用，配置保存在同目录的 `data/config.json`；
- 安装版配置位于 `%APPDATA%\select-bridge\config.json`。

Portable 目录可以整体移动，但不要只移动其中的 EXE。移动后如需开机启动，请重新关闭并开启一次“开机自启”，以更新程序路径。

## 托盘菜单

左键或右键点击托盘图标都会打开同一个菜单，主要包括：

- 暂停或恢复转发；
- 选择查询目标；
- 选择触发方式；
- 调整指示器样式和触发动作；
- 设置开机启动、剪贴板回退和界面语言；
- 检查更新、打开或重新加载配置。

“暂停转发”会停止全局选区钩子，不再监听鼠标选区和键盘事件；“恢复转发”会重新启动钩子。恢复失败时保持暂停并显示错误。

## 触发方式

| 方式 | 行为 |
| --- | --- |
| 立即转发 | 选区稳定后自动转发 |
| 显示图标 / 圆点 | 在选区附近显示指示器，通过点击或悬浮确认 |
| 单按 Ctrl / Alt / Shift | 选中后单独按下并释放对应修饰键 |
| 自定义快捷键 | 使用已注册的全局组合键确认 |

单按修饰键模式不会响应组合键：按住修饰键期间只要出现其他按键，本次触发就会取消，因此 `Ctrl+C`、`Alt+Tab`、`Shift+字母` 等正常组合不会转发选区。

自定义快捷键至少包含一个修饰键和一个普通键。Windows 会检查组合是否已被其他程序占用；冲突或无效的候选不会替换当前快捷键。移除正在使用的自定义快捷键后，触发方式切换为立即转发。

## 剪贴板回退

“设置 → 剪贴板回退”默认开启，对应配置项 `enableClipboardFallback: true`。SelectBridge 会优先通过 Windows 无障碍接口读取选中文字；只有这些方式没有返回文字时，才允许 `selection-hook` 发送模拟 `Ctrl+C` 并尝试读取剪贴板。

剪贴板回退能提高部分应用的兼容性，但可能影响前台程序或改变剪贴板内容。终端出现 `^C`、命令被中断或应用发生意外复制时，可以关闭该选项。设置会立即应用并持久保存；详细原因和影响见[常见问题](#常见问题)。

## 查询目标与配置

“查询目标”可以选择 GoldenDict-ng Popup 或已保存的自定义 URL。自定义模板必须：

- 使用合法 URI scheme；
- 恰好包含一个 `{text}`；
- 不包含空白或控制字符；
- 不超过 2048 个字符。

选中文字会经过 `encodeURIComponent` 编码后替换 `{text}`。存在命令行或环境变量 URL 覆盖时，托盘中的目标选择和编辑入口会显示为受运行参数控制。

配置可以从托盘直接打开、打开所在目录或重新加载。无效配置不会替换当前运行状态。

## 开机启动与单实例

Setup 和 Portable 共用当前用户的开机启动入口，最后开启该选项的版本会接管启动路径。关闭时只移除指向自身的启动项。

同一用户同时只运行一个 SelectBridge 实例。后启动的 Setup、Portable 或开发实例会直接退出，避免安装多套全局选区钩子；不同分发方式仍各自使用自己的配置文件。

## 更新

“设置 → 检查更新…”会将当前版本与 GitHub 最新稳定版比较。SelectBridge 不会自动下载或安装更新。

## FAQ

### 为什么在终端选词时会出现 `^C`，甚至中断当前命令？

剪贴板回退默认开启。检测到文本选区后，`selection-hook` 会先尝试通过 UI Automation、IAccessible 等 Windows 无障碍接口读取文字；如果这些接口不受当前应用支持、读取失败或没有返回文字，剪贴板回退会作为最后一种取词方式向前台程序发送模拟 `Ctrl+C`，再尝试读取剪贴板。

在编辑器和浏览器中，`Ctrl+C` 通常只表示复制；在终端、Shell 和部分交互式程序中，它表示中断当前操作。因此可能出现：

- 命令行末尾出现 `^C`，例如 `clear^C`；
- 当前命令或前台进程被中断；
- 应用执行一次意外复制；
- 系统剪贴板内容发生变化。

模拟 `Ctrl+C` 发生在“读取选区”阶段，而不是“确认转发”阶段。因此即使使用修饰键、自定义快捷键、图标或圆点触发，只要在终端中产生选区，回退仍可能先执行。退出 SelectBridge 或暂停转发会停止选区钩子，所以相同操作随后恢复正常。

遇到这种情况时，取消勾选“设置 → 剪贴板回退”即可。也可以将 `enableClipboardFallback` 改为 `false`，再从托盘重新加载配置。该选择会持久保存。

关闭后，UI Automation 和 IAccessible 等原生取词方式仍会工作；只有依赖模拟复制才能取词的应用可能无法再产生选区。如果要停止全部全局监听，请使用“暂停转发”。

### 关闭剪贴板回退后，为什么某些应用无法取词？

这通常表示该应用没有通过受支持的无障碍接口公开选中文字，之前的结果来自剪贴板回退。可以重新开启回退以恢复兼容性，但在终端中选词时需留意模拟 `Ctrl+C` 的副作用。当前版本不支持按应用分别设置回退。

### 为什么自定义快捷键提示冲突？

Windows 全局快捷键不能与其他程序已经注册的组合重复。请换用其他组合；冲突的候选不会替换当前已生效的快捷键。