Filament 中文文档

主题

全部文档

安装 ​

运行 Filament 需要：

  • PHP 8.2+
  • Laravel v11.28+
  • Tailwind CSS v4.1+

安装有两种方式，取决于你是要用面板构建器做应用，还是在 Blade 视图中使用组件：

面板构建器 ​

多数人选择此方式为应用构建面板（如管理后台）。面板构建器把各个组件组合成统一框架。同一 Laravel 安装中可创建任意数量面板，但只需安装一次。

独立组件 ​

若用 Blade 从零搭建应用，可安装 Filament 的独立组件来丰富 UI。

安装面板构建器 ​

在 Laravel 项目目录运行以下命令安装 Filament 面板构建器：

bash
composer require filament/filament:"^5.0"

php artisan filament:install --panels

WARNING

若用 Windows PowerShell 安装 Filament，可能需要运行下面的命令，因为它会忽略版本约束中的 ^：

bash
composer require filament/filament:"~5.0"

php artisan filament:install --panels

这会创建并注册名为 app/Providers/Filament/AdminPanelProvider.php 的 Laravel 服务提供者。

TIP

若访问面板时报错，请检查服务提供者是否已在 bootstrap/providers.php 注册。若未注册，需手动添加。

可用以下命令创建新用户：

bash
php artisan make:filament-user

在浏览器打开 /admin，登录后即可开始构建应用！

安装独立组件 ​

用 Composer 安装要用的 Filament 组件：

bash
composer require
    filament/tables:"^5.0"
    filament/schemas:"^5.0"
    filament/forms:"^5.0"
    filament/infolists:"^5.0"
    filament/actions:"^5.0"
    filament/notifications:"^5.0"
    filament/widgets:"^5.0"

之后可再安装其他包，无需重复这些安装步骤。

WARNING

若用 Windows PowerShell 安装 Filament，可能需要运行下面的命令，因为它会忽略版本约束中的 ^：

bash
composer require
    filament/tables:"~5.0"
    filament/schemas:"~5.0"
    filament/forms:"~5.0"
    filament/infolists:"~5.0"
    filament/actions:"~5.0"
    filament/notifications:"~5.0"
    filament/widgets:"~5.0"

若只用 Blade UI 组件，此阶段需 require filament/support。

新 Laravel 项目 ​

运行一条简单命令即可快速上手 Filament 组件。注意这会覆盖应用中已修改的文件，因此只适合新 Laravel 项目。

已有 Laravel 项目 ​

已有 Laravel 项目仍可安装 Filament，但应手动安装以保留现有功能。

要在新 Laravel 项目中快速配置 Filament，运行以下命令安装 Livewire、Alpine.js 与 Tailwind CSS：

WARNING

这些命令会覆盖应用中的现有文件。仅在新 Laravel 项目中运行！

运行以下命令安装 Filament 前端资源：

bash
php artisan filament:install --scaffold

npm install

npm run dev

脚手架过程中，若已安装 Notifications 包，Filament 会询问是否将所需 Livewire 组件装入默认布局。若要通过 Filament 向用户发送 flash 通知，则需要该组件。

运行以下命令安装 Filament 前端资源：

bash
php artisan filament:install

安装 Tailwind CSS ​

若尚未安装 Tailwind CSS 及其 Vite 插件，运行：

bash
npm install tailwindcss @tailwindcss/vite --save-dev

配置样式 ​

要配置 Filament 样式，需导入已安装 Filament 包的 CSS，通常在 resources/css/app.css。

按已安装包的组合，可只导入需要的 CSS，以减小应用 CSS 体积：

css
@import 'tailwindcss';

/* Required by all components */
@import '../../vendor/filament/support/resources/css/index.css';

/* Required by actions and tables */
@import '../../vendor/filament/actions/resources/css/index.css';

/* Required by actions, forms and tables */
@import '../../vendor/filament/forms/resources/css/index.css';

/* Required by actions and infolists */
@import '../../vendor/filament/infolists/resources/css/index.css';

/* Required by notifications */
@import '../../vendor/filament/notifications/resources/css/index.css';

/* Required by actions, infolists, forms, schemas and tables */
@import '../../vendor/filament/schemas/resources/css/index.css';

/* Required by tables */
@import '../../vendor/filament/tables/resources/css/index.css';

/* Required by widgets */
@import '../../vendor/filament/widgets/resources/css/index.css';

@variant dark (&:where(.dark, .dark *));

配置 Vite 插件 ​

若尚未配置，在 Vite 配置（vite.config.js）中加入 @tailwindcss/vite 插件：

js
import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        tailwindcss(),
    ],
})

编译资源 ​

用 npm run dev 编译新的 CSS 与 JavaScript 资源。

配置布局 ​

若还没有 Blade 布局文件，运行以下命令在 resources/views/layouts/app.blade.php 创建：

bash
php artisan livewire:layout

在新布局文件中加入：

blade
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">

        <meta name="application-name" content="{{ config('app.name') }}">
        <meta name="csrf-token" content="{{ csrf_token() }}">
        <meta name="viewport" content="width=device-width, initial-scale=1">

        <title>{{ config('app.name') }}</title>

        <style>
            [x-cloak] {
                display: none !important;
            }
        </style>

        @filamentStyles
        @vite('resources/css/app.css')
    </head>

    <body class="antialiased">
        {{ $slot }}

        @livewire('notifications') {{-- Only required if you wish to send flash notifications --}}

        @filamentScripts
        @vite('resources/js/app.js')
    </body>
</html>

关键是布局 <head> 中的 @filamentStyles，以及 <body> 末尾的 @filamentScripts。同时务必包含 Vite 编译出的应用 CSS 与 JavaScript！

INFO

仅当已安装 Notifications 包且要通过 Filament 发送 flash 通知时，布局中才需要 @livewire('notifications')。

发布配置 ​

Filament 自带可覆盖各包共享默认值的配置文件。安装面板构建器后发布它，以便查看并自定义：

bash
php artisan vendor:publish --tag=filament-config

该命令会创建 config/filament.php，可配置默认文件系统磁盘、文件生成标志、UI 默认值等。之后若要拉取新增配置键再按项目调整，可再次运行发布命令。