ASP.NET ListBox 控制項完整操作指南

ListBox 是 ASP.NET Web Forms 中常用的伺服器端列表控制項，支援單選、多選、資料繫結與豐富的項目管理方法。本文整理其宣告語法、核心屬性、常用操作與完整範例程式碼。

1. 宣告語法

<asp:ListBox ID="MyListBox" runat="server" SelectionMode="Multiple" Rows="5">
  <asp:ListItem Value="1">第一個項目</asp:ListItem>
  <asp:ListItem Value="2">第二個項目</asp:ListItem>
  <!-- 可繼續加入更多 ListItem -->
</asp:ListBox>

關鍵屬性：

• SelectionMode="Single|Multiple"：單選或多選
• Rows：顯示行數 (對應 HTML size 屬性)
• DataSource / DataTextField / DataValueField：資料繫結用

2. 核心屬性與方法速查

3. 常用操作程式碼範例 (C#)

新增項目

lstItem.Items.Add(new ListItem("新項目文字", "值"));

刪除選取項目

if (lstItem.SelectedIndex > -1)
    lstItem.Items.Remove(lstItem.SelectedItem);

游標移動：首項、尾項、上一項、下一項

// 至首項
if (lstItem.Items.Count > 0) lstItem.SelectedIndex = 0;

// 至尾項
if (lstItem.Items.Count > 0) lstItem.SelectedIndex = lstItem.Items.Count - 1;

// 上一項
if (lstItem.SelectedIndex > 0) lstItem.SelectedIndex--;

// 下一項
if (lstItem.SelectedIndex < lstItem.Items.Count - 1) lstItem.SelectedIndex++;

項目上下移位 (Swap)

int offset = (sender == btnUp) ? -1 : 1;
int idx = lstItem.SelectedIndex;
if (idx + offset < 0 || idx + offset >= lstItem.Items.Count) return;

ListItem current = lstItem.Items[idx];
ListItem target = lstItem.Items[idx + offset];

// 交換 Text 與 Value
string tempText = current.Text;
string tempValue = current.Value;
current.Text = target.Text;
current.Value = target.Value;
target.Text = tempText;
target.Value = tempValue;

// 移動選取焦點
lstItem.SelectedIndex = idx + offset;

4. 完整 Web Form 範例 (ListBoxDemo.aspx)

<%@ Page Language="C#" %>
<script runat="server">
    protected void btnCommand_Click(object sender, EventArgs e)
    {
        Button btn = (Button)sender;
        switch (btn.ID)
        {
            case "btnAdd":
                if (!string.IsNullOrEmpty(txtItem.Text))
                    lstItem.Items.Add(new ListItem(txtItem.Text));
                break;
            case "btnDel":
                if (lstItem.SelectedIndex > -1)
                    lstItem.Items.Remove(lstItem.SelectedItem);
                break;
            case "btnUp": case "btnDown":
                MoveItem(btn.ID == "btnUp" ? -1 : 1);
                break;
            case "btnFirst": lstItem.SelectedIndex = 0; break;
            case "btnLast": lstItem.SelectedIndex = lstItem.Items.Count - 1; break;
            case "btnPrev": if (lstItem.SelectedIndex > 0) lstItem.SelectedIndex--; break;
            case "btnNext": if (lstItem.SelectedIndex < lstItem.Items.Count - 1) lstItem.SelectedIndex++; break;
        }
    }

    private void MoveItem(int offset)
    {
        int idx = lstItem.SelectedIndex;
        if (idx + offset < 0 || idx + offset >= lstItem.Items.Count) return;
        ListItem a = lstItem.Items[idx];
        ListItem b = lstItem.Items[idx + offset];
        string tText = a.Text, tVal = a.Value;
        a.Text = b.Text; a.Value = b.Value;
        b.Text = tText; b.Value = tVal;
        lstItem.SelectedIndex = idx + offset;
    }
</script>
<html><body>
<form runat="server">
    <asp:TextBox ID="txtItem" runat="server" />
    <asp:Button ID="btnAdd" Text="新增" OnClick="btnCommand_Click" runat="server" />
    <br />
    <asp:ListBox ID="lstItem" Width="200" Height="200" runat="server">
        <asp:ListItem>初始項目</asp:ListItem>
    </asp:ListBox>
    <asp:Button ID="btnDel" Text="刪除" OnClick="btnCommand_Click" runat="server" /><br />
    <asp:Button ID="btnUp" Text="上移" OnClick="btnCommand_Click" runat="server" />
    <asp:Button ID="btnDown" Text="下移" OnClick="btnCommand_Click" runat="server" /><br />
    <asp:Button ID="btnFirst" Text="首項" OnClick="btnCommand_Click" runat="server" />
    <asp:Button ID="btnPrev" Text="上一項" OnClick="btnCommand_Click" runat="server" />
    <asp:Button ID="btnNext" Text="下一項" OnClick="btnCommand_Click" runat="server" />
    <asp:Button ID="btnLast" Text="尾項" OnClick="btnCommand_Click" runat="server" />
</form></body></html>

5. 實務建議

• 大量資料請改用 DropDownList (單選) 或 ListView/GridView 搭配分頁。
• 多選時取值請用 foreach (int i in lstItem.GetSelectedIndices()) 迴圈。
• ListBox 回傳資料時只會送出 Value，若需顯示文字與值不同，請正確設定 ListItem 的 Value 屬性。