How to Use Lists如何使用列表

A JList presents the user with a group of items, displayed in one or more columns, to choose from. JList向用户提供一组项目，显示在一列或多列中，供用户选择。Lists can have many items, so they are often put in scroll panes.列表可以有许多项，因此它们通常放在滚动窗格中。

In addition to lists, the following Swing components present multiple selectable items to the user: combo boxes, menus, tables, and groups of check boxes or radio buttons. 除了列表之外，以下Swing组件还为用户提供了多个可选项：组合框、菜单、表格以及复选框或单选按钮组。To display hierarchical data, use a tree.要显示分层数据，请使用树。

The following figures shows two applications that use lists. 下图显示了两个使用列表的应用程序。This section uses these examples as a basis for the discussions that follow.本节使用这些示例作为后续讨论的基础。

ListDialog (used by ListDialogRunner)（由ListDialogRunner使用）	ListDemo

• Creating a Model创建模型
• Initializing a List初始化列表
• Selecting Items in a List选择列表中的项目
• Adding Items to and Removing Items from a List向列表中添加项目和从列表中删除项目
• Writing a Custom Cell Renderer编写自定义单元格渲染器
• The List API列表API
• Examples that Use Lists使用列表的示例

Creating a Model创建模型

There are three ways to create a list model:创建列表模型有三种方法：

• DefaultListModel — everything is pretty much taken care of for you. 一切都很好的照顾你。The examples in this page use DefaultListModel.本页面中的示例使用DefaultListModel。
• AbstractListModel — you manage the data and invoke the "fire" methods. 您可以管理数据并调用“fire”方法。For this approach, you must subclass AbstractListModel and implement the getSize and getElementAt methods inherited from the ListModel interface.对于这种方法，您必须将AbstractListModel子类化，并实现从ListModel接口继承的getSize和getElementAt方法。
• ListModel — you manage everything.你管理一切。

Initializing a List初始化列表

Here is the code from ListDialog.java that creates and sets up its list:下面是ListDialog.java中创建和设置列表的代码：

list = new JList(data); //data has type Object[]
list.setSelectionMode(ListSelectionModel.SINGLE_INTERVAL_SELECTION);
list.setLayoutOrientation(JList.HORIZONTAL_WRAP);
list.setVisibleRowCount(-1);
...
JScrollPane listScroller = new JScrollPane(list);
listScroller.setPreferredSize(new Dimension(250, 80));

The code passes an array to the list's constructor. 代码将数组传递给列表的构造函数。The array is filled with strings that were passed in from another object. 数组中填充了从另一个对象传入的字符串。In our example, the strings happen to be boys' names.在示例中，字符串恰好是男孩的名字。

Other JList constructors let you initialize a list from a Vector or from an object that adheres to the ListModel interface. 其他JList构造函数允许您从Vector或遵循ListModel接口的对象初始化列表。If you initialize a list with an array or vector, the constructor implicitly creates a default list model. 如果使用数组或向量初始化列表，构造函数将隐式创建默认列表模型。The default list model is immutable — you cannot add, remove, or replace items in the list. 默认列表模型是不可变的；无法添加、删除或替换列表中的项目。To create a list whose items can be changed individually, set the list's model to an instance of a mutable list model class, such as an instance of DefaultListModel. 要创建其项可以单独更改的列表，请将列表的模型设置为可变列表模型类的实例，例如DefaultListModel的实例。You can set a list's model when you create the list or by calling the setModel method. 您可以在创建列表时或通过调用setModel方法来设置列表的模型。See Adding Items to and Removing Items from a List for an example.有关示例，请参阅向列表中添加项目和从列表中删除项目。

The call to setSelectionMode specifies how many items the user can select, and whether they must be contiguous; the next section tells you more about selection modes.对setSelectionMode的调用指定用户可以选择多少项，以及它们是否必须连续；下一节将详细介绍选择模式。

