ScrollConsoleScreenBuffer 函数

项目
10/30/2023

重要

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

移动屏幕缓冲区中的数据块。移动的效果可以通过指定剪辑矩形来限制，因此剪辑矩形外的控制台屏幕缓冲区的内容保持不变。

语法

BOOL WINAPI ScrollConsoleScreenBuffer(
  _In_           HANDLE     hConsoleOutput,
  _In_     const SMALL_RECT *lpScrollRectangle,
  _In_opt_ const SMALL_RECT *lpClipRectangle,
  _In_           COORD      dwDestinationOrigin,
  _In_     const CHAR_INFO  *lpFill
);

参数

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

lpScrollRectangle [in]
指向 SMALL_RECT 结构的指针，其成员指定要移动的控制台屏幕缓冲区矩形的左上角和右下角坐标。

lpClipRectangle [in, optional]
指向 SMALL_RECT 结构的指针，其成员指定受滚动影响的控制台屏幕缓冲区矩形的左上角和右下角坐标。此指针可以为 NULL。

dwDestinationOrigin [in]
COORD 结构，指定 lpScrollRectangle 内容的新位置的左上角（以字符为单位）。

lpFill [in]
指向 CHAR_INFO 结构的指针，该结构指定在移动后留空的 lpScrollRectangle 和 lpClipRectangle 交集内填充单元格时使用的字符和颜色属性。

返回值

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

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

备注

ScrollConsoleScreenBuffer 将屏幕缓冲区的矩形区域的内容（由 lpScrollRectangle 参数指定）复制到控制台屏幕缓冲区的其他区域。目标矩形的维度与 lpScrollRectangle 矩形相同，其左上角位于 dwDestinationOrigin 参数指定的坐标处。 lpScrollRectangle 中与目标矩形不重叠的部分使用 lpFill 参数指定的字符和颜色属性填充。

剪辑矩形应用于在 lpScrollRectangle 矩形和目标矩形中所做的更改。例如，如果剪辑矩形不包含本应由 lpFill 的内容填充的区域，则该区域的原始内容保持不变。

如果滚动区域或目标区域超出了控制台屏幕缓冲区的尺寸，则将进行剪辑。例如，如果 lpScrollRectangle 是 (0,0) 和 (19,19) 包含的区域，dwDestinationOrigin 为 (10,15)，则目标矩形是 (10,15) 和 (29,34) 包含的区域。但是，如果控制台屏幕缓冲区宽 50 个字符、高 30 个字符，则目标矩形被剪辑到 (10,15) 和 (29,29)。如果参数指定 SMALL_RECT 结构，还会根据 lpClipRectangle 剪辑对控制台屏幕缓冲区所做的更改。如果将剪辑矩形指定为 (0,0) 和 (49,19)，则只进行在控制台屏幕缓冲区中的该区域发生的更改。

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

提示

不建议使用此 API，并且此 API 没有虚拟终端等效项。使用方式类似于通过滚动边距固定屏幕区域、通过光标定位设置区域外部的活动位置以及换行符以强制文本移动。剩余空间可以通过移动光标、设置图形属性以及编写正常文本来填充。

示例

有关示例，请参阅滚动屏幕缓冲区的内容。

要求


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