Filament 中文文档

主题

全部文档

概述 ​

更改颜色 ​

在配置中，你可以轻松更改所用颜色。Filament 附带 6 种在框架各处使用的预定义颜色，可按如下方式自定义：

php
use Filament\Panel;
use Filament\Support\Colors\Color;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->colors([
            'danger' => Color::Rose,
            'gray' => Color::Gray,
            'info' => Color::Blue,
            'primary' => Color::Indigo,
            'success' => Color::Emerald,
            'warning' => Color::Orange,
        ]);
}

Filament\Support\Colors\Color 类包含全部 Tailwind CSS 调色板 的颜色选项。

使用自定义颜色的面板使用自定义颜色的面板

也可以向 register() 传入一个函数，该函数仅在应用渲染时才会被调用。若你从服务提供者中调用 register()，又想访问当前认证用户等稍后在中间件中才初始化的对象，这会很有用。

或者，你也可以传入自己的 OKLCH 颜色数组作为调色板：

php
$panel
    ->colors([
        'primary' => [
            50 => 'oklch(0.969 0.015 12.422)',
            100 => 'oklch(0.941 0.03 12.58)',
            200 => 'oklch(0.892 0.058 10.001)',
            300 => 'oklch(0.81 0.117 11.638)',
            400 => 'oklch(0.712 0.194 13.428)',
            500 => 'oklch(0.645 0.246 16.439)',
            600 => 'oklch(0.586 0.253 17.585)',
            700 => 'oklch(0.514 0.222 16.935)',
            800 => 'oklch(0.455 0.188 13.697)',
            900 => 'oklch(0.41 0.159 10.272)',
            950 => 'oklch(0.271 0.105 12.094)',
        ],
    ])

生成调色板 ​

若希望我们根据单个十六进制或 RGB 值尝试生成调色板，可以直接传入该值：

php
$panel
    ->colors([
        'primary' => '#6366f1',
    ])

$panel
    ->colors([
        'primary' => 'rgb(99, 102, 241)',
    ])

更改字体 ​

默认使用 Inter 字体。你可以在配置文件中使用 font() 方法更改：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->font('Poppins');
}

所有 Google Fonts 都可使用。

使用自定义字体的面板使用自定义字体的面板

更改字体提供者 ​

字体由 Bunny Fonts CDN 提供，符合 GDPR。若想改用 Google Fonts CDN，可通过 font() 方法的 provider 参数实现：

php
use Filament\FontProviders\GoogleFontProvider;

$panel->font('Inter', provider: GoogleFontProvider::class)

或者，若希望从本地样式表提供字体，可以使用 LocalFontProvider：

php
use Filament\FontProviders\LocalFontProvider;

$panel->font(
    'Inter',
    url: asset('css/fonts.css'),
    provider: LocalFontProvider::class,
)

创建自定义主题 ​

Filament 允许你编译自定义样式表以替换默认样式表，从而更改用于渲染 UI 的 CSS。这种自定义样式表称为「主题」。主题使用 Tailwind CSS。

要为面板创建自定义主题，可以使用 php artisan make:filament-theme 命令：

bash
php artisan make:filament-theme

若有多个面板，可以指定要为其创建主题的面板：

bash
php artisan make:filament-theme admin

默认情况下，该命令会使用 NPM 安装依赖。若想使用其他包管理器，可以使用 --pm 选项：

bash
php artisan make:filament-theme --pm=bun

该命令将会：

  1. 安装所需的 Tailwind CSS 依赖
  2. 在 `resources/css/filament/{panel}/theme.css` 生成 CSS 文件
  3. 尝试自动把主题加入 `vite.config.js` 的 `input` 数组
  4. 尝试在面板提供者中自动注册 `->viteTheme()`
  5. 询问是否用 Vite 编译主题

若命令无法自动配置你的文件（因格式非标准），则会改为显示手动说明。此时请按以下步骤操作：

手动配置 ​

将主题的 CSS 文件加入 vite.config.js 中 Laravel 插件的 input 数组：

js
input: [
    // ...
    'resources/css/filament/admin/theme.css',
]

在面板的提供者中注册由 Vite 编译的主题 CSS 文件：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->viteTheme('resources/css/filament/admin/theme.css');
}

然后用 Vite 编译主题：

bash
npm run build

INFO

请查看命令输出中的确切文件路径（例如 admin/theme.css），它可能因面板 ID 而异。

现在可以通过编辑 resources/css/filament 中的 CSS 文件来自定义主题。

在 Blade 视图或 PHP 文件中使用 Tailwind CSS 类 ​

WARNING

要在自己的代码中使用 Tailwind CSS 类，必须创建自定义主题。 Filament 默认编译的样式表不包含任意 Tailwind 类——它只包含 Filament 自身 UI 组件所需的样式。

若要在自己的 Blade 视图、Livewire 组件或 PHP 文件中使用 Tailwind CSS 工具类（如 text-primary-600、bg-gray-100、p-4 等），必须先创建自定义主题。