The call to setLayoutOrientation lets the list display its data in multiple columns. 调用setLayoutOrientation可以让列表在多列中显示其数据。The value JList.HORIZONTAL_WRAP specifies that the list should display its items from left to right before wrapping to a new row. Another possible value is JList.VERTICAL_WRAP, which specifies that the data be displayed from top to bottom (as usual) before wrapping to a new column. 值JList.VERTICAL_WRAP指定列表应在换行到新行之前从左到右显示其项。另一个可能的值是JList.HORIZONTAL_WRAP，它指定数据在包装到新列之前从上到下（通常）显示。The following figures show these two wrapping possibilities, together with the default, JList.VERTICAL.下图显示了这两种包装可能性，以及默认的JList.VERTICAL。

HORIZONTAL_WRAP	VERTICAL_WRAP	VERTICAL

In combination with the call to setLayoutOrientation, invoking setVisibleRowCount(-1) makes the list display the maximum number of items possible in the available space onscreen. 结合调用setLayoutOrientation，调用setVisibleRowCount(-1)将使列表显示屏幕上可用空间中的最大项目数。Another common use of setVisibleRowCount is to specify to the lists's scroll pane how many rows the list prefers to display.setVisibleRowCount的另一个常见用法是在列表的滚动窗格中指定列表希望显示的行数。

Selecting Items in a List选择列表中的项目

A list uses an instance of ListSelectionModel to manage its selection. 列表使用ListSelectionModel的实例来管理其选择。By default, a list selection model allows any combination of items to be selected at a time. 默认情况下，列表选择模型允许一次选择项目的任意组合。You can specify a different selection mode by calling the setSelectionMode method on the list. 通过调用列表上的setSelectionMode方法，可以指定不同的选择模式。For example, both ListDialog and ListDemo set the selection mode to SINGLE_SELECTION (a constant defined by ListSelectionModel) so that only one item in the list can be selected. 例如，ListDialog和ListDemo都将选择模式设置为SINGLE_SELECTION（由ListSelectionModel定义的常量），以便只能选择列表中的一项。The following table describes the three list selection modes:下表描述了三种列表选择模式：

Mode模式	Description描述
SINGLE_SELECTION	Only one item can be selected at a time. 一次只能选择一个项目。When the user selects an item, any previously selected item is deselected first.当用户选择一个项目时，将首先取消选择任何先前选择的项目。
SINGLE_INTERVAL_SELECTION	Multiple, contiguous items can be selected. 可以选择多个连续项。When the user begins a new selection range, any previously selected items are deselected first.当用户开始一个新的选择范围时，将首先取消选择任何先前选择的项目。
MULTIPLE_INTERVAL_SELECTION	The default. 默认值。Any combination of items can be selected. 可以选择项目的任意组合。The user must explicitly deselect items.用户必须明确取消选择项目。

No matter which selection mode your list uses, the list fires list selection events whenever the selection changes. 无论列表使用哪种选择模式，只要选择发生更改，列表都会触发列表选择事件。You can process these events by adding a list selection listener to the list with the addListSelectionListener method. 您可以通过使用addListSelectionListener方法向列表添加列表选择侦听器来处理这些事件。A list selection listener must implement one method: valueChanged. 列表选择侦听器必须实现一个方法：valueChanged。Here is the valueChanged method for the listener in ListDemo:下面是ListDemo中监听器的valueChanged方法：

public void valueChanged(ListSelectionEvent e) {
    if (e.getValueIsAdjusting() == false) {

        if (list.getSelectedIndex() == -1) {
        //No selection, disable fire button.
            fireButton.setEnabled(false);

        } else {
        //Selection, enable the fire button.
            fireButton.setEnabled(true);
        }
    }
}

Many list selection events can be generated from a single user action such as a mouse click. 许多列表选择事件可以从单个用户操作（如鼠标单击）生成。The getValueIsAdjusting method returns true if the user is still manipulating the selection. 如果用户仍在操作选择，则getValueIsAdjusting方法返回true。This particular program is interested only in the final result of the user's action, so the valueChanged method does something only if getValueIsAdjusting returns false.这个特定程序只对用户操作的最终结果感兴趣，因此valueChanged方法仅在getValueIsAdjusting返回false时才执行某些操作。

