自定义页面

#简介

Filament 允许你为应用创建完全自定义页面。

#创建页面

要创建新页面，你可以使用：

php artisan make:filament-page Settings

该命令将创建两个文件 —— Filament 目录的 /Pages 目录中的页面类，以及 Filament 视图目录 pages 目录下的视图。

页面类都是全页面 Livewire 组件，带有一些可以用在面板的额外 utility。

#授权

你可以通过重写 Page 类中的 canAccess() 方法来防止页面出现在菜单中。如果你想控制哪些用户可以在导航中看到页面，以及哪些用户可以直接访问页面，这很有用：

public static function canAccess(): bool
{
    return auth()->user()->canManageSettings();
}

#向页面中添加 Action

Action 是页面上执行任务或访问 URL 的按钮。你在此处可以了解更多详细信息。

因为所有页面都是 Livewire 组件，你可以在任何地方添加 Action。 页面已经已经为你设置了 InteractisWithActions trait、HasActions 接口和 <x-filament-actions::modals /> Blade 组件。

#Header Action

你还可以轻松地将操作添加到任何页面的标题中，包括资源页面。你无需担心向 Blade 模板添加任何内容，我们会为你处理。只需在页面类的 getHeaderActions() 方法中返回你的操作：

use Filament\Actions\Action;

protected function getHeaderActions(): array
{
    return [
        Action::make('edit')
            ->url(route('posts.edit', ['post' => $this->post])),
        Action::make('delete')
            ->requiresConfirmation()
            ->action(fn () => $this->post->delete()),
    ];
}

#页面加载时打开 Action 模态框

你也可以在页面加载时通过将 $defaultAction 属性设置为要打开的操作名来打开操作：

use Filament\Actions\Action;

public $defaultAction = 'onboarding';

public function onboardingAction(): Action
{
    return Action::make('onboarding')
        ->modalHeading('Welcome')
        ->visible(fn (): bool => ! auth()->user()->isOnBoarded());
}

使用 $defaultActionArguments 属性，你也可以将参数数组传入到默认 Action 中：

public $defaultActionArguments = ['step' => 2];

Alternatively, you can open an action modal when a page loads by specifying the action as a query string parameter to the page:

/admin/products/edit/932510?action=onboarding

#Refreshing form data

If you’re using actions on an Edit or View resource page, you can refresh data within the main form using the refreshFormData() method:

use App\Models\Post;
use Filament\Actions\Action;

Action::make('approve')
    ->action(function (Post $record) {
        $record->approve();

        $this->refreshFormData([
            'status',
        ]);
    })

This method accepts an array of model attributes that you wish to refresh in the form.

#Adding widgets to pages

Filament allows you to display widgets inside pages, below the header and above the footer.

To add a widget to a page, use the getHeaderWidgets() or getFooterWidgets() methods:

use App\Filament\Widgets\StatsOverviewWidget;

protected function getHeaderWidgets(): array
{
    return [
        StatsOverviewWidget::class
    ];
}

getHeaderWidgets() returns an array of widgets to display above the page content, whereas getFooterWidgets() are displayed below.

If you’d like to learn how to build and customize widgets, check out the Dashboard documentation section.

#Customizing the widgets’ grid

You may change how many grid columns are used to display widgets.

You may override the getHeaderWidgetsColumns() or getFooterWidgetsColumns() methods to return a number of grid columns to use:

public function getHeaderWidgetsColumns(): int | array
{
    return 3;
}

#Responsive widgets grid

You may wish to change the number of widget grid columns based on the responsive breakpoint of the browser. You can do this using an array that contains the number of columns that should be used at each breakpoint:

public function getHeaderWidgetsColumns(): int | array
{
    return [
        'md' => 4,
        'xl' => 5,
    ];
}

This pairs well with responsive widget widths.

#Passing data to widgets from the page

You may pass data to widgets from the page using the getWidgetsData() method:

public function getWidgetData(): array
{
    return [
        'stats' => [
            'total' => 100,
        ],
    ];
}

Now, you can define a corresponding public $stats array property on the widget class, which will be automatically filled:

public $stats = [];

#Passing properties to widgets on pages

When registering a widget on a page, you can use the make() method to pass an array of Livewire properties to it:

use App\Filament\Widgets\StatsOverviewWidget;

protected function getHeaderWidgets(): array
{
    return [
        StatsOverviewWidget::make([
            'status' => 'active',
        ]),
    ];
}

This array of properties gets mapped to public Livewire properties on the widget class:

use Filament\Widgets\Widget;

class StatsOverviewWidget extends Widget
{
    public string $status;

    // ...
}

Now, you can access the status in the widget class using $this->status.

#Customizing the page title

By default, Filament will automatically generate a title for your page based on its name. You may override this by defining a $title property on your page class:

