Windows 控制台文字捲動技術：ScrollConsoleScreenBuffer 深度解析

API 定義

BOOL ScrollConsoleScreenBuffer(
    HANDLE hConsoleOutput,           // 螢幕緩衝區控制代碼
    const SMALL_RECT *lpScrollRectangle, // 捲動區域
    const SMALL_RECT *lpClipRectangle,   // 裁剪區域（NULL=整個緩衝區）
    COORD dwDestinationOrigin,       // 目標左上角座標
    const CHAR_INFO *lpFill          // 填充字符屬性
);

核心參數解析

• 捲動區域：指定要移動的矩形區域
• 裁剪區域：限制捲動影響範圍；區域外內容完全不變（不被覆蓋、不被填充）
• 目標原點：捲動區域移動後的新左上角位置
• 填充字符：捲動區域移走後空出區域的填充內容

實驗驗證：裁剪區域對行為的影響

基礎場景：控制台輸出 4 行文字（0~3 行），捲動區域為第 1~2 行（索引 1~2），向下移動 5 行（目標原點 Y=5）。

實驗 1：裁剪區域 = NULL（整個緩衝區）

第 1~2 行移至第 6~7 行，原位置填充空白。第 0 行與第 3 行被覆蓋（因在裁剪區內）。

實驗 2：裁剪區域 = 捲動區域（第 1~2 行）

僅第 1~2 行內容移動，第 0 行與第 3 行完全保持原樣。移動後第 1~2 行原位置填充空白。

實驗 3：裁剪區域 = 捲動區域，僅下移 1 行

第 1 行覆蓋第 2 行，第 2 行移至第 3 行（但在裁剪區外？不），實際觀察：捲動區域內容整體下移 1 行，頂行填充空白。

實驗 4：裁剪區域 = 整個緩衝區，下移 1 行

所有行整體下移，頂行填充空白，底行捨棄。

實驗 5：裁剪區域 = 捲動區域上半部（僅第 1 行），下移 1 行

第 1 行下移至第 2 行（但第 2 行不在裁剪區內），結果：第 1 行內容消失，第 2 行不變，第 1 行填充空白。

歸納規律

完整範例程式

#include <stdio.h>
#include <windows.h>

int main() {
    HANDLE hOut = GetStdHandle(STD_OUTPUT_HANDLE);
    CONSOLE_SCREEN_BUFFER_INFO csbi;
    SMALL_RECT scrollRect = {1, 1, 10, 2}; // 第1-2行, 第1-10列
    COORD dest = {0, 5};                   // 移至第5行
    CHAR_INFO fill = {' ', 0};             // 空白填充
    
    GetConsoleScreenBufferInfo(hOut, &csbi);
    fill.Attributes = csbi.wAttributes;    // 保持原屬性
    
    // 輸出測試文字
    printf("0000000000\n");
    printf("1111111111\n");
    printf("2222222222\n");
    printf("3333333333\n");
    
    ScrollConsoleScreenBuffer(hOut, &scrollRect, NULL, dest, &fill);
    return 0;
}

實際應用場景

• 日誌視窗：固定標題列（裁剪區外），內容區捲動
• 選單介面：邊框固定，內容捲動
• 遊戲地圖：狀態欄固定，遊戲區捲動

注意事項

1. 座標系統：(0,0) 為左上角，X 向右，Y 向下
2. 捲動區域與裁剪區域以字元格為單位，非像素
3. 填充字符需包含屬性（顏色），否則會重置為預設色
4. 目標原點超出緩衝區邊界時行為未定義，需自行邊界檢查

總結

`ScrollConsoleScreenBuffer` 的關鍵在於理解裁剪區域的邊界隔離作用。善用此特性，可在控制台實現類 GUI 的區域捲動效果，是文字模式介面開發的核心技術之一。