自定义页面

#简介

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];

或者，你可以将 action 指定为页面的查询字符串参数来在页面加载时打开操作模态框：

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

#刷新表单数据

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

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

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

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

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

#向页面添加 Widget

Filament 允许你在页面内部（Header 下方和 Footer 上方）显示 Widget。

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

use App\Filament\Widgets\StatsOverviewWidget;

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

getHeaderWidgets() 返回一个 Widget 数组，用于显示在页面内容上方，而 getFooterWidgets() 则显示在下方。

如果你想了解如何构建和自定义 Widget，请查看 Dashboard 文档部分。

#自定义 Widget 网格

你可以更改用于显示 Widget 的网格列数。

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

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

#响应式 Widget 网格

你可能希望根据浏览器的响应式断点来更改 Widget 的网格列数。你可以使用一个数组来实现此目的，该数组包含每个断点应使用的列数：

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

这与响应式 Widget 宽度完美匹配。

#从页面向 Widget 传递数据

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

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

现在，你可以在 Widget 类上定义相应的公共 $stats 数组属性，它将被自动填充：

public $stats = [];

#将属性传递给页面上的 Widget

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

use App\Filament\Widgets\StatsOverviewWidget;

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

此属性数组映射到 Widget 类上的 公共 Livewire 属性：

use Filament\Widgets\Widget;

class StatsOverviewWidget extends Widget
{
    public string $status;

    // ...
}

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

#自定义页面标题

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

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

或者，你可以在 getTitle() 方法返回一个字符串：

use Illuminate\Contracts\Support\Htmlable;

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

#自定义页面导航标签

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

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

或者，你可以在 getNavigationLabel() 方法中返回一个字符串：

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

#自定义页面 URL

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

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

#自定义页面标题

默认情况下，Filament 会使用页面的标题(title)作为标题(Heading)。你可以在页面类中定义 $heading 属性来覆盖此设置：

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

或者，你可以在 getHeading() 方法中返回一个字符串：

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

#添加页面副标题

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

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

或者，你可以在 getSubheading() 方法中返回一个字符串：

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

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

你可以将任何页面的默认 heading、副标题 和 Action 替换为自定义的 header 视图。你可以通过 getHeader() 方法返回它：

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

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

#最定义最大内容宽度

默认情况下，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：

use Filament\Support\Enums\Width;

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

#生成页面 URL

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

getUrl() 方法不带任何参数，即可生成 URL：

use App\Filament\Pages\Settings;

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

如果你的页面使用 URL / 查询参数，则应使用以下参数：

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

#添加页面之间的子导航

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

#设置子导航的位置

子导航默认渲染在页面的开头。你可以通过设置页面上的 $subNavigationPosition 属性来更改页面的位置。该值可以是 SubNavigationPosition::Start、SubNavigationPosition::End 或 SubNavigationPosition::Top，以将子导航渲染为选项卡：

use Filament\Pages\Enums\SubNavigationPosition;

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

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

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

protected array $extraBodyAttributes = [];

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

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

Edit on GitHub

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