Because the list is in single-selection mode, this code can use getSelectedIndex to get the index of the just-selected item. 由于列表处于单选模式，因此此代码可以使用getSelectedIndex获取刚刚选择的项的索引。JList provides other methods for setting or getting the selection when the selection mode allows more than one item to be selected. 当选择模式允许选择多个项目时，JList提供设置或获取选择的其他方法。If you want, you can listen for events on the list's list selection model rather than on the list itself. 如果需要，可以侦听列表的列表选择模型上的事件，而不是列表本身上的事件。ListSelectionDemo is an example that shows how to listen for list selection events on the list selection model and lets you change the selection mode of a list dynamically.是一个示例，演示如何在列表选择模型上侦听列表选择事件，并允许您动态更改列表的选择模式。

Adding Items to and Removing Items from a List向列表中添加项目和从列表中删除项目

The ListDemo example that we showed previously features a list whose contents can change. 我们之前展示的ListDemo示例提供了一个内容可以更改的列表。You can find the source code for ListDemo in ListDemo.java. 您可以在ListDemo.java中找到ListDemo的源代码。Here is the ListDemo code that creates a mutable list model object, puts the initial items in it, and uses the list model to create a list:下面是创建可变列表模型对象的ListDemo代码，将初始项放入其中，并使用列表模型创建列表：

listModel = new DefaultListModel();
listModel.addElement("Jane Doe");
listModel.addElement("John Smith");
listModel.addElement("Kathy Green");


list = new JList(listModel);

This particular program uses an instance of DefaultListModel, a class provided by Swing. 这个特定的程序使用了DefaultListModel的一个实例，这是Swing提供的一个类。In spite of the class name, a list does not have a DefaultListModel unless your program explicitly makes it so. 不管类名如何，列表都没有DefaultListModel，除非程序显式地这样做。If DefaultListModel does not suit your needs, you can write a custom list model, which must adhere to the ListModel interface.如果DefaultListModel不适合您的需要，您可以编写一个自定义列表模型，它必须符合ListModels接口。

The following code snippet shows the actionPerformed method for the action listener registered on the Fire button. 下面的代码片段显示了在Fire按钮上注册的操作监听器的actionPerformed方法。The bold line of code removes the selected item in the list. 粗体代码行将删除列表中的选定项。The remaining lines in the method disable the fire button if the list is now empty, and make another selection if it is not.如果列表现在为空，则该方法中的其余行将禁用fire按钮，如果列表为空，请进行另一选择。

public void actionPerformed(ActionEvent e) {
    int index = list.getSelectedIndex();
    listModel.remove(index);

    int size = listModel.getSize();

    if (size == 0) { //Nobody's left, disable firing.
        fireButton.setEnabled(false);

    } else { //Select an index.
        if (index == listModel.getSize()) {
            //removed item in last position
            index--;
        }

        list.setSelectedIndex(index);
        list.ensureIndexIsVisible(index);
    }
}

Here is the actionPerformed method for the action listener shared by the Hire button and the text field:以下是由“雇佣”按钮和文本字段共享的操作侦听器的actionPerformed方法：

public void actionPerformed(ActionEvent e) {
    String name = employeeName.getText();

    //User did not type in a unique name...
    if (name.equals("") || alreadyInList(name)) {
        Toolkit.getDefaultToolkit().beep();
        employeeName.requestFocusInWindow();
        employeeName.selectAll();
        return;
    }

    int index = list.getSelectedIndex(); //get selected index
    if (index == -1) { //no selection, so insert at beginning
        index = 0;
    } else {           //add after the selected item
        index++;
    }
listModel.insertElementAt(employeeName.getText(), index);

    //Reset the text field.
    employeeName.requestFocusInWindow();
    employeeName.setText("");

    //Select the new item and make it visible.
    list.setSelectedIndex(index);
    list.ensureIndexIsVisible(index);
}

