Wizards

简介

类似于选项卡，你可能希望使用多步骤向导来减少一次可见的组件数量。如果你的表单具有明确的时间顺序，并且希望在用户操作过程中验证每个步骤，那么多步骤向导尤其有用。

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

如果你希望在面板资源或 Action 模态框中的创建过程中添加向导，我们提供了不同的设置说明。遵循对应文档将确保仅在向导的最后一步才允许提交表单。

在最后一步渲染提交按钮

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

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

除了允许静态值之外，icon() 方法也可以接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually <code>create</code>, <code>edit</code>, or <code>view</code>.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

自定义完成步骤的图标

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

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

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

除了允许静态值之外，completedIcon() 方法也可以接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually <code>create</code>, <code>edit</code>, or <code>view</code>.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

为步骤添加描述

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

use Filament\Schemas\Components\Wizard\Step;

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

除了允许静态值之外，description() 方法也可以接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually <code>create</code>, <code>edit</code>, or <code>view</code>.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

设置默认激活步骤

你可以使用 startOnStep() 方法，在向导中加载指定步骤：

use Filament\Schemas\Components\Wizard;

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

除了允许静态值之外，startOnStep() 方法也可以接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually <code>create</code>, <code>edit</code>, or <code>view</code>.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

允许跳过步骤

如果你想允许自由导航，让所有步骤都是可跳过的，请使用 skippable() 方法：

use Filament\Schemas\Components\Wizard;

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

或者，skippable() 方法接受布尔值来控制该步骤是否可跳过：

use Filament\Schemas\Components\Wizard\Step;

Step::make('Order')
    ->skippable(FeatureFlag::active())
    ->schema([
        // ...
    ]),

除了允许静态值之外，skippable() 方法也可以接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually <code>create</code>, <code>edit</code>, or <code>view</code>.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current 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')

除了允许静态值之外，persistStepInQueryString() 方法也可以接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually <code>create</code>, <code>edit</code>, or <code>view</code>.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

步骤生命周期钩子

你可以使用 afterValidation() 和 beforeValidation() 方法在步骤验证之前和之后运行代码：

use Filament\Schemas\Components\Wizard\Step;

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

你可以将各种 utility 作为参数注入到 afterValidation() 和 beforeValidation() 函数。

Learn more about utility injection.

Utility	Type	Parameter	Description
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually <code>create</code>, <code>edit</code>, or <code>view</code>.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

阻止加载下一步

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

除了允许静态值之外，columns() 方法也可以接受函数来动态计算其值。你可以将各种 utility 作为参数注入到函数中。

Learn more about utility injection.

Utility	Type	Parameter	Description
Component	Filament\Schemas\Components\Component	$component	The current component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current schema data. Validation is not run on form fields.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually <code>create</code>, <code>edit</code>, or <code>view</code>.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

自定义向导操作对象

此组件使用操作（Action）对象来轻松自定义其中的按钮。你可以通过将函数传递给 Action 注册方法来自定义这些按钮。该函数可以访问 $action 对象，你可以使用该对象来自定义。以下方法可用于自定义操作：

• nextAction()
• previousAction()

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

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

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

这些 Action 注册方法可以注入各种 utility 到函数中作为参数。

Learn more about utility injection.

Utility	Type	Parameter	Description
Action	Filament\Actions\Action	$action	The action object to customize.
Field	Filament\Forms\Components\Field	$component	The current field component instance.
Get function	Filament\Schemas\Components\Utilities\Get	$get	A function for retrieving values from the current form data. Validation is not run.
Livewire	Livewire\Component	$livewire	The Livewire component instance.
Eloquent model FQN	?string<Illuminate\Database\Eloquent\Model>	$model	The Eloquent model FQN for the current schema.
Operation	string	$operation	The current operation being performed by the schema. Usually <code>create</code>, <code>edit</code>, or <code>view</code>.
Raw state	mixed	$rawState	The current value of the field, before state casts were applied. Validation is not run.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.
State	mixed	$state	The current value of the field. Validation is not run.