没有自定义主题时，你添加到代码中的任何 Tailwind 类都不会生效——样式不会被应用，因为它们不包含在已编译的 CSS 中。

为项目设置 Tailwind CSS ​

要在项目中使用 Tailwind CSS 类，需要设置自定义主题。运行以下命令：

bash
php artisan make:filament-theme

在生成的 theme.css 文件中，你会看到告诉 Tailwind CSS 在何处扫描类的 @source 指令：

css
@source '../../../../app/Filament/**/*';
@source '../../../../resources/views/filament/**/*';

添加你自己使用 Tailwind 类的目录。例如：

css
@source '../../../../app/Filament/**/*';
@source '../../../../resources/views/filament/**/*';
@source '../../../../resources/views/components/**/*';
@source '../../../../resources/views/livewire/**/*';
@source '../../../../app/Livewire/**/*';

添加目录后，重新构建主题：

bash
npm run build

可在 Tailwind CSS 文档中了解更多关于 @source 指令的信息。

深色模式 ​

默认情况下，Filament 允许用户在浅色与深色模式之间切换。以下各节介绍如何自定义此行为。

禁用深色模式 ​

要完全禁用深色模式，可以使用配置文件：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->darkMode(false);
}

隐藏主题切换器 ​

默认情况下，用户可通过用户菜单中的主题切换器在浅色与深色模式之间切换。若希望保持深色模式可用，但阻止用户手动切换（以便 Filament 遵循默认主题模式或用户的系统偏好），可使用 themeSwitcher(false) 方法隐藏主题切换器：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->themeSwitcher(false);
}

INFO

这与完全禁用深色模式的 darkMode(false) 不同。themeSwitcher(false) 会保持深色模式可用，但隐藏切换器。

强制深色模式 ​

若希望强制面板始终使用深色模式，而不管用户偏好，可以向 darkMode() 方法传入 isForced: true。这也会隐藏主题切换器：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->darkMode(isForced: true);
}

更改默认主题模式 ​

默认情况下，Filament 使用用户的系统主题作为默认模式。例如，若用户的电脑处于深色模式，Filament 默认也会使用深色模式。Filament 中的系统模式会在用户更改电脑模式时响应。若要更改默认模式以强制浅色或深色，可以使用 defaultThemeMode() 方法，传入 ThemeMode::Light 或 ThemeMode::Dark：

php
use Filament\Enums\ThemeMode;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->defaultThemeMode(ThemeMode::Light);
}

默认情况下，Filament 使用应用名称渲染简单的文本 Logo。不过你可以轻松自定义。

若只想更改 Logo 中使用的文本，可以使用 brandName() 方法：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->brandName('Filament Demo');
}
使用自定义品牌名称的面板使用自定义品牌名称的面板

若要改为渲染图片，可以向 brandLogo() 方法传入 URL：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->brandLogo(asset('images/logo.svg'));
}
使用自定义品牌 Logo 的面板使用自定义品牌 Logo 的面板

或者，也可以直接向 brandLogo() 方法传入 HTML，例如渲染内联 SVG 元素：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->brandLogo(fn () => view('filament.admin.logo'));
}
blade
<svg
    viewBox="0 0 128 26"
    xmlns="http://www.w3.org/2000/svg"
    class="h-full fill-gray-500 dark:fill-gray-400"
>
    <!-- ... -->
</svg>

若需要在应用处于深色模式时使用不同的 Logo，可以用同样的方式传给 darkModeBrandLogo()。

Logo 高度默认为一个合理值，但无法兼顾所有宽高比。因此，你可以使用 brandLogoHeight() 方法自定义渲染 Logo 的高度：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->brandLogo(fn () => view('filament.admin.logo'))
        ->brandLogoHeight('2rem');
}

添加 favicon ​

要添加 favicon，可以使用配置文件，传入 favicon 的公开 URL：

php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->favicon(asset('images/favicon.png'));
}

让面板更紧凑 ​

数据量大的面板在表格和控件占用更少空间时更易扫读。Compact 主题 提供现成方案，可减少整个面板的间距，同时保留 Filament 默认的移动端间距。若还想改变视觉风格与密度，也可以与 Sharp、Soft 或 Noir 主题组合使用。

若只需让少数元素更紧凑，可以向自定义主题添加针对性规则。例如，以下规则会在较大屏幕上减少表格文本单元格的垂直内边距，以及默认尺寸按钮的内边距：

css
.fi-ta-text:not(.fi-inline) {
    @apply sm:py-2;
}

.fi-btn {
    @apply sm:px-2.5 sm:py-1.5;
}

使用 sm 断点可在较小屏幕上保留 Filament 的默认间距，因为表格行在这些屏幕上通常以堆叠内容呈现。你可以用同样的方式通过 CSS hook 类 定位其他元素。