Selector

自 2.2.1

Selector<T> 是一个通用的下拉选择器。点击它会弹出一个悬浮的候选项目列表；点击某个项目即可选中它，并可选择关闭下拉列表。每个候选项目都由可配置的 UIElementProvider<T> 渲染。当候选数量超过 max-item 时，列表会切换为可滚动的 ScrollerView。

所有在 UIElement 中记录的内容（布局、样式、事件、数据绑定等）同样适用于此处。

用法

JavaKotlinKubeJS

var selector = new Selector<String>();
selector.setCandidates(List.of("Alpha", "Beta", "Gamma"));
selector.setSelected("Alpha");
selector.setOnValueChanged(value -> {
    System.out.println("Selected: " + value);
});
parent.addChild(selector);

selector<String>({
    candidates("Alpha", "Beta", "Gamma")
    selected("Alpha")
    onChange { value -> println("Selected: $value") }
}) { }

let sel = new Selector();
sel.setCandidates(["Alpha", "Beta", "Gamma"]);
sel.setSelected("Alpha");
sel.setOnValueChanged(v => { console.log("Selected: " + v); });
parent.addChild(sel);

自定义候选项目 UI

默认情况下，每个候选项目以其 toString() 文本显示。你可以提供自定义 provider 来按任意方式渲染项目：

JavaKotlin

selector.setCandidateUIProvider(candidate ->
    new UIElement()
        .addChild(new Label().setText(candidate.displayName(), false))
);

selector<MyItem>({
    candidateUI { item ->
        element { /* build custom row for item */ }
    }
}) { }

XML

<!-- String selector with static candidates -->
<selector default-value="Beta">
    <candidate>Alpha</candidate>
    <candidate>Beta</candidate>
    <candidate>Gamma</candidate>
</selector>

XML 属性	类型	描述
`default-value`	`string`	根据其字符串值预选一个候选项目。

XML 子元素	描述
`<candidate>`	向列表中添加一个字符串候选项目。元素的文本内容用作值。

内部结构

索引	字段	类型	CSS class	描述
`0`	`display`	`UIElement`	—	主显示栏（包含 `preview` 和 `buttonIcon`）。

以下子元素嵌套在内部结构中，可以通过 CSS class 进行定位：

字段	CSS class	描述
`preview`	`.__selector_preview__`	显示当前选中项目的 UI。
`buttonIcon`	`.__selector_button-icon__`	右侧的下拉箭头图标。
`dialog`	`.__selector_dialog__`	悬浮下拉面板（打开时附加到根元素）。
`listView`	`.__selector_list-view__`	当数量 ≤ `max-item` 时直接使用的列表。
`scrollerView`	`.__selector_scroller-view__`	当数量 > `max-item` 时使用的可滚动列表。

Selector 样式

SelectorStyle 控制下拉覆盖层的外观和行为。

focus-overlay

当 Selector 被悬停或获得焦点时，绘制在其上方的纹理。

默认值：Sprites.RECT_RD_T_SOLID

JavaLSS

selector.selectorStyle(style -> style.focusOverlay(myHighlight));

selector {
    focus-overlay: rect(#FFFFFF33, 2);
}

max-item

在平面 listView 中渲染的最大项目数。当候选列表更长时，将改用 ScrollerView。

默认值：5

JavaKotlinLSS

selector.selectorStyle(style -> style.maxItemCount(8));

selector<String>({ }) { withMaxItems(8) }

selector {
    max-item: 8;
}

view-height

当候选数量超过 max-item 时，ScrollerView 的高度。

默认值：50

JavaKotlinLSS

selector.selectorStyle(style -> style.scrollerViewHeight(80f));

selector<String>({ }) { withScrollHeight(80f) }

selector {
    view-height: 80;
}

show-overlay

悬停和选中的候选项目是否以半透明覆盖层高亮显示。

默认值：true

JavaLSS

selector.selectorStyle(style -> style.showOverlay(false));

selector {
    show-overlay: false;
}

close-after-select

玩家选择项目后，下拉列表是否自动关闭。

默认值：true

JavaKotlinLSS

selector.selectorStyle(style -> style.closeAfterSelect(false));

selector<String>({ }) { closeOnSelect() }

selector {
    close-after-select: false;
}

值绑定

Selector<T> 继承自 BindableUIElement<T>，因此支持标准的数据绑定 API：

Java

selector.bind(DataBindingBuilder.string(
    () -> config.getMode(),
    mode -> config.setMode(mode)
).build());

详见数据绑定。

字段

名称	类型	访问权限	描述
`display`	`UIElement`	`public final`	主显示栏。
`preview`	`UIElement`	`public final`	显示选中项目的 UI。
`buttonIcon`	`UIElement`	`public final`	下拉箭头图标。
`dialog`	`UIElement`	`public final`	悬浮下拉面板。
`listView`	`UIElement`	`public final`	用于短候选列表的平面列表。
`scrollerView`	`ScrollerView`	`public final`	用于长候选列表的可滚动列表。
`selectorStyle`	`SelectorStyle`	`private` (getter)	当前 Selector 样式。
`candidates`	`List<T>`	`private` (getter)	当前候选列表。
`value`	`T`	`private` (getter/nullable)	当前选中的值。

方法

方法	返回类型	描述
`setCandidates(List<T>)`	`Selector<T>`	替换候选列表并重建下拉菜单。
`setCandidateUIProvider(UIElementProvider<T>)`	`Selector<T>`	设置用于渲染每个候选项目的自定义工厂。
`setSelected(T)`	`Selector<T>`	选择一个值并通知监听器。
`setOnValueChanged(Consumer<T>)`	`Selector<T>`	注册一个值变化监听器。
`selectorStyle(Consumer<SelectorStyle>)`	`Selector<T>`	流畅地配置 `SelectorStyle`。
`show()`	`void`	打开下拉菜单。
`hide()`	`void`	关闭下拉菜单。
`isOpen()`	`boolean`	如果下拉菜单当前处于打开状态，则返回 `true`。
`getValue()`	`T`	返回当前选中的值（可能为 `null`）。