Question

在脚本运行时创建、修改、启用或禁用热键。

Hotkey, KeyName [, Label, Options]
Hotkey, IfWinActive/Exist [, WinTitle, WinText]
Hotkey, If [, Expression]

参数

KeyName

热键触发键的名称, 包括所有 修饰符. 例如，指定 #c 来触发 Win+C 热键。

如果 KeyName 是现有的热键, 那么将使用此命令的其他参数值更新原来的热键.

KeyName 也可以是现有的热键标签的名称 (即双冒号标签), 这样会使用此命令的其他参数值更新原来的热键.

指定 现有的 热键时, KeyName 是不区分大小写的. 但是, 按键名称必须和现有的热键拼写相同 (例如在这种情况下 Esc 与 Escape 是不同的). 此外, 修饰符 (例如 ^!+#) 是无关紧要的.

首次创建一个热键时 (通过 Hotkey 命令或脚本中的 双冒号标签), 其键名以及修饰符的顺序成为此热键的固定名称, 像 A_ThisHotkey 包含的那样. 即使之后 Hotkey 命令使用不同的修饰符顺序操作此热键, 此名称也不会改变.

[v1.1.15+]：如果已存在该热键变体，则根据 KeyName 是否包含颚化符（~）前缀更新它的行为。

标签

按下热键时会执行 (作为新 线程) 的 标签 的名称. 可以使用普通标签或 热键/热字串 标签. 不要包含尾随的冒号. 如果使用动态的 Label (例如 %VarContainingLabelName%), 请首先调用 IsLabel(VarContainingLabelName) 来检查此标签是否存在.

如果 KeyName 为现有的热键, 则此参数可以留空, 此时其标签不会发生变化. 这可用于仅需要修改热键的 Options 时.

如果指定了标签但热键之前已经使用此命令禁用了, 那么热键会保持禁用状态. 要启用它, 请在 Options 中包含单词 ON.

此参数还可以是下列特定值的其中一个:

On: 启用热键. 如果热键已经处于启用状态, 则不进行操作.

Off: 禁用热键. 如果热键已经处于禁用状态, 则不进行操作.

Toggle: 设置热键到相反的状态 (启用或禁用).

AltTab (及其他): 这些是 这里 描述的特殊的 Alt-Tab 热键动作.

注: 仅当不存在相应的标签时 这些值才有特殊含义. 例如, 如果标签 On: 存在并且此参数为单词 ON, 则它被当成标签的名称. 要启用或禁用这样的热键, 请使用 Options 参数. 可以省略 Label; 例如, Hotkey Esc,, Off.

选项

由零个或多个下列字母组成的字符串, 字母间可以用空格分隔. 例如：UseErrorLevel B0。

UseErrorLevel: 如果命令遇到问题, 使用此选项会跳过警告对话框, 设置 ErrorLevel 为 下表 中的一个代码, 然后让 当前线程 继续执行.

On: 如果热键当前是禁用的则启用它.

Off: 如果热键当前是启用的则禁用它. 此选项常用来创建初始状态为禁用的热键.

B 或 B0: 指定字母 B 将按照 #MaxThreadsBuffer 描述的方法缓冲热键. 指定 B0 (B 后跟着数字 0) 来禁用这种类型的缓冲.

Pn: 指定字母 P 后面跟着热键的 线程优先级. 如果创建热键时省略 P 选项, 则设置优先级为 0.

Tn: 指定字母 T 后面跟着一个表示此热键允许的线程数, 如同 #MaxThreadsPerHotkey 中描述的那样. 例如：T5。

如果 B 和 T 选项同时省略或省略了其中一个且热键已经存在, 则这些设置不会改变. 但如果热键还不存在 (即使用当前命令创建时), 它们将使用最近使用的值. 例如, 会使用最靠近脚本末尾的 "https://www.wenjiangs.com/doc/AutoHotkey-_MaxThreadsBuffer">"https://www.wenjiangs.com/doc/AutoHotkey-_IfWinActive">"Hotkey IfWin", 否则将对新创建的热键应用最近的实例.

IfWinActive
IfWinExist

(也支持 IfWinNotActive 和 IfWinNotExist). 这些子命令让此后创建的所有热键都是上下文相关的. 请参阅 后面 了解详情.

WinTitle
WinText

在这两个参数中, 任何变量引用 (例如 %var%) 会在命令执行结束时被固定下来. 换句话说, 此后对这些变量内容的改变不会影响现有的 IfWin 热键.

与 "SetTitleMatchMode.htm">SetTitleMatchMode 和 DetectHiddenWindows 使用在自动执行段中的默认设置。请参阅 #IfWinActive/Exist 了解详情.

If, Expression

[AHK_L]: "" 或 "". 当用于 Hotkey 命令时, "If" 后面的逗号是必须的. 尽管此命令不能创建新的表达式, 但它可以使用现有的表达式创建新的热键. 请参阅 #If 示例 4.

已知限制：如果 Expression 包含 and/or 运算符，则它不会被识别为表达式。为了避免此问题，请在原来的 #If 表达式和传递给 Hotkey 命令的表达式中使用等价的 &&/|| 运算符。

ErrorLevel

[v1.1.04+] 此命令失败时会抛出异常. 想了解更多信息, 请参阅 运行时错误.

只有在出现下列情况时 ErrorLevel 才会被改变: 1) 首个参数为 IfWin[Not]Active/Exist, 此时如果遇到问题它会被设置为 1 否则为 0; 或 2) 在 Options 参数中使用了单词 UseErrorLevel.

