# Input

等待用户输入字符串.

    Input , OutputVar, Options, EndKeys, MatchList

## 参数

OutputVar

  用来保存用户输入文本的变量名(默认情况下, 模拟输入也被保存下来).

  如果省略此参数和其他参数, 那么会终止在其他线程中正在执行的任何 Input 并且将那个 Input 的 ErrorLevel 设置为单词 NewInput. 与之相比, 如果终止了之前的 Input 则把当前线程的 ErrorLevel 设置为 0, 如果没有需要终止的 Input 则为 1.

  OutputVar 本身并不记录键击. 而是记录通过键击根据活动窗口的键盘布局/语言产生的字符. 因此, 不产生字符的键击(例如 `PgUp` 和 `Home`) 不会被记录下来(尽管可以通过下面的 EndKeys 参数识别它们).

  注意: `Esc` 被转换为 ASCII ESC 字符, `Chr(27)`. 这可以通过在 EndKeys 中包含 `{Esc}` 来避免, 在这种情况下, 按下 `Esc` 将终止输入.

  会原义保存空白字符, 例如 `Tab`(`t). `Enter` 被保存为换行符(`n).

Options

  由零个或多个下列字母组成的字符串(可任意顺序, 字母间可以用空格分隔):

  B: 忽略 `Backspace`(退格) 键. 一般情况下, 按下 `Backspace` 会删除最后一个输入的字符. 注: 如果输入的文本是可见的(例如在编辑器中), 在其中使用方向键或其他方式移动了光标后, `Backspace` 仍然会删除最后一个字符而不是光标(插入点) 后面的字符.

  C: 区分大小写. 一般情况下, MatchList 是不区分大小写的(在 1.0.43.03 之前的版本中, 只有字母 A-Z 被认为具有大小写形式, 而像 ü/ü 这样的字母则没有).

  I: 忽略由 AutoHotkey 脚本产生的所有字符, 例如 SendEvent 命令. 然而, 不论此设置如何, SendInput 和 SendPlay 模式生成的输入总是被忽略. [v1.1.31+]: 选项字母后面可以跟着一个数字来设置最低发送级别. `I` 等同于 `I1`, 而 `I0` 等同于没有指定该选项.

  L: 长度限制(例如 `L5`). 允许输入文本的最大长度. 当文本到达这个长度, 则输入会被终止且 ErrorLevel 被设置为单词 Max, 不过如果此时文本匹配 MatchList 中的某个词组, 则把 ErrorLevel 设置为单词 Match. 如果未指定, 则长度限制为 16383, 这也是 [v1.1.31] 之前版本的绝对最大长度.

  M: 如果含修饰符的键击(例如 `Ctrl`+`A` 到 `Ctrl`+`Z`) 对应于真实的 ASCII 字符, 则会识别并对它们进行转译. 参考这个例子, 其中识别了 `Ctrl`+`C`:

      Transform, CtrlC, Chr, 3 ; 把 Ctrl-C 对应的字符保存到 CtrlC 变量.
      Input, OutputVar, L1 M
      if OutputVar = %CtrlC%
          MsgBox, You pressed Control-C.
      ExitApp

  注意: 从 `Ctrl`+`A` 到 `Ctrl`+`Z` 对应的字符为从 Chr(1) 到 Chr(26). 此外, M 选项可能会导致某些键盘快捷键(例如 `Ctrl`+`←`) 在 Input 执行时表现不正常.

  T: 超时(例如 `T3`). 在终止输入前等待的秒数, 超时后设置 ErrorLevel 为单词 Timeout.Input 超时后, OutputVar 会被设置为用户在超时前输入的文本. 这个值可以为浮点数, 例如 `2.5`.

  V: 可见. 一般情况下, 用户的输入是阻塞的(隐藏在操作系统后). 使用此选项来发送用户的键击到活动窗口.

  *: 通配符(查找所有地方). 一般情况下, 用户输入的文本必须准确匹配 MatchList 中的某个词组, 匹配才会成功. 使用此选项搜索输入文本的整个长度, 这样会更容易找到匹配.

  E [v1.1.20+]: 使结束键响应单个字符而替代使用 keycode(按键码). 这样使得当用户键盘布局和脚本的不同的时候得到一致的返回值. 同时它还能避免实际发生的组合键和定义的不同的歧义; 举个例子, 如果 `@` 作为 结束键, 在 US 键盘布局上 `Shift`+`2` 会触发它, 但是 `Ctrl`+`Shift`+`2` 不会(如果使用了 E 选项的话). 如果 C 选项也同时开启, 那么结束字符是大小写敏感的.

