wsprintfW 函式 (winuser.h)

發行項
03/13/2024

將格式化的數據寫入指定的緩衝區。任何自變數會根據格式字串中的對應格式規格，轉換並複製到輸出緩衝區。函式會將終止 Null 字元附加至寫入的字元，但傳回值不包含其字元計數中的終止 Null 字元。

注意請勿使用。請考慮改用下列其中一個函式：StringCbPrintf、StringCbPrintfEx、StringCchPrintf 或 StringCchPrintfEx。請參閱安全性考慮。

語法

int WINAPIV wsprintfW(
  [out] LPWSTR  unnamedParam1,
  [in]  LPCWSTR unnamedParam2,
        ...     
);

參數

[out] unnamedParam1

類型： LPTSTR

要接收格式化輸出的緩衝區。緩衝區的大小上限為1,024個字節。

[in] unnamedParam2

類型： LPCTSTR

格式控制件規格。除了一般 ASCII 字元之外，每個自變數的格式規格也會出現在此字串中。如需格式規格的詳細資訊，請參閱一節。

...

一或多個選擇性自變數。自變數參數的數目和類型取決於 lpFmt 參數中對應的格式控制規格。

傳回值

類型： int

如果函式成功，傳回值就是儲存在輸出緩衝區中的字元數，而不是計算終止 Null 字元。

如果函式失敗，傳回值會小於預期的輸出長度。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

格式控制字串包含格式規格，可決定 lpFmt 參數之後自變數的輸出格式。以下討論的格式規格一律以百分比符號開頭 (%) 。如果百分比符號後面接著沒有意義做為格式欄位的字元，則字元不會格式化 (例如，%% 會產生單一百分比符號字元) 。

格式控制字串是從左至右讀取。當遇到任何) 時，第一個格式規格 (時，它會在格式控制字串轉換並根據格式規格複製到輸出緩衝區之後，導致第一個自變數的值。第二個格式規格會導致第二個自變數轉換和複製，依此類傳。如果自變數比格式規格還多，則會忽略額外的自變數。如果所有格式規格的自變數不足，結果就會未定義。

格式規格的格式如下︰

%[-][][#0][width][.precision]type

每個欄位都是單一字元或數位，表示特定格式選項。最後一個選擇性格式字段之後出現的類型字元會決定相關聯的自變數是否解譯為字元、字串或數位。最簡單的格式規格只包含百分比符號和類型字元 (，例如 %s) 。選擇性欄位可控制格式化的其他層面。以下是選擇性和必要欄位及其意義。

欄位	意義
-	以空白或零填補右側的輸出，以填滿字段寬度，使輸出靠左對齊。如果省略此欄位，則會將輸出填補到左側，使其靠右對齊。
#	在十六進位值前面加上 0x (小寫) 或 0X (大寫) 。
0	以零填補輸出值以填滿欄位寬度。如果省略此欄位，輸出值會以空格填補。
width (寬度)	將指定的最小字元數複製到輸出緩衝區。寬度欄位是非負整數。寬度規格永遠不會造成值被截斷;如果輸出值中的字元數大於指定的寬度，或寬度欄位不存在，則會列印值的所有字元，受限於有效位數規格。
.精度	針對數位，將指定的最小位數複製到輸出緩衝區。如果自變數中的位數小於指定的有效位數，則輸出值會填補左邊的零。當位數超過指定的有效位數時，不會截斷此值。如果指定的有效位數為 0 或完全省略，或者如果句點 (.) 出現時沒有數位，則精確度會設定為 1。針對字串，將指定的最大字元數複製到輸出緩衝區。
type	將對應的自變數輸出為字元、字串或數位。此欄位可以是下列任何值。 `c` 單一字元。此值會由 wsprintfA 解譯為類型 CHAR，並依 wsprintfW 輸入 WCHAR。注意 wsprintf 是定義為 wsprintfA 的宏， (Unicode 未定義) 或 wsprintfW () 定義的 Unicode。 `C` 單一字元。此值會解譯為 wsprintfA 的類型 WCHAR，以及 wsprintfW 的類型 CHAR。注意 wsprintf 是定義為 wsprintfA 的宏， (Unicode 未定義) 或 wsprintfW () 定義的 Unicode。 `d` 帶正負號的十進位整數。這個值相當於 `i`。 `hc`, `hC` 單一字元。如果字元的數值為零，則會忽略它。此值一律會解譯為類型 CHAR，即使呼叫的應用程式定義 Unicode 也一樣。 `hd` 帶正負號的短整數自變數。 `hs`, `hS` 字串。此值一律會解譯為類型 LPSTR，即使呼叫的應用程式定義 Unicode 也一樣。 `hu` 不帶正負號的短整數。 `i` 帶正負號的十進位整數。這個值相當於 `d`。 `Ix`, `IX` 64 位平臺上小寫或大寫的 64 位無符號十六進位整數、小寫或大寫的 32 位不帶正負號十六進位整數。 `lc`, `lC` 單一字元。如果字元的數值為零，則會忽略它。此值一律會解譯為類型 WCHAR，即使呼叫的應用程式定義 Unicode 也一樣。 `ld` 長帶正負號的整數。這個值相當於 `li`。 `li` 長帶正負號的整數。這個值相當於 `ld`。 `ls`, `lS` 字串。此值一律會解譯為類型 LPWSTR，即使呼叫的應用程式未定義 Unicode 也一樣。這個值相當於 `ws`。 `lu` 長不帶正負號的整數。 `lx`, `lX` 小寫或大寫的長不帶正負號十六進位整數。 `p` 指標。位址會使用十六進位列印。 `s` 字串。此值會解譯為 wsprintfA 的類型 LPSTR，而 wsprintfW 類型為 LPWSTR。注意 wsprintf 是定義為 wsprintfA 的宏， (Unicode 未定義) 或 wsprintfW () 定義的 Unicode。 `S` 字串。此值會由 wsprintfA 解譯為 LPWSTR 類型，而 wsprintfW 類型為 LPSTR。注意 wsprintf 是定義為 wsprintfA 的宏， (Unicode 未定義) 或 wsprintfW () 定義的 Unicode。 `u` 不帶正負號的整數自變數。 `x`, `X` 小寫或大寫不帶正負號的十六進位整數。

注意請務必注意， wsprintf 使用 C 呼叫慣例 (_cdecl) ，而不是標準呼叫 (_stdcall) 呼叫 慣例。因此，呼叫進程會負責將自變數從堆疊移出，而自變數會從右至左推送到堆棧上。在 C 語言模組中，C 編譯程式會執行這項工作。

若要使用大於 1024 個字節的緩衝區，請使用 _snwprintf。如需詳細資訊，請參閱 C 執行時間連結庫的檔。

注意

winuser.h 標頭會根據 UNICODE 預處理器常數的定義，將 wsprintf 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll