AtomUI/docs/Desktop.Controls/Steps/StepsStyling.md

Steps 自定义样式指南

Steps 控件的视觉表现通过 ControlTheme + Design Token 系统控制。由于 Steps 拥有丰富的属性组合（风格 × 方向 × 尺寸 × 状态 × 指示器类型），自定义主要通过属性配置实现。

📖 Gallery 源码位置：controlgallery/AtomUIGallery/ShowCases/Views/Navigation/StepsShowCase.axaml

---

1. 使用属性直接控制

基础步骤条

<atom:Steps CurrentStep="1">
    <atom:StepsItem Header="Finished" Description="This is a description." />
    <atom:StepsItem Header="In Progress" Description="This is a description." SubHeader="Left 00:00:08" />
    <atom:StepsItem Header="Waiting" Description="This is a description." />
</atom:Steps>

小尺寸

<atom:Steps CurrentStep="1" SizeType="Small">
    <atom:StepsItem Header="Finished" Description="This is a description." />
    <atom:StepsItem Header="In Progress" Description="This is a description." />
    <atom:StepsItem Header="Waiting" Description="This is a description." />
</atom:Steps>

垂直方向

<atom:Steps CurrentStep="1" Orientation="Vertical">
    <atom:StepsItem Header="Finished" Description="This is a description." />
    <atom:StepsItem Header="In Progress" Description="This is a description." />
    <atom:StepsItem Header="Waiting" Description="This is a description." />
</atom:Steps>

导航风格

<atom:Steps CurrentStep="0" Style="Navigation" IsItemClickable="True">
    <atom:StepsItem Header="Step 1" Status="Finish" />
    <atom:StepsItem Header="Step 2" Status="Process" />
    <atom:StepsItem Header="Step 3" Status="Wait" />
</atom:Steps>

点状指示器

<atom:Steps CurrentStep="1" ItemIndicatorType="Dot">
    <atom:StepsItem Header="Finished" Description="This is a description." />
    <atom:StepsItem Header="In Progress" Description="This is a description." />
    <atom:StepsItem Header="Waiting" Description="This is a description." />
</atom:Steps>

带进度环

<atom:Steps CurrentStep="1" ProgressValue="60" IsShowItemProgress="True">
    <atom:StepsItem Header="Finished" Description="This is a description." />
    <atom:StepsItem Header="In Progress" Description="This is a description." />
    <atom:StepsItem Header="Waiting" Description="This is a description." />
</atom:Steps>

标签垂直排列

<atom:Steps CurrentStep="1" LabelPlacement="Vertical">
    <atom:StepsItem Header="Finished" Description="This is a description." />
    <atom:StepsItem Header="In Progress" Description="This is a description." />
    <atom:StepsItem Header="Waiting" Description="This is a description." />
</atom:Steps>

---

2. 通过 Style 覆盖样式

自定义连接线颜色

<Style Selector="atom|StepsItem /template/ Rectangle.IndicatorLine">
    <Setter Property="Fill" Value="#E0E0E0" />
</Style>

自定义错误状态颜色

<Style Selector="atom|StepsItem[Status=Error]">
    <Setter Property="Foreground" Value="#FF4D4F" />
</Style>

可点击步骤的鼠标悬浮效果

<Style Selector="atom|StepsItem[IsClickable=True][IsSelected=False] /template/ DockPanel#RootLayout">
    <Setter Property="Background" Value="Transparent" />
    <Setter Property="Cursor" Value="Hand" />
</Style>

禁用动画

<atom:Steps IsMotionEnabled="False" CurrentStep="1">
    <!-- 步骤切换时无过渡动画 -->
</atom:Steps>

---

3. 自定义图标

通过 StepsItem.Icon 属性替换默认的数字指示器：