EndKeys

  零个或多个按键组成的列表, 按下其中的任何一个都可以终止输入(EndKey 自身不会被写入 OutputVar). 使用此方式终止输入后, ErrorLevel 被设置为单词 EndKey 后跟着冒号和 EndKey 的名称. 例如: `EndKey:.`, `EndKey:Escape`.

  EndKey 列表使用类似于 Send 命令的格式. 例如, 指定 `{Enter}.{Esc}` 会使得 `Enter`, `.` 或 `Esc` 其中任何一个都可以终止输入. 要使用大括号作为终止键, 请指定 `{{}` 和/或 `{}}`.

  要使用 `Ctrl`, `Alt` 或 `Shift` 作为终止键, 请指定它们的左和/或右的版本, 而不是中性版本. 例如, 指定 `{LControl}{RControl}` 而不是 `{Control}`.

  [v1.0.14+]: 尽管不支持诸如 `Alt`+`C`(!c) 这样的修饰键, 但支持某些需要按住 `shift` 来输入的字符, 标点符号, 例如 `?!:@&{}`. [v1.1.20+]: 其他字符推荐使用上述的 E 选项. 当同时使用 E 和 M 选项时, 通过在 EndKeys 中包括相应的 ASCII 控制字符来支持 `Ctrl`+`A` 到 `Ctrl`+`Z`.

  还可以指定明确的虚拟按键代码, 例如 `{vkFF}`. 只有在一个按键没有指定名称且按下时不产生可见的字符这样少见的情况下, 这种方法才有用. 它的虚拟按键代码可以通过按键列表页面底部的步骤来确定.

MatchList

  逗号分隔的关键词组列表, 其中的任何一个都可以终止输入(此时 ErrorLevel 被设置为单词 Match). 用户输入的全部文本必须准确匹配列表中的某个词组, 匹配才会成功(除非使用了 * 选项). 此外, 在分隔逗号周围的任何空格或 tab 都是有意义的, 这表示它们也是匹配字符串的一部分. 例如, 如果 MatchList 为 `ABC , XYZ`, 则用户必须输入在 ABC 后或 XYZ 前输入空格才形成匹配.

  在匹配列表中两个连续的逗号产生单个原义逗号. 例如, 后面的匹配列表会在 string1 的末尾产生单个原义逗号: `string1,,,string2` . 同样地, 后面的匹配列表仅包含其中含有一个原义逗号的单个项目: `single,,item`.

  因为 MatchList 中的每一项并不是作为独立的参数, 所以此列表可以完整的包含在一个变量中. 事实上, 如果此列表的长度超过 16383, 那么列表的全部或部分必须包含在变量中以变量表示, 因为这个长度是任何脚本行的最大长度. 例如, MatchList 可以由 `%List1%,%List2%,%List3%` 组成, 其中的每个变量包含了用来匹配词组的一个大的子列表.

## 错误处理

[v1.1.04+] 此命令在不带参数调用且没有 Input 正在执行时会抛出异常. 想了解更多信息, 请参阅运行时错误.

ErrorLevel 被设为下列值之一:

值 | 描述
--- | ---
1 或 0 | 不带参数使用此命令时, 如果成功终止了之前的 Input 则 ErrorLevel 被设置为 0, 或是如果没有需要终止的 Input 则为 1.
NewInput | 此 Input 被另一个使用 Input 的线程中断.
Max | 输入的文本达到了允许的最大长度且没有匹配 MatchList 中的任何一项.
Timeout | 输入超时时间.
Match | 输入的内容匹配 MatchList 中的某项.
EndKey:Name | EndKeys 的某个终止键被按下用于终止输入. 此时, ErrorLevel 包含单词 EndKey 后跟着冒号和不带大括号的终止键的名称, 例如 `EndKey:Enter`, `EndKey:Escape` 等等. 注意 Name 是按键的 "标准" 名称而不管写到 EndKeys 中的方式. 举个例子, `{Esc}` 和 `{vk1B}` 都返回 `EndKey:Escape`. GetKeyName() 可用于获取标准名称. 如果使用了 E 参数, Name 则为实际输入的字符(如果适用的话). 其他情况下, 按键名取决于当前实际使用的键盘布局. 在 [v1.1.20] 之前, 如果 EndKey 的 VK 码在 0x41(A) 到 0x5A(Z) 的范围内时, ErrorLevel 通常包含类似 ASCII 的字符, 甚至不符合当前键盘布局. 而从 [v1.1.20] 开始, 则一定是符合当前键盘布局的. 如果使用从 A 到 Z 的字符, 那么当它是大写字母时可保持向后兼容; 否则可以是小写字母.

