LVM_INSERTITEM訊息

在清單檢視控制項中插入新專案。 您可以明確傳送此訊息，或使用 ListView_InsertItem 宏。

參數

wParam

必須為零。

lParam

指定清單檢視專案屬性之 LVITEM 結構的指標。 使用 iItem 成員來指定應該插入新專案之以零起始的索引。 如果此值大於 listview 目前包含的專案數，新專案將會附加至清單結尾，並指派正確的索引。 檢查訊息的傳回值，以判斷指派給專案的實際索引。

傳回值

如果成功，則傳回新專案的索引，否則傳回 -1。

備註

您無法使用 ListView_InsertItem 或 LVM_INSERTITEM 來插入子專案。 LVITEM結構的iSubItem成員必須是零。 如需設定子專案的詳細資訊 ，請參閱LVM_SETITEM 。

如果清單檢視控制項已設定LVS_EX_CHECKBOXES樣式，則會忽略LVITEM結構狀態成員位 12 到 15 的任何值。 使用此樣式集新增專案時，一律會設定為未核取的狀態。

如果清單檢視控制項具有LVS_SORTASCENDING或LVS_SORTDESCENDING視窗樣式，如果您嘗試插入LPSTR_TEXTCALLBACK專案做為其pszText成員的值，則LVM_INSERTITEM訊息將會失敗。

如果下列條件保留， 則LVM_INSERTITEM 訊息會以排序次序將新專案插入適當的位置：

• 您正在使用其中一個LVS_SORTXXX樣式。
• 您未使用 LVS_OWNERDRAW 樣式。
• pitem所指向結構的pszText成員未設定為 LPSTR_TEXTCALLBACK。

如果 LVITEM 結構不包含 遮罩 成員中的LVIF_GROUPID，則預設會I_GROUPIDCALLBACK iGroupId 成員的值。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
標頭	Commctrl.h
Unicode 與 ANSI 名稱	LVM_INSERTITEMW (Unicode ) 和 LVM_INSERTITEMA (ANSI)