概述

#修改颜色

在配置中，你可以修改使用的颜色。Filament 自带 6 个在框架中使用的预制颜色。他们可以定义如下：

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 颜色数组的方式传入你自己的调色板：

$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 值为你生成调色板，你可以传入：

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

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

#修改字体

默认情况下，我们使用 Inter 字体。你可以在配置文件中使用 font()方法修改：

use Filament\Panel;

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

所有的 Google 字体都是可以使用的。

#修改字体提供者

Bunny Fonts CDN 用于提供字体。它符合 GDPR 标准。如果你想使用 Google Fonts CDN 替换，可以使用 font() 方法的 provider 参数进行修改：

use Filament\FontProviders\GoogleFontProvider;

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

或者如果你想在本地样式表中提供字体，你可以使用 LocalFontProvider：

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 命令：

php artisan make:filament-theme

如果你由多个面板，你可以指定你想要创建主题的面板：

php artisan make:filament-theme admin

默认情况下，该命令将使用 NPM 来安装依赖。如果你想使用不同的包管理器，可以使用 --pm 选项：

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

This command will:

1. Install the required Tailwind CSS dependencies
2. Generate a CSS file in resources/css/filament/{panel}/theme.css
3. Attempt to automatically add the theme to your vite.config.js input array
4. Attempt to automatically register ->viteTheme() in your panel provider
5. Offer to compile the theme with Vite

If the command cannot automatically configure your files (due to non-standard formatting), it will display manual instructions instead. In that case, follow these steps:

#Manual configuration

Add the theme’s CSS file to the Laravel plugin’s input array in vite.config.js:

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

Register the Vite-compiled theme CSS file in the panel’s provider:

use Filament\Panel;

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

Then compile the theme with Vite:

npm run build

You can now customize the theme by editing the CSS file in resources/css/filament.

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

If you want to use Tailwind CSS utility classes (like text-primary-600, bg-gray-100, p-4, etc.) in your own Blade views, Livewire components, or PHP files, you must create a custom theme first.

Without a custom theme, any Tailwind classes you add to your code will simply not work - the styles won’t be applied because they’re not included in the compiled CSS.

#Setting up Tailwind CSS for your project

要在项目中使用 Tailwind CSS 类，你需要设置自定义主题以在面板中自定义编译过的 CSS 文件。运行如下命令：

php artisan make:filament-theme

在生成的的 theme.css 文件中，你将看到这两行：

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

Add your own directories where you use Tailwind classes. For example:

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

After adding your directories, rebuild your theme:

npm run build

You can learn more about the @source directive in the Tailwind CSS documentation.

#Dark mode

By default, Filament allows users to switch between light and dark mode. The following sections cover how to customize this behavior.

#禁用暗黑模式

要禁用暗黑模式的切换，你可以在配置文件中设置：

use Filament\Panel;

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

#Hiding the theme switcher

By default, users can switch between light and dark mode using the theme switcher in the user menu. If you want to keep dark mode enabled but prevent users from manually switching (so that Filament follows the default theme mode or the user’s system preference), you can hide the theme switcher using the themeSwitcher(false) method:

use Filament\Panel;

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

#Forcing dark mode

If you want to force the panel to always use dark mode, regardless of the user’s preference, you can pass isForced: true to the darkMode() method. This also hides the theme switcher:

use Filament\Panel;

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

#修改默认主题模式

默认情况下，Filament 使用用户的系统主题作为默认模式。比如，如果用户电脑使用的是暗黑模式，Filament 将会默认使用暗黑模式。如果用户修改电脑中的模式，Filament 中的系统模式是响应式的。如果你想修改默认模式使之强制使用清亮模式或者暗黑模式，请使用 defaultThemeMode() 方法，并传入 ThemeMode::Light 或者 ThemeMode::Dark：

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

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

#添加图标

默认情况下，Filament 使用你的应用名渲染一个基于文本的简单 Logo。不过，你可以对其进行自定义。

如果你只想要修改 Logo 使用文本，你可以使用 brandName() 方法：

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->brandName('Filament Demo');
}

要替换成渲染图片，请传入 URL 到 brandLogo() 方法：

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->brandLogo(asset('images/logo.svg'));
}

此外，你可以直接传递 HTML 到 brandLogo() 方法，以渲染行内 SVG 元素：

use Filament\Panel;

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

<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 的高度：

use Filament\Panel;

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

#添加 favicon

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

use Filament\Panel;

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

#Making a panel more compact

Data-heavy panels can be easier to scan when tables and controls use less space. The Compact theme provides a ready-made option that reduces the spacing throughout a panel while preserving Filament’s default mobile spacing. It can also be combined with the Sharp, Soft, or Noir themes if you want to change the visual style as well as the density.

If you only need to make a few elements more compact, you can add targeted rules to your custom theme instead. For example, these rules reduce the vertical padding of table text cells and the padding of default-sized buttons on larger screens:

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

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

Using the sm breakpoint keeps Filament’s default spacing on smaller screens, where table rows are often presented as stacked content. You can target other elements in the same way using CSS hook classes.

Edit on GitHub

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