Filament Schemas 多步骤向导Wizard完整指南从基础用法到源码级定制【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament本指南以 Filament 的packages/schemas组件库为核心系统讲解Filament\Schemas\Components\Wizard多步骤向导组件的全部能力基础搭建、提交按钮、步骤图标与描述、跳转控制、延迟加载、URL 状态持久化、生命周期钩子与操作按钮定制。读完本文你将能够在 Laravel Livewire 应用中独立实现分步校验、按序推进的高质量多步骤表单并能借助源码理解其底层推进逻辑。一、Wizard 是什么为有序流程而生的多步表单容器与 Tabs 标签页 类似Wizard 允许你将表单拆分为多个步骤Step任意时刻只渲染当前步骤从而大幅减少同时可见的组件数量。它特别适合具有明确时间顺序的业务流程——例如下单订单 → 配送 → 账单、注册、多阶段配置等——并且每一步都会在用户推进时单独校验确保错误在第一时间暴露。最基础的用法是在Wizard::make()中传入一组Step每个Step再通过schema()定义自己的字段集合use Filament\Schemas\Components\Wizard; use Filament\Schemas\Components\Wizard\Step; Wizard::make([ Step::make(Order) -schema([ // 订单相关字段... ]), Step::make(Delivery) -schema([ // 配送相关字段... ]), Step::make(Billing) -schema([ // 账单相关字段... ]), ])从源码看Wizard.php 的构造函数接受arrayStep | Closure形式的步骤数组内部通过steps()方法委托给components()完成注册Step.php 则以标签字符串为必填构造参数并在setUp()中自动生成唯一key规则为slug(标签)::statePath::wizard-step用于前端 Alpine 组件与 Livewire 请求间的状态关联。1.1 在面板资源创建页中使用向导如果你要把向导应用到资源Resource的创建流程官方推荐在创建页类上引入HasWizardtrait并在getSteps()中返回步骤数组参见 panel resource 集成文档use Filament\Resources\Pages\Concerns\HasWizard; use Filament\Resources\Pages\CreateRecord; use Filament\Schemas\Components\Wizard\Step; class CreatePostUsingWizard extends CreateRecord { use HasWizard; protected static string $resource PostResource::class; public function getSteps(): array { return [ Step::make(Step 1) -schema([ TextInput::make(title)-required(), ]), Step::make(Step 2) -schema([ TextInput::make(content)-required(), ]), ]; } }仓库中的 CreatePostUsingWizard.php 就是该写法的真实示例。这样配置后表单的提交能力只会在向导的最后一步出现用户必须依次走完所有步骤。1.2 在 Action 模态框中渲染向导同样你可以在 Action 模态框 内渲染向导不用schema()而是定义steps()数组并传入Step对象即可在模态框中获得分步表单体验。二、在最后一步渲染提交按钮submitAction()默认情况下向导底部始终显示上一步/下一步按钮而提交按钮由外层表单统一渲染。若你希望提交按钮仅在最后一步出现使用submitAction()方法它接受一段 HTML 字符串或一个 Blade 视图use Filament\Schemas\Components\Wizard; use Illuminate\Support\HtmlString; Wizard::make([ // ... ])-submitAction(view(order-form.submit-button)) Wizard::make([ // ... ])-submitAction(new HtmlString(button typesubmitSubmit/button))更推荐的做法是直接复用 Filament 内置的按钮 Blade 组件x-filament::button通过Blade::render()渲染为字符串后传入use Filament\Schemas\Components\Wizard; use Illuminate\Support\Facades\Blade; use Illuminate\Support\HtmlString; Wizard::make([ // ... ])-submitAction(new HtmlString(Blade::render(BLADE x-filament::button typesubmit sizesm Submit /x-filament::button BLADE)))你也可以把这段组件抽取为独立的 Blade 视图文件以保持整洁。从源码看submitAction()存储的值会在toEmbeddedHtml()中渲染到向导底部的一个容器里该容器通过x-bind:class{ fi-hidden: ! isLastStep() }控制显隐——即只有处于最后一步时才可见。提示如果你使用submitAction()在最后一步渲染提交按钮请务必确保外层表单确实能够被提交例如配合资源创建页的HasWizard或模态框的提交机制否则按钮将没有实际行为。三、步骤图标icon()与completedIcon()3.1 为步骤设置图标每个步骤都可以设置一个 图标用于在向导头部Header 的步骤指示条展示。使用icon()方法use Filament\Schemas\Components\Wizard\Step; use Filament\Support\Icons\Heroicon; Step::make(Order) -icon(Heroicon::ShoppingBag) -schema([ // ... ]),3.2 定制已完成步骤的图标当用户走完某一步后头部会用对勾等图标标记完成状态。你可以用completedIcon()自定义完成态的图标例如换成一个大拇指use Filament\Schemas\Components\Wizard\Step; use Filament\Support\Icons\Heroicon; Step::make(Order) -completedIcon(Heroicon::HandThumbUp) -schema([ // ... ]),在 Step.php 中icon()与completedIcon()的类型签名均为string | BackedEnum | Htmlable | Closure | null因此除了静态的图标枚举/字符串如heroicon-o-user外也可以传入闭包按当前状态动态计算。渲染时Wizard.php 会对已完成步骤优先输出completedIcon未设置时回退到内置的Heroicon::OutlinedCheck未完成的当前/未来步骤则输出icon或两位数的步骤序号。3.3 为步骤添加描述在步骤标题下方你还可以显示一行简短描述使用description()方法use Filament\Schemas\Components\Wizard\Step; Step::make(Order) -description(Review your basket) -schema([ // ... ]),描述同样支持闭包动态计算渲染位置在步骤头部的标签下方见 Step.php 中fi-sc-wizard-header-step-description对应的输出逻辑。四、控制向导的启动与导航行为4.1 设置默认激活步骤startOnStep()默认向导从第 1 步开始。若需要从指定步骤加载例如用户上次未完成回访时继续使用startOnStep()参数为从 1 开始的步骤序号use Filament\Schemas\Components\Wizard; Wizard::make([ // ... ])-startOnStep(2)从源码看getCurrentStepIndex()会以getStartStep() - 1作为初始下标startOnStep()同样支持闭包。4.2 允许自由跳转skippable()默认情况下向导是顺序推进的用户必须先校验当前步骤才能进入下一步也无法点击头部直接跳到未来的步骤。若你想放开限制使用skippable()use Filament\Schemas\Components\Wizard; Wizard::make([ // ... ])-skippable()skippable()也接受一个布尔值参数便于按条件开启Wizard::make([ // ... ])-skippable(FeatureFlag::active())其底层行为在 Wizard.php 的nextStep()与goToStep()中非常清晰nextStep()当isSkippable()为false时会对当前步骤依次执行callBeforeValidation()→getChildSchema()-validate()→callAfterValidation()并顺带用$nextStep?-fillStateWithNull()初始化下一步状态校验失败抛出Halt则直接return不切换步骤。goToStep()仅当isSkippable()为true时才允许跳到当前步骤之后的任意步骤否则只能跳转到已走过的步骤。4.3 延迟加载昂贵的步骤内容deferLoading()如果某个步骤的内容渲染成本很高例如包含复杂关系表、远程数据等你不希望它随页面首屏一起渲染可以给该步骤传入一个Schema对象并调用deferLoading()。这样活动步骤的内容会在进入视口时才加载后续步骤则要等到用户真正到达时才加载use Filament\Forms\Components\TextInput; use Filament\Schemas\Components\Wizard; use Filament\Schemas\Components\Wizard\Step; use Filament\Schemas\Schema; Wizard::make([ Step::make(Account) -key(accountStep) -schema( Schema::make() -components([ TextInput::make(name), ]) -deferLoading(), ), Step::make(Confirmation) -key(confirmationStep) -schema( Schema::make() -components([ // ... ]) -deferLoading(), ), ]) -key(accountWizard)每一个延迟加载的 schema 都必须有唯一 key。在上例中步骤上的key()会被其子 schema 继承而Wizard上的key()用于把它与其他步骤区分开、避免命名冲突。关于延迟加载的完整语义加载指示器、校验错误自动加载、隐藏组件中的延迟行为、repeater/builder 条目的自动唯一 key 等参见 Schema 总览的 Deferring the loading of a child schema 一节。4.4 将当前步骤持久化到 URL 查询字符串persistStepInQueryString()默认情况下当前所在步骤不会反映到 URL 中刷新页面后会回到起始步骤。调用persistStepInQueryString()后当前步骤会以step为 key 写入 URL 查询字符串use Filament\Schemas\Components\Wizard; Wizard::make([ // ... ])-persistStepInQueryString()你也可以传入自定义 key 替换默认的stepWizard::make([ // ... ])-persistStepInQueryString(wizard-step)源码层面的实现值得注意getStartStep()在isStepPersistedInQueryString()为真时会优先从request()-query($this-getStepQueryStringKey())读取值并与各步骤的getId()逐一比对命中则返回对应序号作为起始步骤。也就是说开启后刷新页面会停留在当前步骤非常适用于长流程表单的断点续填体验。该 key 同样支持闭包动态计算。五、步骤生命周期钩子校验前与校验后你可以在步骤级挂载校验钩子用afterValidation()和beforeValidation()在校验发生前后执行任意代码use Filament\Schemas\Components\Wizard\Step; Step::make(Order) -afterValidation(function () { // 校验通过后执行... }) -beforeValidation(function () { // 校验前执行... }) -schema([ // ... ]),两个钩子回调均支持依赖注入各类工具utility。对应的执行点位于 Wizard.php 的nextStep()中callBeforeValidation()→ 子 schema 的validate()→callAfterValidation()顺序完全固定。5.1 阻止下一步加载抛出Halt异常如果在afterValidation()或beforeValidation()中抛出Filament\Support\Exceptions\Halt向导会被迫停留在当前步骤不再加载下一步——这是实现校验通过后仍需人工确认才能继续这类业务的关键机制use Filament\Schemas\Components\Wizard\Step; use Filament\Support\Exceptions\Halt; Step::make(Order) -afterValidation(function () { // ... if (true) { throw new Halt(); } }) -schema([ // ... ]),nextStep()中正是通过catch (Halt $exception) { return; }来吞掉异常并中止步骤切换的。六、步骤内的网格布局columns()与所有布局组件一样Step支持columns()方法用于定制步骤内部的 网格系统。例如让Order步骤内的字段以两列排布use Filament\Schemas\Components\Wizard; use Filament\Schemas\Components\Wizard\Step; Wizard::make([ Step::make(Order) -columns(2) -schema([ // ... ]), // ... ])从 Step.php 的getAllColumns()可以看到未显式设置列数时步骤会继承其所在容器的列配置设置后则覆盖父级。columns()也支持闭包与响应式断点配置。七、定制向导操作按钮nextAction()与previousAction()向导底部的下一步/上一步按钮本质上是两个 Action 对象因此你可以通过传入回调函数来深度定制它们。回调接收$action参数一个Filament\Actions\Action实例可调用 Action 文档 中的任意方法nextAction()定制下一步按钮previousAction()定制上一步按钮例如将下一步按钮改名为Next stepuse Filament\Actions\Action; use Filament\Schemas\Components\Wizard; Wizard::make([ // ... ]) -nextAction( fn (Action $action) $action-label(Next step), )在 Wizard.php 中两个 Action 通过setUp()内的registerActions()自动注册名称分别为next与previous。默认的下一步按钮带iconPosition(IconPosition::After)与livewireTarget(callSchemaComponentMethod)会依据步骤数量自动生成一串从第 N 步推进到下一步的 Livewire 调用上一步按钮则默认为灰色button()。通过回调你可以自由修改标签、颜色、图标、禁用状态等。若传入null则会清空已设置的修改器、恢复默认行为。八、源码视角一次下一步点击背后发生了什么综合 Wizard.php 与 Step.php可以梳理出点击下一步的完整链路前端 Alpine 组件wizardSchemaComponent触发requestNextStep()调用暴露给 Livewire 的nextStep($currentStepIndex)方法。若skippable()未开启服务端取出当前步骤按beforeValidation → validate → afterValidation顺序执行任一步骤抛出Halt则中止。校验通过后$nextStep?-fillStateWithNull()初始化下一步的空状态随后通过$livewire-dispatch(next-wizard-step, key: ...)通知前端切换到下一步。前端监听x-on:next-wizard-step.window事件只有key匹配时才执行goToNextStep()确保多向导共存于同一页面时互不干扰。在 WizardTest.php 中可以看到对这些行为的系统性验证skippable()的默认值与闭包设置、startOnStep()与getCurrentStepIndex()的计算、persistStepInQueryString()的默认 keystep与自定义 key、submitAction()/cancelAction()的存取与清空、nextAction()/previousAction()回调对标签的修改与null清空、hiddenHeader()与contained(false)的渲染、以及浏览器端的可访问性与暗色模式测试StepTest.php 则覆盖了description()、icon()/completedIcon()的字符串/枚举/闭包三种形态、afterValidation()/beforeValidation()的调用与清空以及formWrapper()等细节。这些测试既是行为的契约也是你安全定制向导的保障。九、小结Wizard 能力速查能力方法是否支持闭包搭建步骤Wizard::make([Step::make(...), ...])步骤数组可为 Closure最后一步提交按钮submitAction()—步骤图标icon()✅完成态图标completedIcon()✅步骤描述description()✅默认起始步骤startOnStep()✅允许跳过/自由导航skippable()✅延迟加载步骤内容Schema::make()-deferLoading()✅URL 持久化当前步骤persistStepInQueryString($key step)✅步骤校验前后钩子beforeValidation()/afterValidation()回调可注入 utility阻止下一步回调内throw new Halt()—步骤内网格列数columns()✅定制上/下一步按钮previousAction()/nextAction()回调接收$action在实际项目中推荐将 Wizard 与资源创建页的HasWizardtrait 或 Action 模态框 组合使用以自动获得仅在最后一步可提交的完整交互再按需叠加skippable()、persistStepInQueryString()与deferLoading()来打磨长流程表单的体验与性能。【免费下载链接】filamentA powerful open-source UI framework for Laravel • Build and ship apps admin panels fast with Livewire项目地址: https://gitcode.com/GitHub_Trending/fi/filament创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
