自定义页面

简介

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

创建页面

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

bash

php artisan make:filament-page Settings

该命令会创建两个文件：一个页面类位于 Filament 目录下的 /Pages，一个视图位于 Filament 视图目录下的 /pages。

页面类都是整页 Livewire 组件，并附带一些可与面板一起使用的额外工具。

授权

可通过在 Page 类中重写 canAccess() 方法，阻止页面出现在菜单中。适用于控制哪些用户能在导航中看到该页面，以及哪些用户能直接访问该页面：

php

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

向页面添加操作

操作（Actions）是可在页面上执行任务或访问 URL 的按钮。可在此处了解更多能力。

由于所有页面都是 Livewire 组件，你可以在任意位置添加操作。页面已为你配置好 InteractsWithActions trait、HasActions 接口以及 <x-filament-actions::modals /> Blade 组件。

页头操作

你也可以轻松地向任意页面（包括 resource 页面）的页头添加操作。无需在 Blade 模板中添加内容，我们会替你处理。只需在页面类的 getHeaderActions() 方法中返回操作即可：

php

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()),
    ];
}

对齐页头操作

默认情况下，页头操作在移动端左对齐。要更改移动端页头操作的对齐方式，请设置 $headerActionsAlignment：

php

use Filament\Support\Enums\Alignment;

protected ?Alignment $headerActionsAlignment = Alignment::End;

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

php

use Filament\Actions\Action;

public $defaultAction = 'onboarding';

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

也可使用 $defaultActionArguments 属性向默认操作传递参数数组：

php

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

或者，可通过在页面查询字符串中指定 action 参数，在页面加载时打开操作模态框：

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

刷新表单数据

若在 Edit 或 View resource 页面上使用操作，可用 refreshFormData() 方法刷新主表单中的数据：

php

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

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

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

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

向页面添加小部件

Filament 允许你在页面中显示小部件，位于页头下方、页脚上方。

要向页面添加小部件，请使用 getHeaderWidgets() 或 getFooterWidgets() 方法：

php

use App\Filament\Widgets\StatsOverviewWidget;

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

getHeaderWidgets() 返回显示在页面内容上方的小部件数组，而 getFooterWidgets() 显示在下方。

若想了解如何构建与自定义小部件，请参阅小部件文档。

自定义小部件网格

你可以更改用于显示小部件的网格列数。

可重写 getHeaderWidgetsColumns() 或 getFooterWidgetsColumns() 方法以返回要使用的网格列数：

php

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

响应式小部件网格

你可能希望根据浏览器的响应式断点更改小部件网格列数。可用包含各断点应使用列数的数组实现：

php

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

这与响应式小部件宽度搭配使用效果很好。

从页面向小部件传递数据

可使用 getWidgetData() 方法从页面向小部件传递数据：

php

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

现在可在小部件类上定义对应的公共 $stats 数组属性，它会被自动填充：

php

public $stats = [];

向页面上的小部件传递属性

在页面上注册小部件时，可使用 make() 方法向其传递 Livewire 属性数组：

php

use App\Filament\Widgets\StatsOverviewWidget;

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

该属性数组会映射到小部件类上的公共 Livewire 属性：

php

use Filament\Widgets\Widget;

class StatsOverviewWidget extends Widget
{
    public string $status;

    // ...
}

现在可在小部件类中通过 $this->status 访问 status。

自定义页面标题

默认情况下，Filament 会根据页面名称自动生成标题。可在页面类上定义 $title 属性以覆盖：

php

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

或者，可从 getTitle() 方法返回字符串：

php

use Illuminate\Contracts\Support\Htmlable;

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

默认情况下，Filament 会使用页面的标题作为其导航项标签。可在页面类上定义 $navigationLabel 属性以覆盖：

php

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

或者，可从 getNavigationLabel() 方法返回字符串：

php

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

自定义页面 URL

默认情况下，Filament 会根据页面名称自动生成 URL（slug）。可在页面类上定义 $slug 属性以覆盖：

php

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

自定义页面标题文字

默认情况下，Filament 会使用页面的标题作为页头标题。可在页面类上定义 $heading 属性以覆盖：

php

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

或者，可从 getHeading() 方法返回字符串：

php

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

添加页面副标题

也可通过在页面类上定义 $subheading 属性添加副标题：

php

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

或者，可从 getSubheading() 方法返回字符串：

php

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

你可用自定义页头视图替换任意页面的默认标题、副标题与操作。可从 getHeader() 方法返回：

