页面

#概述

Filament 允许你创建完全自定义的页面。

#新建页面

要创建新页面，你可以使用下面的命令：

php artisan make:filament-page Settings
php artisan make:filament-page Settings

该命令会生成两个文件 - 一个位于Filament目录的 /Pages 文件夹中的页面类，以及一个位于 Filament 视图目录的 /pages 文件夹中的视图文件。

页面类是全页 Livewire 组件，带有一些你可以在面板中使用的额外功能。

#授权

通过重写页面类的 canAccess 方法，你可以阻止页面出现在菜单中。当你想在导航中控制哪些用户可以看到该页面以及哪些用户可以直接访问该页面时，这非常有用：

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

#将 Action 添加到页面

Action 是可以在页面中执行任务或者访问 URL 的按钮。你可以点击此处查阅更多的内容。

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

#头部 Action

你也可以轻松地在任何页面的头部添加 Action，包括资源页面。你不需要操心添加任何内容到 Blade 模板，我们已经帮你处理了。只需在页面类的 getHeaderActions() 方法中返回 Action：

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()),
    ];
}
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 属性设置为你想要打开的 Action 名，你可以在页面加载时打开 Action：

use Filament\Actions\Action;
 
public $defaultAction = 'onboarding';
 
public function onboardingAction(): Action
{
    return Action::make('onboarding')
        ->modalHeading('Welcome')
        ->visible(fn (): bool => ! auth()->user()->isOnBoarded());
}
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];
public $defaultActionArguments = ['step' => 2];

此外，通过将 action 作为查询参数指定给页面，你可以在页面加载时打开 Action 模态框：

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

#刷新表单数据

如果要在资源的编辑页或查看页中使用 Action，你可以使用 refreshFormData() 方法在主表单中刷新数据：

use App\Models\Post;
use Filament\Actions\Action;
 
Action::make('approve')
    ->action(function (Post $record) {
        $record->approve();
 
        $this->refreshFormData([
            'status',
        ]);
    })
use App\Models\Post;
use Filament\Actions\Action;

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

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

该方法接收一个你希望在表单中刷新的模型属性数组。

#添加 Widget 到页面

Filament 允许你在页面内的 header 之下及 footer 之上展示 widgets。 i

使用 getHeaderWidgets() 或 getFooterWidgets()，可以添加 Widget 到页面：

use App\Filament\Widgets\StatsOverviewWidget;
 
protected function getHeaderWidgets(): array
{
    return [
        StatsOverviewWidget::class
    ];
}
use App\Filament\Widgets\StatsOverviewWidget;

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

getHeaderWidgets 方法返回显示在页面内容上面的 Widget 数组，getFooterWidgets() 方法则显示下面的。

关于如何创建自定义插件，查看仪表盘文档。

#自定义 Widget 网格

你可以修改插件占用的网格数。

重写 getHeaderWidgetsColumns() 或者 getFooterWidgetsColumns()，使之返回代表网格宽度的数字：

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

#响应式 Widget 网格

你可能希望根据浏览器的响应式临界点，调整插件占用的网格数。返回类似如下数组：

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

这一功能和响应式插件宽度搭配使用。

#从页面中传递数据到 Widget

你可以使用 getWidgetsData() 方法，从页面中传递数据给 Widget：

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

现在，你可以在 Widget 类中定义相应的 public $stats 数组属性，它会被自动填充：

public $stats = [];
public $stats = [];

#传递属性给页面上的 Widget

当在页面上注册 Widget 时，你可以使用 make() 方法，并传递 Livewire 属性数组给它：

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

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

该属性数组被映射到 Widget 类上中的 public Livewire 属性：

use Filament\Widgets\Widget;
 
class StatsOverviewWidget extends Widget
{
    public string $status;
 
    // ...
}
use Filament\Widgets\Widget;

class StatsOverviewWidget extends Widget
{
    public string $status;

    // ...
}

现在，你可以使用 $this->status 访问 Widget 类中 status。

#自定义页面标题

默认情况下，Filament 会基于它的名字为你的页面自动生成标题。你也可以在页面类中重写定义 $title 属性：

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

另外，你也可以在 getTitle() 方法中返回一个字符串：

