tooltip 提示窗

tooltip 在鼠标悬停或者键盘聚焦时为 UI 元素提供额外的信息。

XML 元素

tooltip

Java 类

Tooltip

基本用法

在线示例

tooltip 是基本上所有组件和布局的内部元素。

如需通过 Jmix Studio 添加 XML 中的 tooltip 元素，请在视图 XML 中，或者 Jmix UI 结构面板中选择需要添加提示的 UI 元素，然后点击 Jmix UI 组件面板的 Add→Tooltip 进行添加。

下面的示例定义了一个带 tooltip 的 textField：

<textField label="Field with tooltip">
    <tooltip text="Tooltip text"/>
</textField>

编程式定义

tooltip 组件可以在代码中编程式定义。下面的示例为 textField 组件定义并使用了 tooltip：

@ViewComponent
private TypedTextField<String> programmaticField;

@Subscribe
public void onInit(final InitEvent event) {
    programmaticField.setTooltipText("This is a tooltip")
            .setPosition(Tooltip.TooltipPosition.START);
}

定位

在线示例

默认情况下，tooltip 会相对于其附属的目标组件进行定位，自动计算 tooltip 能显示的最佳位置，同时考虑屏幕上的可用空间并避免与其他元素重叠。

position 属性可以设置 tooltip 在屏幕上的位置。其取值范围由 TooltipPosition 枚举定义。

代码中使用 setPosition() 方法：

@ViewComponent
protected JmixSelect<Tooltip.TooltipPosition> position;
protected void initPositionItems() {
    ComponentUtils.setItemsMap(position, getPositionItemsMap());
    position.setValue(Tooltip.TooltipPosition.TOP);
}
@Subscribe("position")
protected void onPositionChange(
        ComponentValueChangeEvent<JmixSelect<Tooltip.TooltipPosition>, Tooltip.TooltipPosition> event) {
    customTooltipField.getTooltip().setPosition(event.getValue());
}
protected Map<Tooltip.TooltipPosition, String> getPositionItemsMap() {
    return Arrays.stream(Tooltip.TooltipPosition.values())
            .collect(Collectors.toMap(Function.identity(),mode -> mode.name().replace('_', ' ')));
}

XML 中，也可以指定 position 属性：

<select id="position" label="Position"/>

延迟

在线示例

tooltip 还有显示延迟和隐藏延迟的配置，可以调整其显示、消失的速度，提升用户体验。

聚焦延迟

focusDelay 属性控制当键盘聚焦在带 tooltip 的组件上时，tooltip 延迟显示的时间，以毫秒为单位。

下面的示例中，当键盘聚焦在文本控件时，tooltip 延迟 500 毫秒显示：

@Subscribe("focusDelay")
protected void onFocusDelayChange(ComponentValueChangeEvent<IntegerField, Integer> event) {
    Integer value = event.getValue();

    if (value != null && value > 0 && value <= 5000) {
        customTooltipField.getTooltip().setFocusDelay(value);
    } else {
        customTooltipField.getTooltip().setFocusDelay(0);
    }
}

隐藏延迟

hideDelay 属性控制当鼠标移出带 tooltip 的组件时，tooltip 延迟消失的时间，以毫秒为单位。

下面的示例中，当鼠标离开文本控件，tooltip 延迟 1 秒消失：

@Subscribe("hideDelay")
protected void onHideDelayChange(ComponentValueChangeEvent<IntegerField, Integer> event) {
    Integer value = event.getValue();

    if (value != null && value > 0 && value <= 5000) {
        customTooltipField.getTooltip().setHideDelay(value);
    } else {
        customTooltipField.getTooltip().setHideDelay(0);
    }
}

悬停延迟

hoverDelay 属性控制当鼠标悬停在带 tooltip 的组件上时，tooltip 延迟显示的时间，以毫秒为单位。

下面的示例中，当鼠标悬停在文本控件时，tooltip 延迟 500 毫秒显示：

@Subscribe("hoverDelay")
protected void onHoverDelayChange(ComponentValueChangeEvent<IntegerField, Integer> event) {
    Integer value = event.getValue();

    if (value != null && value > 0 && value <= 5000) {
        customTooltipField.getTooltip().setHoverDelay(value);
    } else {
        customTooltipField.getTooltip().setHoverDelay(0);
    }
}

手动触发

在线示例

tooltip 也可以编程式控制隐藏或显示，即键盘聚焦或鼠标悬停时并不会展示，而只能通过代码触发。下列场景可使用这个功能：

  • 需要根据特定的条件或用户操作显示 tooltip。

  • tooltip 的内容需要动态生成或更新。

在 XML 中，设置 manual 属性为 true。此时，tooltip 不会自动显示，而需要手动触发。

<textField id="manualTooltipField" label="Manual tooltip">
    <tooltip text="Tooltip text" manual="true" position="END_BOTTOM"/>
</textField>

然后在视图控制器中配置 tooltip。

@ViewComponent
protected TypedTextField<String> manualTooltipField;
@Autowired
protected UiComponents uiComponents;
@Subscribe
protected void onInit(InitEvent event) {
    initManualTooltip();
    initPositionItems();
}
protected void initManualTooltip() {
    JmixButton helperButton = createHelperButton();
    Tooltip tooltip = manualTooltipField.getTooltip();
    helperButton.addClickListener(e -> tooltip.setOpened(!tooltip.isOpened()));

    manualTooltipField.setSuffixComponent(helperButton);
}
protected JmixButton createHelperButton() {
    JmixButton helperButton = uiComponents.create(JmixButton.class);
    helperButton.setIcon(VaadinIcon.QUESTION_CIRCLE.create());
    helperButton.addThemeVariants(ButtonVariant.LUMO_ICON);
    helperButton.addClassName(StyleUtility.Button.LINK_BUTTON);

    return helperButton;
}

opened 属性控制 tooltip 的展示，true 表示显示，false 表示隐藏。

虽然可以手动设置 opened，但通常由框架本身根据鼠标悬停或聚焦等事件进行管理。因此，仅在需要以编程方式打开或关闭 tooltip 的情况下使用该属性。

XML 属性

下面是 tooltip 的特殊属性：

名称 描述 默认值

focusDelay

定义非手动模式下键盘聚焦时 tooltip 的显示延迟。参阅 聚焦延迟。

0

hideDelay

定义非手动模式下鼠标移出时 tooltip 的隐藏延迟。在失去焦点时，tooltip 会立即关闭。参阅 隐藏延迟。

0

hoverDelay

定义非手动模式下鼠标悬停时 tooltip 的显示延迟。参阅 悬停延迟。

0

manual

当设置为 true 时，tooltip 由代码控制而不与聚焦或悬停事件交互。参阅 手动触发。

false

opened

当设置为 true 时，tooltip 通过编程的方式打开。仅在 manual 为 true 时有效。参阅 手动触发。

false

position

定义 tooltip 相对于目标组件的显示位置。参阅 定位。

—

text

定义 tooltip 的文本。

—

事件和处理器

tooltip 元素无事件和处理器。聚焦和悬停事件由其附着的组件处理。

参考