php

use Illuminate\Contracts\View\View;

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

此示例假定你在 resources/views/filament/settings/custom-header.blade.php 有一个 Blade 视图。

也可为任意页面在内容下方添加页脚。可从 getFooter() 方法返回：

php

use Illuminate\Contracts\View\View;

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

此示例假定你在 resources/views/filament/settings/custom-footer.blade.php 有一个 Blade 视图。

自定义最大内容宽度

默认情况下，Filament 会限制页面内容宽度，以免在大屏上过宽。要更改此设置，可重写 getMaxContentWidth() 方法。选项对应 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：

php

use Filament\Support\Enums\Width;

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

生成指向页面的 URL

Filament 在页面类上提供静态方法 getUrl() 以生成指向它们的 URL。传统上你需要手动拼 URL 或使用 Laravel 的 route() 辅助函数，但这些方法依赖对页面 slug 或路由命名约定的了解。

不带任何参数的 getUrl() 方法会生成 URL：

php

use App\Filament\Pages\Settings;

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

若页面使用 URL / 查询参数，应使用参数：

php

use App\Filament\Pages\Settings;

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

生成指向其他面板中页面的 URL

若应用中有多个面板，getUrl() 会在当前面板内生成 URL。也可通过向 panel 参数传入面板 ID，指明页面对应的面板：

php

use App\Filament\Pages\Settings;

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

你可能希望为多个页面添加共用子导航，以便用户在它们之间快速切换。可通过定义 cluster 实现。Clusters 也可包含 resources，并可在 cluster 内的多个页面或 resources 之间切换。

默认情况下，子导航渲染在页面起始侧。可通过在页面上设置 $subNavigationPosition 属性更改位置。取值可为 SubNavigationPosition::Start、SubNavigationPosition::End，或用 SubNavigationPosition::Top 将子导航渲染为标签页：

php

use Filament\Pages\Enums\SubNavigationPosition;

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

SubNavigationPosition::Top 选项会将子导航渲染为页面内容上方的标签页：

向页面的 body 标签添加额外属性

你可能希望向页面的 <body> 标签添加额外属性。为此，可在 $extraBodyAttributes 中设置属性数组：

php

protected array $extraBodyAttributes = [];

或者，可从 getExtraBodyAttributes() 方法返回属性及其值的数组：

php

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

自定义页面

简介

创建页面

授权

向页面添加操作

页头操作

对齐页头操作

刷新表单数据

向页面添加小部件

自定义小部件网格

响应式小部件网格

从页面向小部件传递数据

向页面上的小部件传递属性

自定义页面标题

自定义页面导航标签

自定义页面 URL

自定义页面标题文字

添加页面副标题

用自定义视图替换页头

在页面页脚渲染自定义视图

自定义最大内容宽度

生成指向页面的 URL

生成指向其他面板中页面的 URL

在页面之间添加子导航

设置子导航位置

向页面的 body 标签添加额外属性

自定义页面 ​

简介 ​

创建页面 ​

授权 ​

向页面添加操作 ​

页头操作 ​

对齐页头操作 ​

页面加载时打开操作模态框 ​

刷新表单数据 ​

向页面添加小部件 ​

自定义小部件网格 ​

响应式小部件网格 ​

从页面向小部件传递数据 ​

向页面上的小部件传递属性 ​

自定义页面标题 ​

自定义页面导航标签 ​

自定义页面 URL ​

自定义页面标题文字 ​

添加页面副标题 ​

用自定义视图替换页头 ​

在页面页脚渲染自定义视图 ​

自定义最大内容宽度 ​

生成指向页面的 URL ​

生成指向其他面板中页面的 URL ​

在页面之间添加子导航 ​

设置子导航位置 ​

向页面的 body 标签添加额外属性 ​

自定义页面

简介

创建页面

授权

向页面添加操作

页头操作

对齐页头操作

页面加载时打开操作模态框

刷新表单数据

向页面添加小部件

自定义小部件网格

响应式小部件网格

从页面向小部件传递数据

向页面上的小部件传递属性

自定义页面标题

自定义页面导航标签

自定义页面 URL

自定义页面标题文字

添加页面副标题

用自定义视图替换页头

在页面页脚渲染自定义视图

自定义最大内容宽度

生成指向页面的 URL

生成指向其他面板中页面的 URL

在页面之间添加子导航

设置子导航位置

向页面的 body 标签添加额外属性