<atom:Steps CurrentStep="1">
    <atom:StepsItem Header="Login" Status="Finish"
                    Icon="{antdicons:AntDesignIconProvider Kind=UserOutlined}" />
    <atom:StepsItem Header="Verification" Status="Finish"
                    Icon="{antdicons:AntDesignIconProvider Kind=SolutionOutlined}" />
    <atom:StepsItem Header="Pay" Status="Process"
                    Icon="{antdicons:AntDesignIconProvider Kind=LoadingOutlined, Animation=Spin}" />
    <atom:StepsItem Header="Done" Status="Wait"
                    Icon="{antdicons:AntDesignIconProvider Kind=SmileOutlined}" />
</atom:Steps>

📖 参考：Gallery ShowCase 中 "With icon" 示例。

---

4. 步骤内容切换

通过 Steps.CurrentContent 和 Steps.CurrentContentTemplate 实现步骤关联内容的动态切换：

<StackPanel Orientation="Vertical" Spacing="20">
    <atom:Steps Name="MySteps" CurrentStep="{Binding CurrentStep}">
        <atom:StepsItem Header="First" Content="First-content" />
        <atom:StepsItem Header="Second" Content="Second-content" />
        <atom:StepsItem Header="Third" Content="Last-content" />
    </atom:Steps>

    <!-- 步骤内容展示区域 -->
    <Border Background="{atom:SharedTokenResource ColorFillAlter}"
            CornerRadius="{atom:SharedTokenResource BorderRadiusLG}"
            Height="260">
        <ContentPresenter Content="{Binding #MySteps.CurrentContent}"
                          ContentTemplate="{Binding #MySteps.CurrentContentTemplate}"
                          HorizontalAlignment="Center"
                          VerticalAlignment="Center" />
    </Border>

    <!-- 导航按钮 -->
    <StackPanel Orientation="Horizontal" Spacing="10">
        <atom:Button ButtonType="Primary" Click="HandleNextClick">Next</atom:Button>
        <atom:Button Click="HandlePreviousClick">Previous</atom:Button>
    </StackPanel>
</StackPanel>

📖 参考：Gallery ShowCase 中 "Switch Step" 示例。

---

样式选择器速查

按风格选择

选择器	说明
atom|Steps[Style=Default]	默认风格
atom|Steps[Style=Navigation]	导航风格
atom|Steps[Style=Inline]	内联风格

按方向选择

选择器	说明
atom|Steps:horizontal	水平方向（伪类）
atom|Steps:vertical	垂直方向（伪类）

按尺寸选择

选择器	说明
atom|Steps[SizeType=Small]	小尺寸
atom|Steps[SizeType=Middle]	中尺寸（默认）
atom|Steps[SizeType=Large]	大尺寸

按步骤状态选择

选择器	说明
atom|StepsItem[Status=Wait]	等待状态
atom|StepsItem[Status=Process]	进行中状态
atom|StepsItem[Status=Finish]	完成状态
atom|StepsItem[Status=Error]	错误状态
atom|StepsItem:finished	已完成步骤（伪类）
atom|StepsItem:selected	当前选中步骤（伪类）

按交互选择

选择器	说明
atom|StepsItem[IsClickable=True]	可点击步骤
atom|StepsItem[IsClickable=True][IsSelected=False]	可点击但未选中的步骤

模板部件选择器

选择器	说明
atom|Steps /template/ ItemsPresenter#PART_ItemsPresenter	步骤项容器
atom|StepsItem /template/ DockPanel#RootLayout	步骤项根布局
atom|StepsItem /template/ atom|StepsItemIndicator#PART_Indicator	步骤指示器
atom|StepsItem /template/ Rectangle.IndicatorLine	连接线
atom|StepsItem /template/ ContentPresenter#HeaderPresenter	标题展示器
atom|StepsItem /template/ ContentPresenter#SubHeaderPresenter	副标题展示器
atom|StepsItem /template/ ContentPresenter#DescriptionPresenter	描述展示器

组合选择器示例

选择器	说明
atom|Steps[Style=Default][Orientation=Horizontal][SizeType=Small]	水平默认风格小尺寸
atom|Steps[Style=Navigation]:vertical	垂直导航风格
atom|StepsItem[Status=Error] /template/ Rectangle.IndicatorLine	错误状态的连接线
atom|StepsItem[IndicatorType=Dot][Status=Process]	进行中的点状指示器