tooltip 提示窗

在线示例

提示窗是小的弹窗，用于在鼠标悬停或者键盘聚焦时为 UI 元素提供额外的信息。

XML 元素

tooltip

XML 属性

focusDelay - hideDelay - hoverDelay - manual - opened - position - text

基本用法

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

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

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

<button icon="CREDIT_CARD">
    <tooltip text="Add a credit card" position="END_TOP"/>
</button>
tooltip basic

编程式定义

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() 方法：

programmaticField.getTooltip()
        .setPosition(Tooltip.TooltipPosition.START);

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

<textField id="textField">
    <tooltip text="Basics tooltip"
             position="END_BOTTOM"/>
</textField>

延迟

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

聚焦延迟

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

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

<textField label="Text Field">
    <tooltip text="This is a tooltip"
             focusDelay="500"/>
</textField>

隐藏延迟

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

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

<textField label="Text Field">
    <tooltip text="This is a tooltip"
             hideDelay="1000"/>
</textField>

悬停延迟

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

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

<textField label="Text Field">
    <tooltip text="This is a tooltip"
             hoverDelay="500"/>
</textField>

手动触发

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

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

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

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

<textField id="manualTextField"
           label="Text Field">
    <tooltip text="This is a tooltip"
             manual="true"/>
</textField>

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

@ViewComponent
private TypedTextField<String> manualTextField;

@Autowired
private UiComponents uiComponents;

@Subscribe
public void onInit(final InitEvent event) {
    JmixButton helperButton = createHelperButton();
    Tooltip tooltip = manualTextField.getTooltip();
    helperButton.addClickListener(e ->
            tooltip.setOpened(!tooltip.isOpened())); (1)

    manualTextField.setSuffixComponent(helperButton);
}

protected JmixButton createHelperButton() {
    JmixButton helperButton = uiComponents.create(JmixButton.class);
    helperButton.setIcon(VaadinIcon.QUESTION_CIRCLE.create());
    helperButton.addThemeVariants(ButtonVariant.LUMO_ICON,
            ButtonVariant.LUMO_TERTIARY_INLINE);

    return helperButton;
}
1 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 的文本。

参考

Vaadin 文档