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

#在最后一步渲染提交按钮

你可以使用 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 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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;

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

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

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
Eloquent record	?Illuminate\Database\Eloquent\Model	$record	The Eloquent record for the current schema.

#Deferring the loading of step content

If the content of a wizard step is expensive to render, you can pass a Schema object to its schema() method and use deferLoading(). The content of the active step will be loaded when it enters the viewport. The content of a later step will not be loaded until the user reaches it:

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')

Every deferred schema must have a unique key. In this example, the keys on the steps are inherited by their child schemas, while the key on the Wizard component namespaces them from other steps in the same schema. You can learn more in the schema overview.

#将当前步骤持久化到 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 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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() 函数。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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 作为参数注入到函数中。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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 到函数中作为参数。

了解更多 utility 注入详情。

Utility	类型	参数	描述
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 create, edit, or view.
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.

Edit on GitHub

Still need help? Join our Discord community or open a GitHub discussion