错误	说明
1	Label 参数指定了不存在的标签名.
2	KeyName 参数指定了一个或多个当前键盘布局/语言无法识别或不支持的键.
3	不支持的前缀键. 例如，不支持使用鼠标滚轮作为热键（如 WheelDown & Enter）的前缀。
4	KeyName 参数不适合用于 AltTab 或 ShiftAltTab功能。这种情况下要求热键为两个键的组合. 例如：RControl & RShift::AltTab。
5	命令试图修改不存在的热键.
6	命令试图修改现有热键的不存在的 变体. 要解决此问题，请使用 Hotkey IfWin 来设置匹配那些需修改的热键变体的标准。
98	创建此热键后将超过每脚本 1000 个热键的限制 (不过, 每个热键的 变体 数目不受限制, 并且对于 热字串 的数目也没有限制).
99	内存不足. 这种情况极少, 通常仅在操作系统变得不稳定时才会发生.

提示: 使用 UseErrorLevel 选项可以检查一个热键的变体是否存在. 例如：

Hotkey, ^!p,, UseErrorLevel
if ErrorLevel in 5,6
    MsgBox The hotkey does not exist or it has no variant for the current IfWin criteria.

备注

当前的 IfWin 设置 决定了 Hotkey 命令将操作热键的哪个 变体.

如果需要根据活动窗口的类型自动禁用选择的热键或热字串，使用 Hotkey, ^!c, Off 通常不如 "">下面的动态副本“Hotkey IfWinActive/Exist”）来的方便。

通过 双冒号 创建热键比使用 Hotkey 命令执行地更好, 因为在脚本启动时会批量启用它们 (而非一个一个地启用). 因此, 最好使用此命令创建那些在脚本开始运行后才知道键名的热键. 一种这样的情况是通过 INI 文件 为热键配置了多个不同的动作.

给定的标签可以是多个热键的目标. 如果某个热键调用了标签, 您可以通过检查内置变量 A_ThisHotkey 来确定是哪个热键.

如果脚本是 挂起的, 那么新增加/启用的热键也将是挂起的, 直到挂起状态被关闭 (除非它们像 Suspend 命令中描述的那样被免除了).

由此命令做出的改变使得 键盘 和/或 鼠标 钩子被安装或移除是正常的.

