gpui-kit Stepper 组件完全指南用 GPUI 构建多步骤导航流程【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit导读本文基于 gpui-kit 仓库中 stepper.md 文档结合 crates/component/src/stepper 源码实现系统讲解 Stepper 分步导航组件的完整用法。Stepper 是面向表单、向导Wizard、订单流程等场景的步骤进度组件支持水平/垂直布局、自定义图标、四种尺寸规格与多级禁用控制。读完本文你将掌握Stepper与StepperItem的全部公开 API、事件回调写法、与Sizable尺寸体系及主题 tokens 的联动机制并能直接写出可运行的多步骤表单。组件定位与适用场景Stepper 组件用于引导用户按顺序完成一系列步骤或阶段例如注册流程、结账向导、配置引导。其核心能力包括水平 / 垂直两种布局Axis驱动每步可配置自定义图标未配置图标时自动显示步骤序号四种尺寸XSmall / Small / Medium / Large整体禁用与单步禁用两级控制点击事件回调配合cx.listener实现受控状态更新。从源码看组件在 crates/component/src/lib.rs 中以pub mod stepper;导出模块内部由三个文件组成stepper.rs容器、item.rs步骤项与分隔线、trigger.rs指示器触发器架构清晰、职责单一。快速上手导入use gpui_kit::component::stepper::{Stepper, StepperItem}; use gpui_kit::component::IconName; // 使用图标时导入 use gpui_kit::component::{Sizable as _, Size}; // 使用尺寸方法时导入基础 Stepperselected_index用于设置当前激活步骤索引从 0 开始默认值为 0即默认高亮第一步Stepper::new(my-stepper) .selected_index(0) .items([ StepperItem::new().child(Step 1), StepperItem::new().child(Step 2), StepperItem::new().child(Step 3), ]) .on_click(|step, _, _| { println!(Clicked step: {}, step); })对应源码 stepper.rsStepper::new默认使用水平布局Axis::Horizontal、step 0、disabled false、size Size::default()即 Medium。on_click回调的第一个参数是被点击步骤的索引类型为usize。自定义图标每步可通过icon(IconName::...)设置图标不设置时StepperTrigger会自动渲染步骤序号见 trigger.rs。use gpui_kit::component::IconName; Stepper::new(icon-stepper) .selected_index(0) .items([ StepperItem::new() .icon(IconName::Calendar) .child(Order Details), StepperItem::new() .icon(IconName::Inbox) .child(Shipping), StepperItem::new() .icon(IconName::Frame) .child(Preview), StepperItem::new() .icon(IconName::Info) .child(Finish), ])图标直接来源于 gpui-kit 的图标体系基于 lucide 图标集见 crates/assets。示例故事 stepper_story.rs 中即用 Calendar / Inbox / Frame / Info 组合演示了订单 → 发货 → 预览 → 完成的电商流程。布局控制垂直布局调用.vertical()将布局切换为垂直方向内部等价于layout(Axis::Vertical)见 stepper.rsStepper::new(vertical-stepper) .vertical() .selected_index(2) .items_center() .items([ StepperItem::new() .pb_8() .icon(IconName::Building2) .child(v_flex().child(Step 1).child(Description for step 1.)), StepperItem::new() .pb_8() .icon(IconName::Asterisk) .child(v_flex().child(Step 2).child(Description for step 2.)), StepperItem::new() .pb_8() .icon(IconName::Folder) .child(v_flex().child(Step 3).child(Description for step 3.)), StepperItem::new() .icon(IconName::CircleCheck) .child(v_flex().child(Step 4).child(Description for step 4.)), ])其中.items_center()让步骤指示器水平居中对齐用于标题位于指示器右侧的垂直场景.pb_8()为每个步骤项增加底部 8px 内边距除最后一项外拉开垂直间距。垂直布局下每个步骤项内部采用h_flex().gap_2()见 trigger.rs即指示器 文本横向排列而水平布局下采用v_flex().gap_1()即指示器在上、文本在下。文本居中.text_center(true)将每个步骤内的文本居中显示适合图标与文字同轴居中的场景Stepper::new(center-stepper) .selected_index(0) .text_center(true) .items([ StepperItem::new().child( v_flex() .items_center() .child(Step 1) .child(Desc for step 1.), ), StepperItem::new().child( v_flex() .items_center() .child(Step 2) .child(Desc for step 2.), ), StepperItem::new().child( v_flex() .items_center() .child(Step 3) .child(Desc for step 3.), ), ])源码层面text_center会影响三层结构容器布局中步骤项增加flex_1().justify_center()item.rs、触发器内部items_center()trigger.rs、以及分隔线的定位方式改为以图标中心为对称轴见 item.rs。尺寸规格SizingStepper实现了Sizabletraitsizing.rs可用四个快捷方法设置尺寸use gpui_kit::component::{Sizable as _, Size}; Stepper::new(stepper) .xsmall() .items([...]) Stepper::new(stepper) .small() .items([...]) Stepper::new(stepper) .large() .items([...])尺寸一览方法对应Size说明.xsmall()Size::XSmall极小尺寸指示器仅 8px不渲染图标/序号.small()Size::Small小尺寸指示器 18px.medium()默认Size::Medium中尺寸指示器 24px.large()Size::Large大尺寸指示器 32px尺寸对组件的影响在 item.rs 中有明确映射指示器圆形容器的直径分别为 8 / 18 / 32 / 24 px。同时文本字号跟随size.smaller()Medium 时对应 Small 字号自动缩放见 trigger.rs。需要注意两个特殊行为XSmall 不渲染图标/序号StepperTrigger中.when(self.size ! Size::XSmall, ...)的逻辑表明XSmall 尺寸下指示器内部保持空白trigger.rs分隔线粗细也随尺寸变化XSmall 为 1.5px、Large 为 3px、其余为 2pxitem.rs。禁用状态整体禁用.disabled(true)禁用整个 Stepper所有步骤不可点击且指示器不再响应 hover / active 状态Stepper::new(disabled-stepper) .disabled(true) .items([ StepperItem::new().child(Step 1), StepperItem::new().child(Step 2), ])从源码看禁用有两层保障容器层把disabled透传给每个 itemstepper.rs触发器层在disabled时不注册on_click事件trigger.rs同时跳过 hover / active 背景切换trigger.rs。单步禁用StepperItem也有独立的.disabled(true)。根据源码注释单项禁用会覆盖 Stepper 的整体禁用状态item.rsStepper::new(stepper) .selected_index(0) .items([ StepperItem::new().child(Available), StepperItem::new().disabled(true).child(Locked), StepperItem::new().child(Available), ])这条覆盖语义意味着即使 Stepper 被整体disabled(true)将某个 item 单独设为disabled(true)也不会改变该 item 的禁用结果而整体启用时可以用它精准锁定个别步骤。事件处理受控步骤状态on_click的第一个参数是被点击步骤的索引usize。在 GPUI 中配合cx.listener即可实现受控组件——点击某步后更新状态并触发重绘Stepper::new(my-stepper) .selected_index(current_step) .items([ StepperItem::new().child(Step 1), StepperItem::new().child(Step 2), StepperItem::new().child(Step 3), ]) .on_click(cx.listener(|this, step, _, cx| { this.current_step *step; cx.notify(); }))事件传递链路为Stepper的on_click在渲染时被逐个注入到每个 itemstepper.rsitem 再转发给StepperTrigger的点击处理器trigger.rs最终以 GPUI 的on_click事件对外暴露。因此回调中拿到的step始终是真实索引可用作数组下标。状态渲染规则与主题联动理解完成 / 进行中 / 未完成三态判定有助于调试已通过的步骤step checked_step分隔线用主题 primary 色高亮item.rs已到达的步骤含当前步step checked_step指示器使用tokens.primary背景 primary_foreground文字trigger.rs未到达的步骤指示器使用tokens.secondary背景hover / active 时切换为secondary_hover/secondary_activetrigger.rs分隔线默认使用主题border色item.rs。此外每个 item 渲染为Role::ListItem并设置aria_position_in_setitem.rs保证无障碍访问与 UI 测试的可定位性配合.test_support()。综合实战多步骤表单向导将以上能力组合即可实现一个完整的多步骤表单顶部 Stepper 展示阶段.w_full()让容器占满宽度.on_click允许用户点击任意步骤跳转Stepper::new(form-stepper) .w_full() .selected_index(form_step) .items([ StepperItem::new() .icon(IconName::User) .child(Personal Info), StepperItem::new() .icon(IconName::CreditCard) .child(Payment), StepperItem::new() .icon(IconName::CircleCheck) .child(Confirmation), ]) .on_click(cx.listener(|this, step, _, cx| { this.form_step *step; cx.notify(); }))工程化建议selected_index应始终与表单当前阶段变量保持同步受控模式避免显示进度与实际阶段脱节点击回调中可增加校验逻辑例如仅允许跳转到已解锁的步骤需要响应式尺寸时可用Size::from_str(sm)之类的字符串解析能力见 sizing.rs从配置驱动尺寸。参考实现与验证官方示例故事stepper_story.rs 完整展示了水平、图标、垂直、文本居中四种形态并提供尺寸下拉与Disabled开关的交互式演示可运行crates/story查看效果容器源码crates/component/src/stepper/stepper.rs步骤项与分隔线crates/component/src/stepper/item.rs触发器与指示器crates/component/src/stepper/trigger.rs尺寸体系crates/component/src/sizing.rs模块导出crates/component/src/stepper/mod.rs小结Stepper 是 gpui-kit 中轻量但完整的流程导航组件三个源码文件容器 / 步骤项 / 触发器分层清晰公开 API 覆盖布局、图标、尺寸、禁用与事件五个维度。核心要点可归纳为selected_index默认 0 且从 0 计数尺寸影响指示器直径8/18/24/32px、分隔线粗细与文本字号StepperItem::disabled(true)可覆盖整体禁用三态渲染由step与checked_step的大小关系决定并自动联动主题 tokens。结合 stepper_story.rs 示例即可在数分钟内集成进自己的 GPUI 应用。【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gpui-kit Stepper 组件完全指南：用 GPUI 构建多步骤导航流程
gpui-kit Stepper 组件完全指南用 GPUI 构建多步骤导航流程【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit导读本文基于 gpui-kit 仓库中 stepper.md 文档结合 crates/component/src/stepper 源码实现系统讲解 Stepper 分步导航组件的完整用法。Stepper 是面向表单、向导Wizard、订单流程等场景的步骤进度组件支持水平/垂直布局、自定义图标、四种尺寸规格与多级禁用控制。读完本文你将掌握Stepper与StepperItem的全部公开 API、事件回调写法、与Sizable尺寸体系及主题 tokens 的联动机制并能直接写出可运行的多步骤表单。组件定位与适用场景Stepper 组件用于引导用户按顺序完成一系列步骤或阶段例如注册流程、结账向导、配置引导。其核心能力包括水平 / 垂直两种布局Axis驱动每步可配置自定义图标未配置图标时自动显示步骤序号四种尺寸XSmall / Small / Medium / Large整体禁用与单步禁用两级控制点击事件回调配合cx.listener实现受控状态更新。从源码看组件在 crates/component/src/lib.rs 中以pub mod stepper;导出模块内部由三个文件组成stepper.rs容器、item.rs步骤项与分隔线、trigger.rs指示器触发器架构清晰、职责单一。快速上手导入use gpui_kit::component::stepper::{Stepper, StepperItem}; use gpui_kit::component::IconName; // 使用图标时导入 use gpui_kit::component::{Sizable as _, Size}; // 使用尺寸方法时导入基础 Stepperselected_index用于设置当前激活步骤索引从 0 开始默认值为 0即默认高亮第一步Stepper::new(my-stepper) .selected_index(0) .items([ StepperItem::new().child(Step 1), StepperItem::new().child(Step 2), StepperItem::new().child(Step 3), ]) .on_click(|step, _, _| { println!(Clicked step: {}, step); })对应源码 stepper.rsStepper::new默认使用水平布局Axis::Horizontal、step 0、disabled false、size Size::default()即 Medium。on_click回调的第一个参数是被点击步骤的索引类型为usize。自定义图标每步可通过icon(IconName::...)设置图标不设置时StepperTrigger会自动渲染步骤序号见 trigger.rs。use gpui_kit::component::IconName; Stepper::new(icon-stepper) .selected_index(0) .items([ StepperItem::new() .icon(IconName::Calendar) .child(Order Details), StepperItem::new() .icon(IconName::Inbox) .child(Shipping), StepperItem::new() .icon(IconName::Frame) .child(Preview), StepperItem::new() .icon(IconName::Info) .child(Finish), ])图标直接来源于 gpui-kit 的图标体系基于 lucide 图标集见 crates/assets。示例故事 stepper_story.rs 中即用 Calendar / Inbox / Frame / Info 组合演示了订单 → 发货 → 预览 → 完成的电商流程。布局控制垂直布局调用.vertical()将布局切换为垂直方向内部等价于layout(Axis::Vertical)见 stepper.rsStepper::new(vertical-stepper) .vertical() .selected_index(2) .items_center() .items([ StepperItem::new() .pb_8() .icon(IconName::Building2) .child(v_flex().child(Step 1).child(Description for step 1.)), StepperItem::new() .pb_8() .icon(IconName::Asterisk) .child(v_flex().child(Step 2).child(Description for step 2.)), StepperItem::new() .pb_8() .icon(IconName::Folder) .child(v_flex().child(Step 3).child(Description for step 3.)), StepperItem::new() .icon(IconName::CircleCheck) .child(v_flex().child(Step 4).child(Description for step 4.)), ])其中.items_center()让步骤指示器水平居中对齐用于标题位于指示器右侧的垂直场景.pb_8()为每个步骤项增加底部 8px 内边距除最后一项外拉开垂直间距。垂直布局下每个步骤项内部采用h_flex().gap_2()见 trigger.rs即指示器 文本横向排列而水平布局下采用v_flex().gap_1()即指示器在上、文本在下。文本居中.text_center(true)将每个步骤内的文本居中显示适合图标与文字同轴居中的场景Stepper::new(center-stepper) .selected_index(0) .text_center(true) .items([ StepperItem::new().child( v_flex() .items_center() .child(Step 1) .child(Desc for step 1.), ), StepperItem::new().child( v_flex() .items_center() .child(Step 2) .child(Desc for step 2.), ), StepperItem::new().child( v_flex() .items_center() .child(Step 3) .child(Desc for step 3.), ), ])源码层面text_center会影响三层结构容器布局中步骤项增加flex_1().justify_center()item.rs、触发器内部items_center()trigger.rs、以及分隔线的定位方式改为以图标中心为对称轴见 item.rs。尺寸规格SizingStepper实现了Sizabletraitsizing.rs可用四个快捷方法设置尺寸use gpui_kit::component::{Sizable as _, Size}; Stepper::new(stepper) .xsmall() .items([...]) Stepper::new(stepper) .small() .items([...]) Stepper::new(stepper) .large() .items([...])尺寸一览方法对应Size说明.xsmall()Size::XSmall极小尺寸指示器仅 8px不渲染图标/序号.small()Size::Small小尺寸指示器 18px.medium()默认Size::Medium中尺寸指示器 24px.large()Size::Large大尺寸指示器 32px尺寸对组件的影响在 item.rs 中有明确映射指示器圆形容器的直径分别为 8 / 18 / 32 / 24 px。同时文本字号跟随size.smaller()Medium 时对应 Small 字号自动缩放见 trigger.rs。需要注意两个特殊行为XSmall 不渲染图标/序号StepperTrigger中.when(self.size ! Size::XSmall, ...)的逻辑表明XSmall 尺寸下指示器内部保持空白trigger.rs分隔线粗细也随尺寸变化XSmall 为 1.5px、Large 为 3px、其余为 2pxitem.rs。禁用状态整体禁用.disabled(true)禁用整个 Stepper所有步骤不可点击且指示器不再响应 hover / active 状态Stepper::new(disabled-stepper) .disabled(true) .items([ StepperItem::new().child(Step 1), StepperItem::new().child(Step 2), ])从源码看禁用有两层保障容器层把disabled透传给每个 itemstepper.rs触发器层在disabled时不注册on_click事件trigger.rs同时跳过 hover / active 背景切换trigger.rs。单步禁用StepperItem也有独立的.disabled(true)。根据源码注释单项禁用会覆盖 Stepper 的整体禁用状态item.rsStepper::new(stepper) .selected_index(0) .items([ StepperItem::new().child(Available), StepperItem::new().disabled(true).child(Locked), StepperItem::new().child(Available), ])这条覆盖语义意味着即使 Stepper 被整体disabled(true)将某个 item 单独设为disabled(true)也不会改变该 item 的禁用结果而整体启用时可以用它精准锁定个别步骤。事件处理受控步骤状态on_click的第一个参数是被点击步骤的索引usize。在 GPUI 中配合cx.listener即可实现受控组件——点击某步后更新状态并触发重绘Stepper::new(my-stepper) .selected_index(current_step) .items([ StepperItem::new().child(Step 1), StepperItem::new().child(Step 2), StepperItem::new().child(Step 3), ]) .on_click(cx.listener(|this, step, _, cx| { this.current_step *step; cx.notify(); }))事件传递链路为Stepper的on_click在渲染时被逐个注入到每个 itemstepper.rsitem 再转发给StepperTrigger的点击处理器trigger.rs最终以 GPUI 的on_click事件对外暴露。因此回调中拿到的step始终是真实索引可用作数组下标。状态渲染规则与主题联动理解完成 / 进行中 / 未完成三态判定有助于调试已通过的步骤step checked_step分隔线用主题 primary 色高亮item.rs已到达的步骤含当前步step checked_step指示器使用tokens.primary背景 primary_foreground文字trigger.rs未到达的步骤指示器使用tokens.secondary背景hover / active 时切换为secondary_hover/secondary_activetrigger.rs分隔线默认使用主题border色item.rs。此外每个 item 渲染为Role::ListItem并设置aria_position_in_setitem.rs保证无障碍访问与 UI 测试的可定位性配合.test_support()。综合实战多步骤表单向导将以上能力组合即可实现一个完整的多步骤表单顶部 Stepper 展示阶段.w_full()让容器占满宽度.on_click允许用户点击任意步骤跳转Stepper::new(form-stepper) .w_full() .selected_index(form_step) .items([ StepperItem::new() .icon(IconName::User) .child(Personal Info), StepperItem::new() .icon(IconName::CreditCard) .child(Payment), StepperItem::new() .icon(IconName::CircleCheck) .child(Confirmation), ]) .on_click(cx.listener(|this, step, _, cx| { this.form_step *step; cx.notify(); }))工程化建议selected_index应始终与表单当前阶段变量保持同步受控模式避免显示进度与实际阶段脱节点击回调中可增加校验逻辑例如仅允许跳转到已解锁的步骤需要响应式尺寸时可用Size::from_str(sm)之类的字符串解析能力见 sizing.rs从配置驱动尺寸。参考实现与验证官方示例故事stepper_story.rs 完整展示了水平、图标、垂直、文本居中四种形态并提供尺寸下拉与Disabled开关的交互式演示可运行crates/story查看效果容器源码crates/component/src/stepper/stepper.rs步骤项与分隔线crates/component/src/stepper/item.rs触发器与指示器crates/component/src/stepper/trigger.rs尺寸体系crates/component/src/sizing.rs模块导出crates/component/src/stepper/mod.rs小结Stepper 是 gpui-kit 中轻量但完整的流程导航组件三个源码文件容器 / 步骤项 / 触发器分层清晰公开 API 覆盖布局、图标、尺寸、禁用与事件五个维度。核心要点可归纳为selected_index默认 0 且从 0 计数尺寸影响指示器直径8/18/24/32px、分隔线粗细与文本字号StepperItem::disabled(true)可覆盖整体禁用三态渲染由step与checked_step的大小关系决定并自动联动主题 tokens。结合 stepper_story.rs 示例即可在数分钟内集成进自己的 GPUI 应用。【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考