WriteConsoleOutput 函式

發行項
12/13/2023

重要

本文件說明已不再是生態系統藍圖一部分的控制台平臺功能。我們不建議您在新產品中使用此內容，但我們將繼續支持無限期的未來現有使用量。我們慣用的新式解決方案著重於 虛擬終端機序列 ，以在跨平臺案例中達到最大相容性。您可以在傳統 主控台與虛擬終端機 檔中找到此設計決策的詳細資訊。

將字元和色彩屬性數據寫入主控台畫面緩衝區中指定的字元儲存格矩形區塊。要寫入的數據取自來源緩衝區中指定位置的對應大小的矩形區塊。

語法

BOOL WINAPI WriteConsoleOutput(
  _In_          HANDLE      hConsoleOutput,
  _In_    const CHAR_INFO   *lpBuffer,
  _In_          COORD       dwBufferSize,
  _In_          COORD       dwBufferCoord,
  _Inout_       PSMALL_RECT lpWriteRegion
);

參數

hConsoleOutput [in]
主控台螢幕緩衝區的控點。句柄必須具有 GENERIC_WRITE 訪問許可權。如需詳細資訊，請參閱主控台緩衝區安全性和存取權限。

lpBuffer [in]
要寫入主控台畫面緩衝區的數據。這個指標會被視為 CHAR_INFO由 dwBufferSize 參數指定大小之結構之二維陣列的原點。

dwBufferSize [in]
字元格中 lpBuffer 參數指向的緩衝區大小。 COORD 結構的 X 成員是數據行數目;Y 成員是數據列數目。

dwBufferCoord [in]
緩衝區中左上方儲存格的座標，由 lpBuffer 參數指向。 COORD 結構的 X 成員是數據行，而 Y 成員則是數據列。

lpWriteRegion [in， out]
SMALL_RECT 結構的指標。在輸入時，結構成員會指定要寫入之控制台畫面緩衝區矩形的左上方和右下角座標。在輸出中，結構成員會指定使用的實際矩形。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

WriteConsoleOutput 會將來源緩衝區和目的地畫面緩衝區視為二維陣列（字元單元格的數據行和數據列）。 lpWriteRegion 參數所指向的矩形會指定要寫入控制台畫面緩衝區中區塊的大小和位置。相同大小的矩形位於 lpBuffer 陣列中 dwBufferCoord 參數座標處的左上方單元格。來自這個矩形交集單元格和來源緩衝區矩形的數據（其維度是由 dwBufferSize 參數所指定）寫入目的地矩形。

目的地矩形中對應的來源位置超出來源緩衝區矩形界限的單元格，不會受到寫入作業影響。換句話說，這些是沒有數據可供寫入的單元格。

在 WriteConsoleOutput 傳回之前，它會將 lpWriteRegion 的成員設定為受寫入作業影響的實際螢幕緩衝區矩形。這個矩形會反映來源緩衝區中存在對應單元格之目的矩形中的單元格，因為 WriteConsoleOutput 會將目的地矩形的維度裁剪到控制台畫面緩衝區的界限。

如果 lpWriteRegion 所指定的矩形完全位於控制台畫面緩衝區的界限之外，或對應的矩形完全位於來源緩衝區的界限之外，則不會寫入任何數據。在此情況下，函式會傳回 lpWriteRegion 參數所指向的結構成員，讓 Right 成員小於 Left，或 Bottom 成員小於 Top。 若要判斷主控台畫面緩衝區的大小，請使用 GetConsoleScreenBufferInfo 函式。

WriteConsoleOutput 對游標位置沒有任何作用。

此函式會從主控台的目前字碼頁使用 Unicode 字元或 8 位元字元。主控台的字碼頁一開始會預設為系統的 OEM 字碼頁。若要變更控制台的字碼頁，請使用 SetConsoleCP 或 SetConsoleOutputCP 函式。舊版取用者也可以使用 chcp 或 mode con cp select= 命令，但不建議用於新的開發。

提示

此 API 具有文字格式設定和 游標定位序列中的虛擬終端機對等專案。將游標移至要插入的位置、套用所需的格式設定，並寫出文字。 建議針對所有新的和持續開發使用虛擬終端機序列 。

範例

如需範例，請參閱讀取和寫入字元和屬性區塊。

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
頁首	ConsoleApi2.h （透過 WinCon.h，包含 Windows.h）
程式庫	Kernel32.lib
DLL	Kernel32.dll
Unicode 和 ANSI 名稱	WriteConsoleOutputW （Unicode）和 WriteConsoleOutputA （ANSI）