Lists
本节描述了所有列表组件的共通特性,并不是一个可以实例化或直接使用的类。
在您的应用中可使用三种类型的列表:ListBox
、ChoiceBox
和 ComboBox
。这些组件都显示一系列键值对项,并提供添加、删除、选择和管理列表内项的方法。
本页面概述了所有列表组件的共享特性和行为,而每个组件的具体细节则在各自的页面中介绍。
使用 ListItem
列表组件由 ListItem
对象组成,这些对象代表列表中的单个项。每个 ListItem
与一个唯一的键和显示文本相关联。ListItem
类的重要特性包括:
通过 API 管理 ListItem
对象
各种列表组件提供了多种方法来管理项目列表并保持列表与客户端之间的一致状态。通过使用这些方法,您可以有效地管理列表中的项目。API 允许您与列表进行交互和操作,以满足您的应用需求。
添加项目
-
添加一个项目:
- 若要将
ListItem
添加到列表,您可以使用add(ListItem item)
方法。 - 您还可以通过使用
add(Object key, String text)
或add(String text)
方法按键和值添加新的ListItem
。
- 若要将
-
在特定索引插入一个项目:
- 要在特定索引插入项目,请使用
insert(int index, ListItem item)
方法。 - 您可以使用
insert(int index, Object key, String text)
或insert(int index, String text)
方法插入具有键和文本的项目。
- 要在特定索引插入项目,请使用
-
插入多个项目:
- 您可以使用
insert(int index, List< ListItem > items)
方法在指定索引处插入多个项目。
- 您可以使用
为了优化性能,减少每次使用 add()
方法时触发服务器到客户端的消息,先创建一个 ListItem
对象的列表更有效。一旦您拥有这个列表,可以使用 insert(int index, List<ListItem> items)
方法一次性添加所有项目。这种方法减少了服务器与客户端之间的通信,提高了整体效率。有关此及 webforJ 架构中的其他最佳实践的详细指南,请参阅 Client/Server Interaction。
移除项目
-
移除一个项目:
- 要从列表中移除项目,请使用
remove(int index)
或remove(Object key)
方法。
- 要从列表中移除项目,请使用
-
移除所有项目:
- 您可以使用
removeAll()
移除列表中的所有项目。
- 您可以使用
选择项目
所有列表类型都实现了 SelectableList
接口。该接口允许多种选择当前 ListItem
的方式。
使用给定的 ListItem
select(ListItem item)
以参数形式接收一个 ListItem
进行选择。
List demoList = new List();
ListItem demoItem = new ListItem("demo","Demo Item");
demoList.add(demoItem);
demoList.select(demoItem);
使用给定的 ListItem
键
selectKey(Object key)
以参数形式接收 ListItem
的键进行选择。
List demoList = new List();
demoList.add("demo","Demo Item");
demoList.selectKey("demo");
使用给定的 ListItem
索引
selectIndex(int index)
以参数形式接收一个索引以选择 ListItem
。
List demoList = new List();
demoList.add("demo","Demo Item");
demoList.selectKey(0);
其他列表操作
-
访问和更新项目:
- 要通过键或索引访问项目,请使用
getByKey(Object key)
或getByIndex(int index)
。 - 您可以使用
setText(String text)
方法更新ListItem
类中项的文本。
- 要通过键或索引访问项目,请使用
-
获取有关列表的信息:
遍历列表
所有列表组件都实现了 Java Iteratable
接口,提供了一种高效且直观的方法来遍历列表的内容。通过该接口,您可以轻松循环遍历每个 ListItem
,简单地访问、修改或对每个项执行操作,几乎不费力。Iterable
接口是 Java 语言的标准模式,确保您的代码对任何 Java 开发者都熟悉且易于维护。
以下代码示例展示了两种简单的遍历列表的方法:
list.forEach(item -> {
item.setText("Modified: " + item.getText());
});
for (ListItem item : list) {
item.setText("Modified2: " + item.getText());
}
共享列表属性
标签
所有列表组件都可以分配一个标签,这是与组件相关联的描述性文本或标题。标签提供了简单的解释或提示,以帮助用户理解特定列表的目的或预期选择。除了对可用性的意义外,列表标签在无障碍性方面也发挥着至关重要的作用,使屏幕阅读器和辅助技术能够提供准确的信息,并促进键盘导航。
辅助文本
每个列表组件都可以使用 setHelperText()
方法在列表下方显示辅助文本。该辅助文本提供有关可用选项的附加上下文或解释,确保用户拥有足够的信息以做出明智的选择。
水平对齐
所有列表组件都实现了 HasHorizontalAlignment
接口,使您可以控制组件内部文本和内容的对齐方式。
使用 setHorizontalAlignment()
方法设置对齐:
HorizontalAlignment.LEFT
(默认)HorizontalAlignment.MIDDLE
HorizontalAlignment.RIGHT
ListBox<String> listBox = new ListBox<>();
listBox.setHorizontalAlignment(HorizontalAlignment.LEFT);
要获取当前对齐方式:
HorizontalAlignment alignment = listBox.getHorizontalAlignment();
尺寸
webforJ 中的所有列表组件还实现了 HasExpanse
接口,允许您调整组件的整体大小和视觉权重。这对于将组件调整为各种 UI 上下文非常有用,例如表单、对话框、侧边栏等。
使用 setExpanse()
方法设置尺寸水平。选项包括:
Expanse.NONE
Expanse.XSMALL
Expanse.SMALL
Expanse.MEDIUM
(默认)Expanse.LARGE
Expanse.XLARGE
ListBox<String> listBox = new ListBox<>();
listBox.setExpanse(Expanse.LARGE);
您可以使用以下方式检索当前设置:
Expanse current = listBox.getExpanse();
主题
📄️ ChoiceBox
ChoiceBox 组件是一个用户界面元素,旨在为用户提供一个选项或选择的列表。用户可以从该列表中选择一个选项,通常通过点击 ChoiceBox,这会触发下拉列表的显示,其中包含可用的选择。用户还可以使用箭头键与 ChoiceBox 进行交互。当用户做出选择时,所选选项将显示在 ChoiceBox 按钮中。
📄️ ComboBox
ComboBox 组件是一个用户界面元素,旨在为用户呈现选项或选择列表,以及一个输入自定义值的字段。用户可以从此列表中选择一个选项,通常通过单击 ComboBox,这将触发显示包含可用选择的下拉列表,或者输入自定义值。用户还可以使用箭头键与 ComboBox 进行交互。当用户做出选择后,所选选项将显示在 ComboBox 中。
📄️ ListBox
ListBox 组件是一个用户界面元素,旨在显示可滚动的对象列表,并允许用户从中选择单个或多个项目。用户还可以使用箭头键与 ListBox 进行交互。