向导

简介

与 选项卡 类似，你可能希望使用多步向导来减少一次可见的组件数量。若表单有明确的时间顺序，并希望用户推进时逐步校验，则尤其有用。

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([
            // ...
        ]),
])

TIP

若要在 面板资源 的创建流程或 操作模态框 中添加向导，另有不同设置说明。按该文档操作可确保仅在向导最后一步才能提交表单。

在最后一步渲染提交按钮

可使用 submitAction() 方法在向导末尾（最后一步）渲染提交按钮 HTML 或视图。这比始终在向导下方显示提交按钮能提供更清晰的 UX：

use Filament\Schemas\Components\Wizard;
use Illuminate\Support\HtmlString;

Wizard::make([
    // ...
])->submitAction(view('order-form.submit-button'))

Wizard::make([
    // ...
])->submitAction(new HtmlString('<button type="submit">Submit</button>'))

或者，可使用内置的 Filament 按钮 Blade 组件：

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
        type="submit"
        size="sm"
    >
        Submit
    </x-filament::button>
BLADE)))

若愿意，也可将该组件提取到单独的 Blade 视图。

设置步骤图标

步骤可有 图标，可使用 icon() 方法设置：

use Filament\Schemas\Components\Wizard\Step;
use Filament\Support\Icons\Heroicon;

Step::make('Order')
    ->icon(Heroicon::ShoppingBag)
    ->schema([
        // ...
    ]),

TIP

除了接受静态值外，icon() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

自定义已完成步骤的图标

可使用 completedIcon() 方法自定义已完成步骤的 图标：

use Filament\Schemas\Components\Wizard\Step;
use Filament\Support\Icons\Heroicon;

Step::make('Order')
    ->completedIcon(Heroicon::HandThumbUp)
    ->schema([
        // ...
    ]),

TIP

除了接受静态值外，completedIcon() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

为步骤添加描述

可使用 description() 方法在每个步骤标题后添加简短描述：

use Filament\Schemas\Components\Wizard\Step;

Step::make('Order')
    ->description('Review your basket')
    ->schema([
        // ...
    ]),

TIP

除了接受静态值外，description() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

设置默认活动步骤

可使用 startOnStep() 方法加载向导中的特定步骤：

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->startOnStep(2)

TIP

除了接受静态值外，startOnStep() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

允许跳过步骤

若希望允许自由导航（所有步骤都可跳过），请使用 skippable() 方法：

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->skippable()

skippable() 方法也可接受布尔值，以控制步骤是否可跳过：

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->skippable(FeatureFlag::active())

TIP

除了接受静态值外，skippable() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

延迟加载步骤内容

若向导步骤内容渲染成本较高，可向其 schema() 方法传入 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 则将其与同一 schema 中的其他步骤命名空间隔离。更多信息见 schema 概览。

在 URL 查询字符串中持久化当前步骤

默认情况下，当前步骤不会持久化到 URL 的查询字符串中。可使用 persistStepInQueryString() 方法更改此行为：

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->persistStepInQueryString()

启用后，当前步骤会使用 step 键持久化到 URL 查询字符串中。可通过向 persistStepInQueryString() 方法传入键名来更改：

use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])->persistStepInQueryString('wizard-step')

TIP

除了接受静态值外，persistStepInQueryString() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

步骤生命周期钩子

可使用 afterValidation() 与 beforeValidation() 方法在步骤校验前后运行代码：

use Filament\Schemas\Components\Wizard\Step;

Step::make('Order')
    ->afterValidation(function () {
        // ...
    })
    ->beforeValidation(function () {
        // ...
    })
    ->schema([
        // ...
    ]),

TIP

可将各种工具作为参数注入 afterValidation() 与 beforeValidation() 函数。

阻止加载下一步

在 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([
        // ...
    ]),

在步骤中使用网格列

可使用 columns() 方法自定义步骤内的 网格：

use Filament\Schemas\Components\Wizard;
use Filament\Schemas\Components\Wizard\Step;

Wizard::make([
    Step::make('Order')
        ->columns(2)
        ->schema([
            // ...
        ]),
    // ...
])

TIP

除了接受静态值外，columns() 方法也接受函数以动态计算。你可以将各种工具作为参数注入该函数。

自定义向导操作对象

该组件使用操作对象以便轻松自定义其中的按钮。可通过向操作注册方法传入函数来自定义这些按钮。函数可访问 $action 对象，用于 自定义它。可用于自定义操作的方法如下：

• nextAction()
• previousAction()

以下是自定义操作的示例：

use Filament\Actions\Action;
use Filament\Schemas\Components\Wizard;

Wizard::make([
    // ...
])
    ->nextAction(
        fn (Action $action) => $action->label('Next step'),
    )

TIP

操作注册方法可将各种工具作为参数注入该函数。