组件/数据展示

ETour 漫游引导

import EUI 1.0

示例与代码

定位、遮罩和目标点击

QML 代码QML

import EUI 1.0 import QtQuick 2.15 import QtQuick.Layouts 1.15 import QtQuick.Controls 2.15 Column { spacing: 16 width: parent.width EButton { id: targetButton text: qsTr("启动引导") onClicked: tour.start() } ETour { id: tour placement: "bottom-start" targetAreaClickable: true gap: ({ offset: 8, radius: 6 }) steps: [{ target: targetButton, title: qsTr("操作入口"), description: qsTr("引导期间仍可点击目标。") }, { title: qsTr("完成"), description: qsTr("空目标的引导卡片自动居中。") }] } }

效果

运行代码，体验组件交互

可修改文字、属性和事件，再点击运行。

代码在当前浏览器中运行 许可

漫游引导

QML 代码QML

import EUI 1.0 import QtQuick 2.15 import QtQuick.Layouts 1.15 import QtQuick.Controls 2.15 Column { EButton { id: startButton text: "启动引导" onClicked: tour.start() } ETour { id: tour steps: [{ "target": startButton, "title": qsTr("开始"), "description": qsTr("点击此按钮。") }] } }

效果

运行代码，体验组件交互

可修改文字、属性和事件，再点击运行。

代码在当前浏览器中运行 许可

属性

属性说明取值与默认值

closeOnPressEscapebool

是否允许按 Escape 关闭。

默认值true

closePolicyenum

弹层自动关闭的触发条件，可组合多个条件。

Popup.*（可用 | 组合）
NoAutoClose
CloseOnPressOutside
CloseOnPressOutsideParent
CloseOnReleaseOutside
CloseOnReleaseOutsideParent
CloseOnEscape

默认值closeOnPressEscape ? Popup.CloseOnEscape : Popup.NoAutoClose

currentStepint

当前引导步骤的索引，从 0 开始。

默认值0

descriptionDelegateComponent

自定义说明文字的 Component 插槽；null 使用默认内容。 委托上下文见本页示例。

默认值null

enabledbool

是否允许交互；false 时控件禁用。

默认值true

focusbool

是否请求弹层焦点。

默认值true

gapvar

水印间距数组或引导高亮边距配置。

字段：
offset, radius

默认值({ offset: 6, radius: 4 })

headerDelegateComponent

自定义头部内容或表头的 Component 插槽；null 使用默认内容。 委托上下文见本页示例。

默认值null

heightreal

组件尺寸，单位为像素；可绑定父布局尺寸。

默认值动态绑定

indicatorsDelegateComponent

自定义引导步骤指示器的 Component 插槽；null 使用默认内容。 委托上下文见本页示例。

默认值null

maskbool

是否显示遮罩；滚动条还支持边缘渐隐遮罩配置。

默认值true

maskColorcolor

遮罩颜色。

默认值动态绑定

modalbool

使用模态弹层，阻止对下层内容的交互。

默认值!targetAreaClickable

placementstring

引导卡片相对于目标的位置。

"top" / "top-start"
"top-end" / "bottom"
"bottom-start" / "bottom-end"
"left" / "left-start"
"left-end" / "right"
"right-start" / "right-end"

默认值"bottom"

scrollIntoViewbool

开始步骤时滚动目标使其可见。

默认值true

scrollIntoViewOptionsvar

滚动定位配置，可设置 behavior、block、inline。

字段：
block, inline

默认值({block: "center", inline: "nearest"})

showArrowbool

是否显示弹层或引导箭头。

默认值true

showClosebool

是否显示关闭或删除按钮。

默认值true

stepsvar

引导步骤的数据数组。

字段：
target, title, description
placement, type, mask
headerDelegate, descriptionDelegate, nextButtonProps
prevButtonProps, scrollIntoViewOptions

默认值[]

targetAreaClickablebool

允许点击引导高亮区域中的目标。

默认值false

typestring

引导卡片的视觉样式。

"default" / "primary"

默认值"default"

visiblebool

是否显示组件。

默认值true

widthreal

组件尺寸，单位为像素；可绑定父布局尺寸。

默认值动态绑定

cardPositionpoint只读

引导说明卡片计算后的坐标。

字段：x, y

默认值由运行时计算

effectiveMaskbool只读

引导当前步骤实际采用的遮罩开关。

默认值由运行时计算

effectivePlacementstring只读

引导卡片相对于目标的位置。

"top" / "top-start"
"top-end" / "bottom"
"bottom-start" / "bottom-end"
"left" / "left-start"
"left-end" / "right"
"right-start" / "right-end"

默认值由运行时计算

effectiveScrollOptionsvar只读

当前引导步骤使用的滚动配置。

字段：
block, inline

默认值由运行时计算

effectiveTypestring只读

当前引导步骤使用的视觉样式。

"default" / "primary"

默认值由运行时计算

finalStepbool只读

当前是否为引导最后一步。

默认值由运行时计算

gapOffsetreal只读

引导高亮与目标之间的实际边距。

默认值由运行时计算

gapRadiusreal只读

引导高亮区域的圆角半径。

默认值由运行时计算

highlightrect只读

引导目标的高亮区域几何。

字段：x, y, width, height

默认值由运行时计算

nextButtonPropsvar只读

当前引导步骤的下一步或上一步按钮配置。

字段：
text, visible, disabled
size, styleType

默认值由运行时计算

previousButtonPropsvar只读

当前引导步骤的下一步或上一步按钮配置。

字段：
text, visible, disabled
size, styleType

默认值由运行时计算

stepvar只读

增量步长；滑块可覆盖 stepSize，时间下拉使用分钟数或 HH:mm。

默认值由运行时计算

stepCountint只读

引导总步骤数。

默认值由运行时计算

targetItem只读

滚动、定位或加载遮罩所作用的目标对象。

默认值由运行时计算

targetPositionpoint只读

固钉或引导目标计算后的坐标和尺寸。

字段：x, y

默认值由运行时计算

信号

签名作用

finished()

引导结束时触发。

changed(int index)

引导步骤变化时触发，index 为当前步骤索引。

方法

签名作用

previous()

切换到上一项或上一步。

start()

从第一步开始引导。

next()

切换到下一项或下一步。

goTo(index)

跳转到 index 指定的引导步骤。