尽管 Hotkey 命令不能直接启用或禁用脚本中不是它创建的热键, 但在大多数情况下它可以通过创建或启用相同的热键来 覆盖 它们. 这样是否有效取决于下列因素：1) 在其他脚本中需要被覆盖的热键是否为钩子热键（非钩子热键总是可以成功覆盖）；2) 最近启动的热键通常优先于其他脚本中的相同热键（因此，如果要覆盖其他脚本中的脚本是最近启动的，覆盖总是会成功）；3) 此热键的启用或创建是否会重新激活键盘或鼠标钩子（如果是，那么覆盖总是会成功）。

每当脚本含有至少一个热键时, 它会变成持续运行的, 这意味着应该使用 ExitApp 而不是 Exit 来终止它. 同时热键脚本自动为 #SingleInstance 的单实例属性，不过可以指定 #SingleInstance Off 来关闭。

关于 Hotkey, IfWinXX [, WinTitle, WinText] 的备注

"Hotkey IfWin" 命令允许在脚本运行时创建或修改上下文相关的 热键 (与之相比, #IfWinActive/Exist 指令是由位置决定的并且在脚本启动时生效). 例如：

Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!e, MyLabel  ; 创建仅在记事本中有效的热键.

使用 "Hotkey IfWin" 会把后续创建或修改的所有 热键 都变成上下文相关的. 此外, 每个 IfWin 子命令是互斥的; 即只有最近的那个会起作用.

要关闭上下文相关性 (即让后续创建的热键对所有窗口有效), 请指定任一省略了 WinTitle/Text 参数的 IfWin 子命令. 例如：Hotkey, IfWinActive。

如果脚本中没有使用过“Hotkey IfWin”，则最近使用的#IfWin指令（如果有）将作用于Hotkey命令。

通过 IfWin 禁用鼠标或键盘热键后, 则热键会执行它原来的功能; 即如同这样的热键不存在那样被直接传递到活动窗口. 有一种情况例外：对于操纵杆热键，尽管 #IfWin 有效，但它不能阻止其他程序探测到按钮的按下动作。

变体 (副本) 热键

只要每次定义时含有不同的 IfWin 条件, 一个特定的热键可以被创建多次. 这被称为 热键变体. 例如：

Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!c, MyLabelForNotepad
Hotkey, IfWinActive, ahk_class WordPadClass
Hotkey, ^!c, MyLabelForWordPad
Hotkey, IfWinActive
Hotkey, ^!c, MyLabelForAllOtherWindows

如果有多个变体符合触发条件, 那么仅触发最早创建的那个. 这种情况的例外是全局变体 (不带有 IfWin 条件的那个): 它的优先级总是最低, 仅当其他变体都不触发时它才会被触发.

创建重复热键时, 修饰符 的顺序例如 ^!+"https://www.wenjiangs.com/doc/AutoHotkey-Hotkeys">通配符前缀（*）的热键和不带通配符的完全不同；例如, *F1 和 F1 将拥有各自的变体设置。

关于 IfWin 热键的更多信息, 请参阅 #IfWin 的一般说明.

相关

热键修饰符, "https://www.wenjiangs.com/doc/AutoHotkey-_MaxThreadsBuffer">"https://www.wenjiangs.com/doc/AutoHotkey-_MaxThreadsPerHotkey">"https://www.wenjiangs.com/doc/AutoHotkey-Suspend">Suspend, IsLabel(), 线程, Thread, Critical, Gosub, Return, Menu, SetTimer

示例

Hotkey, ^!z, MyLabel
return

MyLabel:
MsgBox You pressed %A_ThisHotkey%.
return

; 其他的例子:
Hotkey, RCtrl & RShift, AltTab ; 让 RCtrl & RShift 执行 Alt-Tab 的功能.
Hotkey, #c, On  ; 重新启用 Win-C 热键.
Hotkey, $+#c, Off  ; 禁用 Shift-Win-C 热键.
Hotkey, ^!a, , T5  ; 改变热键为允许 5 个线程.

Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!c, MyLabelForNotepad  ; 创建仅在记事本中有效的热键 Ctrl-Alt-C.