use Illuminate\Contracts\Support\Htmlable;
 
public function getTitle(): string | Htmlable
{
    return __('Custom Page Title');
}
use Illuminate\Contracts\Support\Htmlable;

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

#自定义页面导航标签

默认情况下，Filament 使用页面的 title 作为其导航项标签。你可以在页面类中定义 $navigationLabel 属性重写：

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

另外，你也可以在 getNavigationLabel() 方法中返回一个字符串实现：

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

#自定义页面 URL

默认情况下，Filament 会为基于页面的名称为页面生成 URL(slug)。你可以在页面类中定义 $slug 属性进行重写：

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

#自定义页首标题

默认情况下，Filament 会使用页面的 title 作为页面的 heading。你可以在页面类中定义 heading 属性来重写：

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

此外，你也可以在 getHeading() 方法中返回字符串来实现：

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

#添加页面子标题

你也可以在页面类中定义 #subheading 属性为页面添加子标题：

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

另外，你也可以在 getSubheading() 方法中返回字符串来实现该功能：

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

#使用自定义视图替换页面 Header

你可以使用自定义 Header 视图为任何页面替换默认的 heading、subheading 和 actions。你可以在 getHeader() 方法中返回该视图：

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

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

本例假定你有一个 Blade 模板视图位于 resources/views/filament/settings/custom-header.blade.php。

#在页面的底部(footer)中渲染自定义视图

你可以在页面内容的下方将添加 footer 到任何页面中。在 getFooter() 方法中返回视图：

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

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

本例假定你有一个 Blade 模板视图位于 resources/views/filament/settings/custom-footer.blade.php。

#自定义最大内容宽度

默认情况下，Filament 会在页面中限制内容的宽度，这样在大屏幕中才不会变动过宽。你可以重写 getContentMaxWidth() 方法来修改它。选项对应于 Tailwind 的 max-width 尺度。选项值包括 ExtraSmall、Small、Medium、Large、ExtraLarge、TwoExtraLarge、ThreeExtraLarge、FourExtraLarge、FiveExtraLarge、SixExtraLarge、SevenExtraLarge、Full、MinContent、MaxContent、FitContent、Prose、ScreenSmall、ScreenMedium、ScreenLarge、ScreenExtraLarge 及 ScreenTwoExtraLarge。默认值为 SevenExtraLarge。

use Filament\Support\Enums\MaxWidth;
 
public function getMaxContentWidth(): MaxWidth
{
    return MaxWidth::Full;
}
use Filament\Support\Enums\MaxWidth;

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

#为页面生成 URL

Filament 在页面类中提供了 getUrl() 静态方法，用以为其生成 URL。传统上，你需要使用 Laravel 的 route() 辅助函数手动生成 URL，不过这些方法取决于对页面 slug 或路由命名规范的认知。

getUrl() 方法，不带任何参数将会生成一个 URL：

use App\Filament\Pages\Settings;
 
Settings::getUrl(); // /admin/settings
use App\Filament\Pages\Settings;

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

如果你的页面使用 URL/查询参数，你应该使用这些参数：

use App\Filament\Pages\Settings;
 
Settings::getUrl(['section' => 'notifications']); // /admin/settings?section=notifications
use App\Filament\Pages\Settings;

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

#生成其他面板页面的 URL

如果你的应用中有多个面板，getUrl 会在当前面板中生成 URL。你也可以传入面板 ID 到 panel 参数，说明页面关联的面板：

use App\Filament\Pages\Settings;
 
Settings::getUrl(panel: 'marketing');
use App\Filament\Pages\Settings;

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

#在页面之间添加子导航

你可能希望向多个页面添加一个通用的子导航，以允许用户在它们之间快速导航。你可以通过定义 Cluster 来实现这一点。Cluster 也可以包含资源，并且可以在 Cluster 内的多个页面或资源之间切换。

#在页面的 body 标签上添加额外属性

你可能想添加额外属性到页面的 <body> 标签中。可以在 $extraBodyAttributes 中设置属性数组，实现该功能。

protected array $extraBodyAttributes = [];
protected array $extraBodyAttributes = [];

或者，可以在 getExtraBodyAttributes() 方法中返回属性数组：

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

Edit on GitHub

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