protected static ?string $title = 'Custom Page Title';

Alternatively, you may return a string from the getTitle() method:

use Illuminate\Contracts\Support\Htmlable;

public function getTitle(): string | Htmlable
{
    return __('Custom Page Title');
}

#Customizing the page navigation label

By default, Filament will use the page’s title as its navigation item label. You may override this by defining a $navigationLabel property on your page class:

protected static ?string $navigationLabel = 'Custom Navigation Label';

Alternatively, you may return a string from the getNavigationLabel() method:

public static function getNavigationLabel(): string
{
    return __('Custom Navigation Label');
}

#Customizing the page URL

By default, Filament will automatically generate a URL (slug) for your page based on its name. You may override this by defining a $slug property on your page class:

protected static ?string $slug = 'custom-url-slug';

#Customizing the page heading

By default, Filament will use the page’s title as its heading. You may override this by defining a $heading property on your page class:

protected ?string $heading = 'Custom Page Heading';

Alternatively, you may return a string from the getHeading() method:

public function getHeading(): string
{
    return __('Custom Page Heading');
}

#Adding a page subheading

You may also add a subheading to your page by defining a $subheading property on your page class:

protected ?string $subheading = 'Custom Page Subheading';

Alternatively, you may return a string from the getSubheading() method:

public function getSubheading(): ?string
{
    return __('Custom Page Subheading');
}

#Replacing the page header with a custom view

You may replace the default heading, subheading and actions with a custom header view for any page. You may return it from the getHeader() method:

use Illuminate\Contracts\View\View;

public function getHeader(): ?View
{
    return view('filament.settings.custom-header');
}

This example assumes you have a Blade view at resources/views/filament/settings/custom-header.blade.php.

#Rendering a custom view in the footer of the page

You may also add a footer to any page, below its content. You may return it from the getFooter() method:

use Illuminate\Contracts\View\View;

public function getFooter(): ?View
{
    return view('filament.settings.custom-footer');
}

This example assumes you have a Blade view at resources/views/filament/settings/custom-footer.blade.php.

#Customizing the maximum content width

By default, Filament will restrict the width of the content on the page, so it doesn’t become too wide on large screens. To change this, you may override the getMaxContentWidth() method. Options correspond to Tailwind’s max-width scale. The options are ExtraSmall, Small, Medium, Large, ExtraLarge, TwoExtraLarge, ThreeExtraLarge, FourExtraLarge, FiveExtraLarge, SixExtraLarge, SevenExtraLarge, Full, MinContent, MaxContent, FitContent, Prose, ScreenSmall, ScreenMedium, ScreenLarge, ScreenExtraLarge and ScreenTwoExtraLarge. The default is SevenExtraLarge:

use Filament\Support\Enums\Width;

public function getMaxContentWidth(): Width
{
    return Width::Full;
}

#Generating URLs to pages

Filament provides getUrl() static method on page classes to generate URLs to them. Traditionally, you would need to construct the URL by hand or by using Laravel’s route() helper, but these methods depend on knowledge of the page’s slug or route naming conventions.

The getUrl() method, without any arguments, will generate a URL:

use App\Filament\Pages\Settings;

Settings::getUrl(); // /admin/settings

If your page uses URL / query parameters, you should use the argument:

use App\Filament\Pages\Settings;

Settings::getUrl(['section' => 'notifications']); // /admin/settings?section=notifications

#Generating URLs to pages in other panels

If you have multiple panels in your app, getUrl() will generate a URL within the current panel. You can also indicate which panel the page is associated with, by passing the panel ID to the panel argument:

use App\Filament\Pages\Settings;

Settings::getUrl(panel: 'marketing');

#Adding sub-navigation between pages

You may want to add a common sub-navigation to multiple pages, to allow users to quickly navigate between them. You can do this by defining a cluster. Clusters can also contain resources, and you can switch between multiple pages or resources within a cluster.

#Setting the sub-navigation position

The sub-navigation is rendered at the start of the page by default. You may change the position for a page by setting the $subNavigationPosition property on the page. The value may be SubNavigationPosition::Start, SubNavigationPosition::End, or SubNavigationPosition::Top to render the sub-navigation as tabs:

use Filament\Pages\Enums\SubNavigationPosition;

protected static ?SubNavigationPosition $subNavigationPosition = SubNavigationPosition::End;

#Adding extra attributes to the body tag of a page

You may wish to add extra attributes to the <body> tag of a page. To do this, you can set an array of attributes in $extraBodyAttributes:

protected array $extraBodyAttributes = [];

Or, you can return an array of attributes and their values from the getExtraBodyAttributes() method:

public function getExtraBodyAttributes(): array
{
    return [
        'class' => 'settings-page',
    ];
}

Edit on GitHub

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