自定义页面

引言

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

向页面添加操作

动作是可以在页面上执行任务或访问 URL 的按钮。您可以此处阅读更多关于它们的功能。

由于所有页面都是 Livewire 组件，您可以添加操作到任何位置。页面已经为您设置了InteractsWithActions trait、HasActions 接口，以及<x-filament-actions::modals /> Blade 组件。

首部操作

您还可以轻松地向任何页面的头部添加操作，包括资源页面。您无需担心向 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

刷新表单数据

如果你正在编辑或查看资源页面上使用操作，你可以使用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,
        ],
    ];
}

现在，你可以在 widget 类上定义一个对应的公共 $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;

    // ...
}

现在，你可以在 widget 类中，使用 $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');
}

本示例假设您有一个 Blade 视图，位于 resources/views/filament/settings/custom-header.blade.php.

在页面的页脚渲染一个自定义视图

您也可以为任何页面添加页脚，位于其内容下方。您可以从 getFooter() 方法返回它：

php

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 的最大宽度比例。可选选项包括 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。你还可以通过将面板 ID 传递给 panel 参数来指示页面关联的面板：

php

use App\Filament\Pages\Settings;

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

添加页面间的子导航

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

设置子导航位置

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

php

use Filament\Pages\Enums\SubNavigationPosition;

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

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

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

php

protected array $extraBodyAttributes = [];

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

php

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

引言

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

创建页面

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

bash

php artisan make:filament-page Settings

此命令将创建两个文件 - 一个页面类在 Filament 目录的 /Pages 目录中，以及一个视图在 Filament 视图目录的 /pages 目录中。

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

授权

php

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

向页面添加操作

动作是可以在页面上执行任务或访问 URL 的按钮。您可以此处阅读更多关于它们的功能。

首部操作

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

刷新表单数据

如果你正在编辑或查看资源页面上使用操作，你可以使用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,
        ],
    ];
}

现在，你可以在 widget 类上定义一个对应的公共 $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;

    // ...
}

现在，你可以在 widget 类中，使用 $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');
}

本示例假设您有一个 Blade 视图，位于 resources/views/filament/settings/custom-header.blade.php.

在页面的页脚渲染一个自定义视图

您也可以为任何页面添加页脚，位于其内容下方。您可以从 getFooter() 方法返回它：

php

use Illuminate\Contracts\View\View;

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

本例假设您有一个 Blade 视图位于 resources/views/filament/settings/custom-footer.blade.php。

自定义最大内容宽度

php

use Filament\Support\Enums\Width;

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

生成页面的 URL

该 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。你还可以通过将面板 ID 传递给 panel 参数来指示页面关联的面板：

php

use App\Filament\Pages\Settings;

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

添加页面间的子导航

设置子导航位置

php

use Filament\Pages\Enums\SubNavigationPosition;

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

向页面的 `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 标签添加额外属性

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

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