低级控制台输出函数

重要

本文档介绍控制台平台功能，该功能已不再是生态系统蓝图的一部分。 我们不建议在新产品中使用此内容，但我们未来将无限期支持现有使用。 我们的首选最新解决方案侧重于虚拟终端序列，以实现跨平台方案中的最大兼容性。 可以在经典控制台与虚拟终端文档中找到有关此设计决策的详细信息。

通过低级控制台输出函数可直接访问屏幕缓冲区的字符单元。 一组函数从控制台屏幕缓冲区中的任何位置开始读取或写入连续单元。 另一组函数从矩形单元块读取或写入。

下列函数读取或写入到屏幕缓冲区中指定数量的连续字符单元，以指定的单元开头。

函数	说明
ReadConsoleOutputCharacter	从屏幕缓冲区复制 Unicode 或 ANSI 字符的字符串。
WriteConsoleOutputCharacter	将 Unicode 或 ANSI 字符的字符串写入屏幕缓冲区。
ReadConsoleOutputAttribute	从屏幕缓冲区复制文本和背景色属性的字符串。
WriteConsoleOutputAttribute	将文本和背景色属性的字符串写入屏幕缓冲区。
FillConsoleOutputCharacter	将单个 Unicode 或 ANSI 字符写入到屏幕缓冲区中指定数量的连续单元。
FillConsoleOutputAttribute	将文本和背景色属性组合写入到屏幕缓冲区中指定数量的连续单元。

对于所有这些函数，遇到行的最后一个单元时，读取或写入将换行到下一行的第一个单元。 当遇到控制台屏幕缓冲区最后一行的末尾时，写入函数将放弃所有未写入的字符或属性，读取函数将报告实际写入的字符或属性的数量。

下列函数读取或写入到屏幕缓冲区中指定位置的矩形字符单元块。

函数	说明
ReadConsoleOutput	将屏幕缓冲区单元的指定块中的字符和颜色数据复制到目标缓冲区中的给定块。
WriteConsoleOutput	将字符和颜色数据从源缓冲区中的给定块复制到屏幕缓冲区单元的指定块。

这些函数将屏幕缓冲区和源或目标缓冲区视为 CHAR_INFO 结构的二维数组（包含每个单元的字符和颜色属性数据）。 这些函数指定源缓冲区或目标缓冲区的宽度和高度（以字符单元为单位），并且指向缓冲区的指针被视为指向二维数组的原点单元 (0,0) 的指针。 这些函数使用 SMALL_RECT 结构指定要在控制台屏幕缓冲区中访问的矩形，源缓冲区或目标缓冲区中左上方单元格的坐标决定相应矩形在该缓冲区中的位置。

这些函数自动裁剪指定的屏幕缓冲区矩形，以适应控制台屏幕缓冲区的边界。 例如，如果矩形指定右下角坐标（第 100 列，第 50 行），并且控制台屏幕缓冲区的宽只有 80 列，则坐标将被裁剪，使其成为（第 79 列，第 50 行）。 相似的，这个调整后的矩形再次被裁剪，以适应源或目标缓冲区的边界。 指定读取自或写入到的实际矩形的屏幕缓冲区坐标。 有关使用这些函数的示例，请参阅读取和写入字符和属性块。

此图显示了一个 ReadConsoleOutput 操作，其中裁剪发生在从控制台屏幕缓冲区读取块时，并在块复制到目标缓冲区时再次发生。 该函数报告作为复制源的实际屏幕缓冲区矩形。