This code uses the list model's insertElementAt method to insert the new name after the current selection or, if no selection exists, at the beginning of the list. 此代码使用列表模型的insertElementAt方法在当前选择后插入新名称，如果不存在选择，则在列表的开头插入新名称。If you just wish to add to the end of the list, you can use DefaultListModel's addElement method instead.如果您只想添加到列表的末尾，可以使用DefaultListModel的addElement方法。

Whenever items are added to, removed from, or modified in a list, the list model fires list data events. 无论何时在列表中添加、删除或修改项，列表模型都会触发列表数据事件。Refer to How to Write a List Data Listener for information about listening for these events. 有关侦听这些事件的信息，请参阅如何编写列表数据侦听器。That section contains an example that is similar to ListDemo, but adds buttons that move items up or down in the list.该部分包含一个类似于ListDemo的示例，但添加了在列表中向上或向下移动项目的按钮。

Writing a Custom Cell Renderer编写自定义单元格渲染器

A list uses an object called a cell renderer to display each of its items. 列表使用称为单元渲染器的对象来显示其每个项。The default cell renderer knows how to display strings and icons and it displays Objects by invoking toString. 默认单元格渲染器知道如何显示字符串和图标，并通过调用toString显示Object。If you want to change the way the default renderer display icons or strings, or if you want behavior different than what is provided by toString, you can implement a custom cell renderer. 如果希望更改默认渲染器显示图标或字符串的方式，或者希望行为与toString提供的不同，可以实现自定义单元格渲染器。Take these steps to provide a custom cell renderer for a list:采取以下步骤为列表提供自定义单元格渲染器：

• Write a class that implements the ListCellRenderer interface.编写一个实现ListCellRenderer接口的类。
• Create an instance of your class and call the list's setCellRenderer using the instance as an argument.创建类的实例，并使用实例作为参数调用列表的setCellRenderer。

We do not provide an example of a list with a custom cell renderer, but we do have an example of a combo box with a custom renderer — and combo boxes use the same type of renderer as lists. 我们不提供具有自定义单元格渲染器的列表示例，但我们确实提供了具有自定义渲染器的组合框示例；组合框使用与列表相同类型的渲染器。See the example described in Providing a Custom Renderer.请参见提供自定义渲染器中描述的示例。

The List API列表API

The following tables list the commonly used JList constructors and methods. 下表列出了常用的JList构造函数和方法。Other methods you are most likely to invoke on a JList object are those such as setPreferredSize that its superclasses provide. 您最可能在JList对象上调用的其他方法是其超类提供的setPreferredSize。See The JComponent API for tables of commonly used inherited methods.有关常用继承方法的表，请参阅JComponent API。

Much of the operation of a list is managed by other objects. 列表的大部分操作由其他对象管理。The items in the list are managed by a list model object, the selection is managed by a list selection model object, and most programs put a list in a scroll pane to handle scrolling. 列表中的项目由列表模型对象管理，选择由列表选择模型对象管理。大多数程序将列表放在滚动窗格中以处理滚动。For the most part, you do not need to worry about the models because JList creates them as necessary and you interact with them implicitly with JList's convenience methods.在大多数情况下，您不需要担心模型，因为JList根据需要创建模型，您可以使用JList的方便方法隐式地与它们交互。

That said, the API for using lists falls into these categories:也就是说，使用列表的API分为以下几类：

• Initializing List Data初始化列表数据
• Displaying the List显示列表
• Managing the List's Selection管理列表的选择
• Managing List Data管理列表数据

Examples that Use Lists使用列表的示例

This table shows the examples that use JList and where those examples are described.下表显示了使用JList的示例以及这些示例的描述位置。

See the Using JavaFX UI Controls: List View tutorial to learn how to create lists in JavaFX.请参阅使用JavaFXUI控件：列表视图教程，了解如何在JavaFX中创建列表。