## 备注

如果在使用此命令时另一个线程中的 Input 正在执行, 则那个 Input 会被终止且其 ErrorLevel 会被设置为单词 NewInput. 之后(如果给出了参数), 新的 Input 开始执行.

在执行 Input 时, 仍然可以启动新的线程(例如, 自定义菜单项和计时子程序).

在 Input 正在进行时, 键盘热键仍然有效, 但如果任何必需的修饰键被抑制, 或者如果热键使用了 reg 方法且其后缀键被抑制, 则无法触发热键. 例如, 热键 `^+a::` 可能 会被 Input 覆盖, 而 `$^+a::` 将优先于 Input.

脚本中首次使用此命令时, 会安装键盘钩子(在还没有安装时). 同时, 脚本变成持续运行的, 这意味着应该使用 ExitApp 结束脚本. 键盘钩子会一直保持加载状态, 直到下一次使用 Suspend 或 Hotkey 命令, 此时如果没有任何热键或热字串需要那么它会被移除.

如果您使用多种语言或多种键盘布局, 则 Input 会使用活动窗口的键盘布局而不是脚本的(不论 Input 是否可见). 然而, 在 1.0.44.03 之前的脚本中, 则使用脚本自己的布局.

尽管不够灵活, 但热字串通常比 Input 命令更容易使用.

InputHook() 比 Input 命令更灵活.

## 相关

KeyWait, 热字串, InputBox, #InstallKeybdHook, 线程, if var in/contains MatchList

## 示例

等待用户按下任意键. 产生不可见字符的这些键(例如, 修饰键, 功能键和方向键) 已经被列为终止键, 这样就能检测到它们.

    Input, SingleKey, L1, {LControl}{RControl}{LAlt}{RAlt}{LShift}{RShift}{LWin}{RWin}{AppsKey}{F1}{F2}{F3}{F4}{F5}{F6}{F7}{F8}{F9}{F10}{F11}{F12}{Left}{Right}{Up}{Down}{Home}{End}{PgUp}{PgDn}{Del}{Ins}{BS}{CapsLock}{NumLock}{PrintScreen}{Pause}

由于此热键含有颚化符(~) 前缀, 所以它本身的键击会被传递到活动窗口. 因此, 如果您键入 `[btw`(或其他某个匹配词组) 到任意编辑器中, 脚本会自动执行您选择的动作(例如替换键入的文本). 有关此示例的另一个版本, 请参阅 Switch.

    ~[::
    Input, UserInput, V T5 L4 C, {enter}.{esc}{tab}, btw,otoh,fl,ahk,ca
    if (ErrorLevel = "Max")
    {
        MsgBox, You entered "%UserInput%", which is the maximum length of text.
        return
    }
    if (ErrorLevel = "Timeout")
    {
        MsgBox, You entered "%UserInput%" at which time the input timed out.
        return
    }
    if (ErrorLevel = "NewInput")
        return
    If InStr(ErrorLevel, "EndKey:")
    {
        MsgBox, You entered "%UserInput%" and terminated the input with %ErrorLevel%.
        return
    }
    ; 否则, 找到了匹配.
    if (UserInput = "btw")
        Send, {backspace 4}by the way
    else if (UserInput = "otoh")
        Send, {backspace 5}on the other hand
    else if (UserInput = "fl")
        Send, {backspace 3}Florida
    else if (UserInput = "ca")
        Send, {backspace 3}California
    else if (UserInput = "ahk")
        Run, https://www.autohotkey.com
    return

dftg