Module  javafx.controls
软件包  javafx.scene.control

Class ListView<T>

  • 参数类型
    T - 此类型用于表示存储在ListViews items ObservableList中的对象的类型。 它也用于selection model和focus model 。
    All Implemented Interfaces:
    Styleable ， EventTarget ， Skinnable 

    @DefaultProperty("items")
public class ListView<T>
extends Control
    ListView显示用户可以从中选择或与用户可以进行交互的项目的水平或垂直列表。 ListView能够将其通用类型设置为表示后台模型中的数据类型。 这样做有利于在ListView中进行各种方法以及支持类（如下所述），类型安全。 此外，使用通用类型支持使用ListView的应用程序的大大简化开发，因为所有现代IDE都能够更加成功地使用附加类型信息自动完成。

    填充ListView

    如何创建和填充ListView的名称（Strings）的简单示例如下所示： 

       ObservableList<String> names = FXCollections.observableArrayList( "Julia", "Ian", "Sue", "Matthew", "Hannah", "Stephan", "Denise"); ListView<String> listView = new ListView<String>(names);

    ListView的元素包含在items ObservableList中 。 这个ObservableList由ListView自动观察到，这样ObservableList中发生的任何更改都将自动显示在ListView本身中。 如果将ObservableList传递给ListView构造函数是不可行的，那么设置项目的推荐方法是简单地调用： 

       ObservableList<T> content = ... listView.setItems(content);
    最后的结果是，如上所述，ListView将自动刷新视图来表示列表中的项目。

    ListView接受的另一种方法不是推荐的方法 ： 

       List<T> content = ... getItems().setAll(content);
    上述方法的问题是内容列表被复制到项目列表中 - 这意味着对内容列表的后续更改没有被观察到，并且不会在ListView中被视觉反映出来。

    ListView选择/焦点API

    要跟踪选择和重点，有必要熟悉SelectionModel和FocusModel类。 ListView最多只有一个这些类的一个实例，分别可从selectionModel和focusModel属性获得。 虽然可以使用此API来设置新的选择模型，但在大多数情况下，这不是必需的 - 默认选择和焦点模型应该在大多数情况下工作。

    实例化ListView时使用的默认值为SelectionModel是MultipleSelectionModel抽象类的实现。 但是，如selectionMode属性的API文档中所述，默认值为SelectionMode.SINGLE 。 要在默认ListView实例中启用多个选择，因此需要执行以下操作： 

       listView.getSelectionModel().setSelectionMode(SelectionMode.MULTIPLE);

    自定义ListView视觉

    可以通过替换默认的cell factory完全自定义ListView的视觉效果。 一个单元格工厂用于生成ListCell个实例，用于表示ListView中的一个项目。 有关如何编写自定义单元格的更完整的说明，请参阅Cell类文档。

    编辑

    此控件支持值的内联编辑，本节尝试概述可用的API以及如何使用它们。

    首先，细胞编辑通常需要不同于不编辑细胞的用户界面。 这是正在使用的Cell实现的责任。 对于ListView，这是cell factory的责任。 您可以选择单元格是否永久处于编辑状态（例如，这对于CheckBox单元格是常见的），或者在编辑开始时切换到不同的UI（例如，在单元格上接收到双击时）。

    要知道在单元格上请求编辑时，只需覆盖Cell.startEdit()方法，并根据需要更新单元格text和graphic属性（例如，将文本设置为空，并将图形设置为TextField ）。 此外，您还应该覆盖Cell.cancelEdit()，以便在编辑结束时将UI重置为原始的可视状态。 在这两种情况下，重要的是您还要确保您调用超级方法以使单元格执行所有必须执行的任务，以进入或退出其编辑模式。

    一旦您的单元格处于编辑状态，您最感兴趣的下一件事就是如何提交或取消正在进行的编辑。 这是您作为电池厂商的责任。 您的单元实现将基于用户输入（例如当用户按下键盘上的Enter键或ESC键时）知道编辑结束。 发生这种情况时，您有责任酌情致电Cell.commitEdit(Object)或Cell.cancelEdit() 。

    当您拨打Cell.commitEdit(Object)一个事件触发到ListView，您可以通过setOnEditCommit(javafx.event.EventHandler)添加一个EventHandler来观察 。 同样，您还可以观察edit start和edit cancel的编辑事件。

    默认情况下，ListView编辑提交处理程序是非空的，默认处理程序会尝试覆盖当前正在编辑的行中的项目的属性值。 它可以这样做，因为Cell.commitEdit(Object)方法在新值中传递，并通过被触发的ListView.EditEvent传递给编辑提交处理程序。 这只是一个调用ListView.EditEvent.getNewValue()来检索这个值的问题。

    需要注意的是，如果你把它是非常重要的setOnEditCommit(javafx.event.EventHandler)用自己EventHandler ，那么你会删除默认的处理程序。 除非您再处理该属性（或相关数据源）的回写，否则不会发生任何事情。 您可以使用Node.addEventHandler(javafx.event.EventType, javafx.event.EventHandler)方法添加一个EDIT_COMMIT_EVENT EventType与您所需的EventHandler作为第二个参数。 使用此方法，您将不会替换默认实现，但在发生编辑提交时会收到通知。

    希望这个总结回答了一些常见问题。 幸运的是，JavaFX附带了许多预先构建的单元格工厂，可以代表您处理所有的编辑要求。 您可以在javafx.scene.control.cell包中找到这些预构建的单元工厂。

    从以下版本开始：
    JavaFX 2.0
    另请参见：
    ListCell ， MultipleSelectionModel ， FocusModel

    • 构造方法详细信息

      • ListView

        public ListView​()
        创建一个默认的ListView，它将显示垂直堆叠的内容。 由于在此构造函数中没有提供ObservableList ，因此创建一个空的ObservableList，这意味着如果需要，直接调用getItems()是合法的。 但是，如其他地方所述，这不是推荐的方法（而是调用setItems(javafx.collections.ObservableList) ）。

        有关其他属性的默认状态的详细信息，请参阅ListView类文档。

      • ListView

        public ListView​(ObservableList<T> items)
        创建一个默认的ListView，它将堆叠从垂直提供的ObservableList检索的内容。

        尝试将一个监听器添加到ObservableList ，以便列表中的所有后续更改将显示给用户。

        有关其他属性的默认状态的详细信息，请参阅ListView类文档。

        参数
        items - 项目列表

    • 方法详细信息

      • editStartEvent

        public static <T> EventType<ListView.EditEvent<T>> editStartEvent​()
        EventType用于指示在事件被触发的ListView中启动编辑事件。
        参数类型
        T - 存储在此ListView中的对象的类型
        结果
        事件类型

      • editCancelEvent

        public static <T> EventType<ListView.EditEvent<T>> editCancelEvent​()
        一个EventType，用于指示在事件触发的ListView中刚刚取消了编辑事件。
        参数类型
        T - 存储在此ListView中的对象的类型
        结果
        事件类型

      • editCommitEvent

        public static <T> EventType<ListView.EditEvent<T>> editCommitEvent​()
        EventType用于指示已在触发事件的ListView中提交了编辑事件。
        参数类型
        T - 存储在此ListView中的对象的类型
        结果
        事件类型

      • setItems

        public final void setItems​(ObservableList<T> value)
        设置ListView的底层数据模型。 请注意，它具有必须与ListView本身类型匹配的通用类型。
        参数
        value - 此ListView的项目列表

      • getItems

        public final ObservableList<T> getItems​()
        返回一个ObservableList ，其中包含当前向用户显示的项目。 如果先前已经调用了setItems(javafx.collections.ObservableList)，这可能为null，但是默认情况下，它是一个空的ObservableList。
        结果
        包含要显示给用户的项目的ObservableList，如果项目以前设置为null，则为null。

      • itemsProperty

        public final ObjectProperty<ObservableList<T>> itemsProperty​()
        ListView的底层数据模型。 请注意，它具有必须与ListView本身类型匹配的通用类型。
        结果
        这个ListView的items属性

      • placeholderProperty

        public final ObjectProperty<Node> placeholderProperty​()
        当列表视图没有显示的内容时，向用户显示该节点。 可能是这种情况，因为表模型首先没有数据，或者过滤器已经应用于列表模型，导致无法显示用户。
        从以下版本开始：
        JavaFX 8.0
        另请参见：
        getPlaceholder() ， setPlaceholder(Node)

      • setPlaceholder

        public final void setPlaceholder​(Node value)
        设置属性占位符的值。
        Property description:
        当列表视图没有显示的内容时，向用户显示该节点。 可能是这种情况，因为表模型首先没有数据，或者过滤器已经应用于列表模型，导致无法显示用户。
        从以下版本开始：
        JavaFX 8.0

      • getPlaceholder

        public final Node getPlaceholder​()
        获取属性占位符的值。
        Property description:
        当列表视图没有显示的内容时，向用户显示该节点。 可能是这种情况，因为表模型首先没有数据，或者过滤器已经应用于列表模型，导致无法显示用户。
        从以下版本开始：
        JavaFX 8.0

      • getSelectionModel

        public final MultipleSelectionModel<T> getSelectionModel​()
        返回当前安装的选择模型。
        结果
        当前安装的选择模型

      • setFocusModel

        public final void setFocusModel​(FocusModel<T> value)
        设置要在ListView中使用的FocusModel 。
        参数
        value - 要在ListView中使用的FocusModel

      • getFocusModel

        public final FocusModel<T> getFocusModel​()
        返回当前安装的FocusModel 。
        结果
        当前安装的FocusModel

      • setOrientation

        public final void setOrientation​(Orientation value)
        设置ListView的方向，它决定它是垂直滚动还是水平滚动。
        参数
        value - ListView的方向

      • getOrientation

        public final Orientation getOrientation​()
        返回ListView的当前方向，它决定了它是垂直滚动还是水平滚动。
        结果
        ListView的当前方向

      • setCellFactory

        public final void setCellFactory​(Callback<ListView<T>,ListCell<T>> value)
        设置要在ListView中使用的新单元格工厂。 这迫使所有旧的ListCell被抛弃，并且新的ListCell是用新的单元格工厂创建的。
        参数
        value - 在这个ListView中使用的单元格工厂

      • getCellFactory

        public final Callback<ListView<T>,ListCell<T>> getCellFactory​()
        返回当前的单元格工厂。
        结果
        目前的电池厂

      • cellFactoryProperty

        public final ObjectProperty<Callback<ListView<T>,ListCell<T>>> cellFactoryProperty​()

        设置自定义单元格工厂具有推迟所有单元格创建的效果，允许对单元格进行全面定制。 在内部，ListView负责重用ListCells - 所有必要的是自定义单元格工厂从此函数返回可用于表示ListView中任何项目的ListCell。

        有关详细信息，请参阅Cell类文档。

        另请参见：
        getCellFactory() ， setCellFactory(Callback)

      • setFixedCellSize

        public final void setFixedCellSize​(double value)
        设置此控件的新固定单元格大小。 任何大于零的值将启用固定的单元大小模式，而零值或负值（或Region.USE_COMPUTED_SIZE）将用于禁用固定单元大小模式。
        参数
        value - 新的固定单元格大小值，或小于或等于零（或Region.USE_COMPUTED_SIZE）的值禁用。
        从以下版本开始：
        JavaFX 8.0

      • getFixedCellSize

        public final double getFixedCellSize​()
        返回固定的单元格大小值。 使用小于或等于零的值来表示禁用固定单元大小模式，大于零的值表示此控件中所有单元格的大小。
        结果
        表示该控件的固定单元大小的double，或者如果固定单元大小模式被禁用，小于或等于零的值。
        从以下版本开始：
        JavaFX 8.0

      • fixedCellSizeProperty

        public final DoubleProperty fixedCellSizeProperty​()
        指定此控件是否具有固定高度（指定值）的单元格。 如果该值小于或等于零，则所有单元格都被单独设置和定位。 这是一个缓慢的操作。 因此，当性能重要且开发人员不依赖于可变单元大小时，设置固定单元大小值是一个好主意。 一般情况下，单元格大约为24像素，因此设置固定的单元格大小为24可能导致视觉差异很小，但性能有所改善。

        要通过CSS设置此属性，请使用-fx-fixed-cell-size属性。 这不应该与-fx-cell-size属性混淆。 这两个CSS属性之间的区别是-fx-cell-size将所有单元格的大小设置为指定的大小，但不会强制这是唯一的大小（从而允许变量单元大小，并且阻止性能提升可能）。 因此，当性能很重要的时候使用-fx-fixed-cell-size，而不是-fx-cell-size。 如果在CSS中指定了两个属性，则-fx-fixed-cell-size优先。

        从以下版本开始：
        JavaFX 8.0
        另请参见：
        getFixedCellSize() ， setFixedCellSize(double)

      • setEditable

        public final void setEditable​(boolean value)
        设置属性可编辑的值。
        Property description:
        指定此ListView是否可编辑 - 只有当ListView和ListCells都可编辑时，ListCell才能进入编辑状态。

      • isEditable

        public final boolean isEditable​()
        获取可编辑属性的值。
        Property description:
        指定此ListView是否可编辑 - 只有当ListView和ListCells都可编辑时，ListCell才能进入编辑状态。

      • editableProperty

        public final BooleanProperty editableProperty​()
        指定此ListView是否可编辑 - 只有当ListView和ListCells都可编辑时，ListCell才能进入编辑状态。
        另请参见：
        isEditable() ， setEditable(boolean)

      • getEditingIndex

        public final int getEditingIndex​()
        返回ListView中当前正在编辑的项目的索引，如果没有编辑任何项目，则返回-1。
        结果
        当前正在编辑的项目的索引

      • editingIndexProperty

        public final ReadOnlyIntegerProperty editingIndexProperty​()

        用于表示当前在ListView中编辑的项目的索引的属性（如果正在进行编辑），如果没有编辑任何项目，则用于表示-1。

        无法设置编辑索引，而需要调用edit(int) 。

        另请参见：
        getEditingIndex()

      • setOnEditStart

        public final void setOnEditStart​(EventHandler<ListView.EditEvent<T>> value)
        设置当用户开始编辑时将被调用的EventHandler 。

        这是一个方便的方法 - 通过调用addEventHandler(ListView.EDIT_START_EVENT, eventHandler)可以实现相同的结果。

        参数
        value - 当用户开始编辑时将被调用的EventHandler

      • setOnEditCommit

        public final void setOnEditCommit​(EventHandler<ListView.EditEvent<T>> value)
        设置当用户完成编辑时将被调用的EventHandler 。 这被称为ListCell.commitEdit(java.lang.Object)方法的一部分。

        这是一个方便的方法 - 通过调用addEventHandler(ListView.EDIT_START_EVENT, eventHandler)相同的结果。

        参数
        value - 当用户完成编辑时将被调用的EventHandler

      • setOnEditCancel

        public final void setOnEditCancel​(EventHandler<ListView.EditEvent<T>> value)
        设置当用户取消编辑时将被调用的EventHandler 。
        参数
        value - 当用户取消编辑时将被调用的EventHandler

      • edit

        public void edit​(int itemIndex)
        指示ListView开始编辑给定索引中的项目，如果ListView为editable 。 一旦调用此方法，如果当前的cellFactoryProperty()设置为支持编辑，则Cell将切换其视觉状态以使用户可以进行输入。
        参数
        itemIndex - ListView中应编辑的项目的索引。

      • scrollTo

        public void scrollTo​(int index)
        滚动ListView，使给定索引中的项目对最终用户可见。
        参数
        index - 应该对用户可见的索引，假定它大于或等于0，小于给定ListView中包含的项目列表的大小。

      • scrollTo

        public void scrollTo​(T object)
        滚动ListView，使给定对象在视口内可见。
        参数
        object - 用户应该可以看到的对象。
        从以下版本开始：
        JavaFX 8.0

      • createDefaultSkin

        protected Skin<?> createDefaultSkin​()
        为此控件创建一个新的默认皮肤实例。 如果没有通过CSS -fx-skin提供皮肤或者在具有setSkin(...)的子类中显式设置，则调用此控件创建皮肤。
        重写：
        createDefaultSkin在 Control
        结果
        此控件的默认皮肤的新实例。 如果为null，则控件将没有皮肤，除非由css提供。

      • refresh

        public void refresh​()
        调用refresh()强制ListView控件重新创建并重新填充填充控件的可视边界所需的单元格。 换句话说，这会强制ListView更新它向用户显示的内容。 这在底层数据源以ListView本身未观察到的方式发生更改的情况下很有用。
        从以下版本开始：
        JavaFX 8u60

      • getClassCssMetaData

        public static List<CssMetaData<? extends Styleable,?>> getClassCssMetaData​()
        结果
        与此类相关联的CssMetaData可能包括其类的CssMetaData。
        从以下版本开始：
        JavaFX 8.0

      • queryAccessibleAttribute

        public Object queryAccessibleAttribute​(AccessibleAttribute attribute,
                                       Object... parameters)
        该方法由辅助技术调用以请求属性的值。

        子类通常覆盖此方法来实现特定角色所需的属性。
        如果未处理特定属性，则必须调用超类实现。

        重写：
        queryAccessibleAttribute在 Control
        参数
        attribute - 请求的属性
        parameters - 可选参数列表
        结果
        请求的属性的值
        另请参见：
        AccessibleAttribute