WriteConsole 函数

项目
07/12/2023

从当前光标位置开始，将字符串写入控制台屏幕缓冲区。

语法

BOOL WINAPI WriteConsole(
  _In_             HANDLE  hConsoleOutput,
  _In_       const VOID    *lpBuffer,
  _In_             DWORD   nNumberOfCharsToWrite,
  _Out_opt_        LPDWORD lpNumberOfCharsWritten,
  _Reserved_       LPVOID  lpReserved
);

参数

hConsoleOutput [in]
控制台屏幕缓冲区的句柄。此句柄必须具有 GENERIC_WRITE 访问权限。有关详细信息，请参阅控制台缓冲区安全性和访问权限。

lpBuffer [in]
指向缓冲区的指针，该缓冲区包含要写入控制台屏幕缓冲区的字符。这应为 WriteConsoleA 的 char 数组，或 WriteConsoleW 的 wchar_t 数组。

nNumberOfCharsToWrite [in]
将要写入的字符数。如果指定数量的字符的总大小超过可用堆，则函数将失败并出现 ERROR_NOT_ENOUGH_MEMORY。

lpNumberOfCharsWritten [出，可选]
指向某个变量的指针，该变量接收实际写入的字符数。

lpReserved 保留；必须为 NULL。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

备注

WriteConsole 函数将字符写入控制台屏幕缓冲区中的当前光标位置。写入字符时，光标位置会前移。 SetConsoleCursorPosition 函数设置当前光标位置。

字符使用与控制台屏幕缓冲区关联的前景色和背景色属性进行写入。 SetConsoleTextAttribute 函数更改这些颜色。若要确定当前颜色属性和当前光标位置，请使用 GetConsoleScreenBufferInfo。

影响 WriteFile 函数行为的所有输入模式对于 WriteConsole 都具有相同的效果。若要检索和设置控制台屏幕缓冲区的输出模式，请使用 GetConsoleMode 和 SetConsoleMode 函数。

此函数使用控制台当前代码页中的 Unicode 字符或 8 位字符。控制台的代码页最初默认为系统的 OEM 代码页。若要更改控制台的代码页，请使用 SetConsoleCP 或 SetConsoleOutputCP 函数。旧版使用者也可以使用 chcp 或 mode con cp select= 命令，但不建议将其用于新开发。

如果 WriteConsole 与重定向到某个文件的标准句柄一起使用，则会失败。如果应用程序处理可重定向的多语言输出，请确定输出句柄是否为控制台句柄（一种方法是调用 GetConsoleMode 函数并检查是否成功）。如果该句柄为控制台句柄，请调用 WriteConsole。如果该句柄不是控制台句柄，则会重定向输出，应调用 WriteFile 来执行 I/O。请确保使用字节顺序标记作为 Unicode 纯文本文件的前缀。有关详细信息，请参阅使用字节顺序标记。

尽管应用程序可使用 ANSI 模式下 WriteConsole 来写入 ANSI 字符，但控制台并不支持“ANSI 转义”或“虚拟终端”序列（除非启用）。有关详细信息和操作系统版本适用性，请参阅控制台虚拟终端序列。

如果未启用虚拟终端转义序列，控制台函数可提供等效功能。有关详细信息，请参阅 SetCursorPos、SetConsoleTextAttribute 和 GetConsoleCursorInfo。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
Header	ConsoleApi.h (via WinCon.h, include Windows.h)
库	Kernel32.lib
DLL	Kernel32.dll
Unicode 和 ANSI 名称	WriteConsoleW (Unicode) 和 WriteConsoleA (ANSI)