AtomUI/docs/Desktop.Controls/Tour/TourAPI.md

Tour API 参考

命名空间

namespace AtomUI.Desktop.Controls;

AXAML 命名空间前缀：atom（xmlns:atom="https://atomui.net"）

---

枚举类型

TourStyleType

Tour 风格类型枚举，定义气泡卡片的视觉风格。

值	说明
Default	默认风格，白色背景卡片
Primary	主色调风格，主色调背景卡片

TourPlacementMode

弹出位置枚举，定义气泡卡片相对目标控件的弹出方向。

值	说明
Center	屏幕居中（无 Target 时自动使用）
Left	目标左侧
LeftTop	目标左侧，上对齐
LeftBottom	目标左侧，下对齐
Right	目标右侧
RightTop	目标右侧，上对齐
RightBottom	目标右侧，下对齐
Top	目标上方
TopLeft	目标上方，左对齐
TopRight	目标上方，右对齐
Bottom	目标下方（默认）
BottomLeft	目标下方，左对齐
BottomRight	目标下方，右对齐

---

Tour 公共属性（StyledProperty / DirectProperty）

属性名	类型	默认值	说明
IsOpen	bool	false	控制 Tour 的显示/隐藏，支持双向绑定
CurrentIndex	int	-1	当前显示步骤的索引，支持双向绑定（DirectProperty）
StepCount	int	0	步骤总数，只读（DirectProperty）
StyleType	TourStyleType	TourStyleType.Default	全局风格类型，每个步骤可单独覆盖
Placement	TourPlacementMode	TourPlacementMode.Bottom	默认弹出位置，每个步骤可单独覆盖
IsShowArrow	bool	true	是否显示指向目标的箭头
IsPointAtCenter	bool	false	箭头是否指向目标中心
IsShowMask	bool	true	是否显示遮罩层
MaskColor	IBrush?	SharedToken.ColorBgMask	遮罩层颜色
GapOffsetX	double	6	镂空区域水平外扩偏移（px）
GapOffsetY	double	6	镂空区域垂直外扩偏移（px）
GapRadius	double	2	镂空区域圆角半径（px）
IsScrollIntoView	bool	true	是否自动将目标控件滚动到可视区域
IsDisabledInteraction	bool	false	是否禁用目标控件的交互
CloseIcon	IIconTemplate?	CloseOutlined 图标	关闭按钮图标模板
Indicator	TourIndicator?	DefaultTourIndicator	步骤指示器实例
StepsSource	IEnumerable<ITourStepOption>?	null	步骤数据源（用于数据绑定场景）
ItemTemplate	IDataTemplate?	null	数据绑定场景下的步骤项模板
IsMotionEnabled	bool	跟随全局 Token	是否启用过渡动画（共享属性）

Tour 集合属性

属性名	类型	说明
Steps	ItemCollection（[Content] 属性）	步骤集合，在 AXAML 中直接声明 TourStep 子元素
CustomActions	ItemCollection	自定义操作按钮集合，插入到导航区域前方

---

TourStep 公共属性（StyledProperty）

TourStep 继承自 ContentControl，实现 ITourStepOption 接口。

属性名	类型	默认值	说明
Target	Control?	null	目标控件引用（通过 ElementName 绑定），为 null 时居中显示
Title	object?	null	步骤标题（支持字符串或自定义控件）
TitleTemplate	IDataTemplate?	null	标题数据模板
Description	object?	null	步骤描述文字
DescriptionTemplate	IDataTemplate?	null	描述数据模板
Cover	object?	null	封面图内容（Image 或任意控件）
CoverTemplate	IDataTemplate?	null	封面数据模板
CloseIcon	PathIcon?	null	关闭按钮图标（覆盖 Tour 全局设置）
IsShowArrow	bool?	null（跟随 Tour）	是否显示箭头（覆盖 Tour 全局设置）
IsPointAtCenter	bool?	null（跟随 Tour）	箭头是否指向中心（覆盖 Tour 全局设置）
Placement	TourPlacementMode?	null（跟随 Tour）	弹出位置（覆盖 Tour 全局设置）
StyleType	TourStyleType?	null（跟随 Tour）	视觉风格（覆盖 Tour 全局设置）
IsShowMask	bool?	null（跟随 Tour）	是否显示遮罩（覆盖 Tour 全局设置）
MaskColor	IBrush?	null（跟随 Tour）	遮罩颜色（覆盖 Tour 全局设置）
IsScrollIntoView	bool?	null（跟随 Tour）	是否滚动到视图（覆盖 Tour 全局设置）

注意：TourStep 的可空属性（bool?、TourPlacementMode? 等）在为 null 时自动继承 Tour 上的全局设置，非 null 时覆盖全局设置。

---

TourIndicator 公共属性（TourIndicator 抽象基类）

属性名	类型	默认值	说明
StepCount	int	0	步骤总数（由 Tour 自动绑定）
ActiveIndex	int	0	当前活跃步骤索引（由 Tour 自动绑定）
StyleType	TourStyleType	TourStyleType.Default	视觉风格（由 Tour 自动绑定）
IsMotionEnabled	bool	跟随全局 Token	是否启用动画（由 Tour 自动绑定）

DefaultTourIndicator 额外属性

属性名	类型	默认值	说明
IndicatorSize	double	由 Token 控制（6）	圆点大小
IndicatorColor	IBrush?	SharedToken.ColorFill	非活跃圆点颜色
IndicatorActiveColor	IBrush?	SharedToken.ColorPrimary	活跃圆点颜色
ItemSpacing	double	SharedToken.SpacingXXS	圆点之间的间距

TextTourIndicator

TextTourIndicator 无额外公共属性。内部通过 IndicatorText（DirectProperty）自动生成 "当前索引 / 总数" 格式文本。

---

接口

ITourStepOption

步骤选项数据接口，用于 StepsSource 数据绑定场景。同时也被 TourStep 控件实现。

public interface ITourStepOption
{
    Control? Target { get; set; }
    bool? IsShowArrow { get; set; }
    bool? IsPointAtCenter { get; set; }
    PathIcon? CloseIcon { get; set; }
    object? Cover { get; set; }
    object? Title { get; set; }
    IDataTemplate? TitleTemplate { get; set; }
    object? Description { get; set; }
    IDataTemplate? DescriptionTemplate { get; set; }
    TourPlacementMode? Placement { get; set; }
    TourStyleType? StyleType { get; set; }
    bool? IsShowMask { get; set; }
    IBrush? MaskColor { get; set; }
    bool? IsScrollIntoView { get; set; }
}

TourStepOption（POCO 实现）

TourStepOption 是 ITourStepOption 的简单 POCO 实现类，适用于在 ViewModel 中构造步骤数据。

ITourAction

自定义操作按钮接口，添加到 Tour.CustomActions 中的控件如果实现此接口，将自动接收步骤状态同步。

public interface ITourAction
{
    int StepCount { get; set; }
    int ActiveIndex { get; set; }
    TourStyleType StyleType { get; set; }
    void NotifyAttached(Tour tour) {}
}

---

公共方法

方法名	返回值	说明
ShowTour()	void	显示 Tour 引导（等效于设置 IsOpen = true）
HideTour()	void	隐藏 Tour 引导（等效于设置 IsOpen = false）
ResetState()	void	重置 Tour 状态：关闭 Tour 并将 CurrentIndex 重置为 0

---

实现的接口

IMotionAwareControl

public bool IsMotionEnabled { get; set; }

控制 Tour 相关的过渡动画是否启用。