如何正确使用WriteConsoleInput函数发送KEY_EVENT键盘输入事件

AI 小北

2026-8-26

问题场景

为了从其他线程终止处于阻塞状态的控制台输入，尝试使用WriteConsoleInput函数模拟键盘输入事件，测试代码如下：

#include<Windows.h>
#include<conio.h>
#include<thread>

void KillBlockingIO() {
    DWORD entityWritten;
    INPUT_RECORD inputs;
    inputs.EventType = KEY_EVENT;
    inputs.Event.KeyEvent.bKeyDown = true;
    inputs.Event.KeyEvent.uChar.AsciiChar = VK_RETURN;
    inputs.Event.KeyEvent.wRepeatCount = 0;

    inputs.Event.KeyEvent.dwControlKeyState = 0;
    inputs.Event.KeyEvent.wVirtualKeyCode = 0;
    inputs.Event.KeyEvent.wVirtualScanCode = 0;
    // inputs.Event = { true, 0, 0, 0, VK_RETURN, 0 }; // same as above
    Sleep(2000);
    WriteConsoleInputA(GetStdHandle(STD_INPUT_HANDLE), &inputs, 1, &entityWritten);
}

int main()
{
    std::thread t(KillBlockingIO);
    char c = _getch();
    printf("character recieved without typing: %c\n", c);
    t.join();
}

上述代码可正常运行，但存在以下疑问：

代码中将KEY_EVENT结构体的wVirtualKeyCode、wVirtualScanCode、dwControlKeyState成员均设置为0，且无论修改这些成员传入什么值，程序运行结果都没有差异。
查阅官方文档未找到足够详尽的参数说明与公开代码示例，需要明确这些参数的具体作用，以及WriteConsoleInput函数的正确使用方式。

参数作用说明

KEY_EVENT_RECORD结构各成员的实际作用如下：

bKeyDown：标记事件类型，值为true表示按键按下，false表示按键释放。仅做简单唤醒阻塞读操作时只写按下事件也能触发返回，但完整模拟输入需要成对写入按下、释放两个事件，否则控制台内部的按键状态标记会持续停留在按下状态，可能引发后续输入异常。
wRepeatCount：标记该事件对应的按键重复次数，模拟单次输入时应设为1，设为0时部分低层输入API会默认按1次处理，这也是示例代码能正常运行的原因之一。
wVirtualKeyCode：按键对应的虚拟键码，是键盘按键的系统级逻辑标识。对于方向键、功能键这类没有对应ASCII字符的按键，或者需要识别Ctrl/Alt/Shift组合键的场景，必须正确填写该字段；仅模拟普通可打印字符输入时，若读操作只取字符值，该字段设为0不会影响结果。
wVirtualScanCode：键盘硬件生成的按键扫描码，是按键在硬件层面的标识。仅部分依赖硬件扫描码的程序（如老旧游戏、底层按键监听工具）会读取该字段，普通控制台字符输入逻辑不会校验该值。
uChar：存储输入字符的联合体，ANSI版本API读取AsciiChar字段，Unicode版本API读取UnicodeChar字段，是字符类输入的核心字段，示例代码正是因为正确给该字段赋值了回车符，才能被_getch正常读取。
dwControlKeyState：标记修饰键与状态键的状态，包括Ctrl、Alt、Shift是否按下，以及Caps Lock、Num Lock等开关的状态。模拟组合键（如Ctrl+C）时必须正确设置该字段，仅模拟普通字符输入时设为0即可。

WriteConsoleInput 正确使用要点

模拟完整键盘输入时，需要成对写入按键按下、按键释放两个事件，不要只写入单个按下事件。
模拟非字符按键、组合键时，必须正确填写wVirtualKeyCode和dwControlKeyState字段，不能全部置0，否则相关功能键、组合键的识别会失效。
注意字符集匹配：使用ANSI版APIWriteConsoleInputA时填写AsciiChar字段，使用Unicode版APIWriteConsoleInputW时填写UnicodeChar字段，不要混用。
扫描码可通过MapVirtualKey接口根据虚拟键码自动生成，不需要手动硬编码。

针对示例中终止阻塞IO的场景，修正后的规范注入代码如下：

void KillBlockingIO() {
    DWORD entityWritten;
    INPUT_RECORD inputs[2] = {0};
    // 回车按下事件
    inputs[0].EventType = KEY_EVENT;
    inputs[0].Event.KeyEvent.bKeyDown = true;
    inputs[0].Event.KeyEvent.wRepeatCount = 1;
    inputs[0].Event.KeyEvent.wVirtualKeyCode = VK_RETURN;
    inputs[0].Event.KeyEvent.wVirtualScanCode = MapVirtualKey(VK_RETURN, MAPVK_VK_TO_VSC);
    inputs[0].Event.KeyEvent.uChar.AsciiChar = VK_RETURN;
    inputs[0].Event.KeyEvent.dwControlKeyState = 0;
    // 回车释放事件
    inputs[1].EventType = KEY_EVENT;
    inputs[1].Event.KeyEvent.bKeyDown = false;
    inputs[1].Event.KeyEvent.wRepeatCount = 1;
    inputs[1].Event.KeyEvent.wVirtualKeyCode = VK_RETURN;
    inputs[1].Event.KeyEvent.wVirtualScanCode = MapVirtualKey(VK_RETURN, MAPVK_VK_TO_VSC);
    inputs[1].Event.KeyEvent.uChar.AsciiChar = 0;
    inputs[1].Event.KeyEvent.dwControlKeyState = 0;

    Sleep(2000);
    WriteConsoleInputA(GetStdHandle(STD_INPUT_HANDLE), inputs, 2, &entityWritten);
}

内容的提问来源于stack exchange，提问作者vector X