FillConsoleOutputCharacter 函式

發行項
12/13/2023

重要

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

從指定的座標開始，將字元寫入主控台畫面緩衝區的指定次數。

語法

BOOL WINAPI FillConsoleOutputCharacter(
  _In_  HANDLE  hConsoleOutput,
  _In_  TCHAR   cCharacter,
  _In_  DWORD   nLength,
  _In_  COORD   dwWriteCoord,
  _Out_ LPDWORD lpNumberOfCharsWritten
);

參數

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

cCharacter [in]
要寫入主控台畫面緩衝區的字元。

nLength [in]
應該寫入字元的字元儲存格數目。

dwWriteCoord [in]
COORD 結構，指定要寫入字元的第一個儲存格的字元座標。

lpNumberOfCharsWritten [out]
變數的指標，可接收實際寫入控制台畫面緩衝區的字元數。

傳回值

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

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

備註

如果要寫入的字元數超出控制台畫面緩衝區中指定數據列結尾的延伸，則會將字元寫入下一個數據列。如果要寫入的字元數超出控制台畫面緩衝區結尾，字元會寫入控制台畫面緩衝區的結尾。

寫入位置的屬性值不會變更。

此函式會從主控台的目前字碼頁使用 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 名稱	FillConsoleOutputCharacterW （Unicode）和 FillConsoleOutputCharacterA （ANSI）