Back to Details

filament-pro

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Filament v5

Filament v5

Build powerful Laravel admin panels using Filament v5's server-driven UI with Schemas and Livewire v4 reactivity.
借助Filament v5的基于Schema的服务器驱动UI和Livewire v4的响应式能力，构建功能强大的Laravel管理面板。

Overview

概述

Filament v5 is a Laravel admin panel framework that provides complete CRUD interfaces, forms, tables, and dashboard components through a declarative PHP API. Built on Livewire v4, it offers real-time reactivity without writing JavaScript.
Filament v5是一款Laravel管理面板框架，通过声明式PHP API提供完整的CRUD界面、表单、表格和仪表盘组件。它基于Livewire v4构建，无需编写JavaScript即可实现实时响应。

Key Concepts

核心概念

  • PanelProvider: Central configuration class defining your admin panel
  • Resources: Automatic CRUD interfaces for Eloquent models
  • Schemas: Declarative UI components (forms, tables, infolists)
  • Actions: Interactive buttons with modals and backend logic
  • Widgets: Dashboard components for data visualization
  • PanelProvider: 定义管理面板的核心配置类
  • Resources: 为Eloquent模型自动生成CRUD界面
  • Schemas: 声明式UI组件（表单、表格、信息列表）
  • Actions: 带有模态框和后端逻辑的交互式按钮
  • Widgets: 用于数据可视化的仪表盘组件

System Requirements

系统要求

  • Laravel 11.28+
  • PHP 8.2+
  • Livewire v4
  • Node.js 18+
  • Tailwind CSS v4.1+
  • Laravel 11.28+
  • PHP 8.2+
  • Livewire v4
  • Node.js 18+
  • Tailwind CSS v4.1+

Installation

安装

Install Filament via Composer and scaffold a panel:
bash
composer require filament/filament:"^5.0" -W
php artisan filament:install --scaffold
npm install && npm run dev
php artisan make:filament-user
This creates the panel provider, directory structure, and assets needed to start building.
通过Composer安装Filament并搭建面板：
bash
composer require filament/filament:"^5.0" -W
php artisan filament:install --scaffold
npm install && npm run dev
php artisan make:filament-user
此命令会创建面板提供者、目录结构以及开始构建所需的资源文件。

Directory Structure

目录结构

app/
  Filament/
    Resources/          # CRUD resources with forms and tables
    Pages/              # Custom pages
    Widgets/            # Dashboard widgets
  Providers/
    Filament/
      AdminPanelProvider.php
app/
  Filament/
    Resources/          # 包含表单和表格的CRUD资源
    Pages/              # 自定义页面
    Widgets/            # 仪表盘小组件
  Providers/
    Filament/
      AdminPanelProvider.php

Core Concepts

核心概念详解

Panel Configuration

面板配置

The PanelProvider is the entry point for your admin panel. It configures:
  • Identity: ID, path, branding (name, logo, colors)
  • Discovery: Auto-discovery of resources, pages, and widgets
  • Middleware: Session, authentication, and custom middleware
  • Tenancy: Multi-tenant configuration for SaaS applications
PanelProvider是管理面板的入口点，用于配置：
  • 标识: ID、路径、品牌（名称、Logo、颜色）
  • 自动发现: 自动识别资源、页面和小组件
  • 中间件: 会话、认证和自定义中间件
  • 多租户: SaaS应用的多租户配置

Resources

资源

Resources provide complete CRUD interfaces through:
  • Forms: Schema-based forms with 20+ field types (TextInput, Select, DatePicker, FileUpload, RichEditor, etc.)
  • Tables: Data tables with columns, filters, sorting, and actions
  • Pages: Automatic generation of List, Create, Edit, and View pages
  • Relations: Relation managers for handling model relationships
资源通过以下内容提供完整的CRUD界面：
  • 表单: 基于Schema的表单，包含20+字段类型（TextInput、Select、DatePicker、FileUpload、RichEditor等）
  • 表格: 带有列、筛选器、排序和操作的数据表格
  • 页面: 自动生成列表、创建、编辑和详情页面
  • 关联: 用于处理模型关联的关联管理器

Forms

表单

Forms use a schema-based approach where you declare fields as PHP objects:
  • Input Fields: Text, select, checkbox, toggle, date/time pickers
  • Media: File and image uploads with validation
  • Complex Fields: Rich text editors, repeaters, builders
  • Layout: Grids, sections, tabs, and wizards
  • Validation: Built-in Laravel validation rules
表单采用基于Schema的方式，通过PHP对象声明字段：
  • 输入字段: 文本、选择框、复选框、开关、日期/时间选择器
  • 媒体: 带有验证的文件和图片上传
  • 复杂字段: 富文本编辑器、重复器、构建器
  • 布局: 网格、区块、标签页和向导
  • 验证: 内置Laravel验证规则

Tables

表格

Tables display data with extensive customization:
  • Columns: Text, badges, icons, images, colors
  • Filters: Select, ternary, and custom filter logic
  • Actions: Per-row actions, bulk actions, header actions
  • Features: Search, sorting, pagination, grouping
表格可高度自定义地展示数据：
  • 列: 文本、徽章、图标、图片、颜色
  • 筛选器: 选择、三元和自定义筛选逻辑
  • 操作: 单行操作、批量操作、头部操作
  • 功能: 搜索、排序、分页、分组

Actions

操作

Actions are interactive buttons that trigger:
  • Modals: Form dialogs for data collection
  • Confirmation: Destructive action confirmation
  • Wizards: Multi-step processes
  • Notifications: User feedback after completion
操作是触发以下行为的交互式按钮：
  • 模态框: 用于收集数据的表单对话框
  • 确认: 破坏性操作的确认提示
  • 向导: 多步骤流程
  • 通知: 操作完成后的用户反馈

Widgets

小组件

Dashboard widgets include:
  • Stats Overview: Metric cards with trends and sparklines
  • Charts: Line, bar, pie charts using Chart.js
  • Tables: Data tables for recent records
仪表盘小组件包括：
  • 统计概览: 带有趋势和迷你图的指标卡片
  • 图表: 使用Chart.js的折线图、柱状图、饼图
  • 表格: 用于展示最近记录的数据表格

Testing

测试

Filament uses Pest PHP with Livewire testing helpers:
  • Page Testing: List, create, edit, view page functionality
  • Form Testing: Validation, state management, submission
  • Table Testing: Search, filters, sorting, actions
  • Authorization Testing: Access control and permissions
Filament结合Pest PHP和Livewire测试助手：
  • 页面测试: 列表、创建、编辑、详情页面的功能测试
  • 表单测试: 验证、状态管理、提交测试
  • 表格测试: 搜索、筛选、排序、操作测试
  • 授权测试: 访问控制和权限测试

Authorization

授权

Access control through:
  • Panel Access: FilamentUser contract for panel-level access
  • Policies: Laravel policies for resource-level permissions
  • Field Visibility: Show/hide fields based on user roles
  • Multi-Tenancy: Tenant isolation for SaaS applications
通过以下方式实现访问控制：
  • 面板访问: 用于面板级访问控制的FilamentUser契约
  • 策略: 用于资源级权限的Laravel策略
  • 字段可见性: 根据用户角色显示/隐藏字段
  • 多租户: SaaS应用的租户隔离

Architecture Patterns

架构模式

Server-Driven UI

服务器驱动UI

Filament uses a server-driven approach where the backend defines the UI structure through schemas. The PHP code describes forms, tables, and layouts which Filament renders as Livewire components.
Filament采用服务器驱动方式，后端通过Schema定义UI结构。PHP代码描述表单、表格和布局，Filament将其渲染为Livewire组件。

Schema System

Schema系统

Schemas are PHP configuration objects that define:
  • Form fields and their validation rules
  • Table columns and their formatting
  • Layout containers (grids, sections, tabs)
  • Action definitions and their behavior
Schema是定义以下内容的PHP配置对象：
  • 表单字段及其验证规则
  • 表格列及其格式化
  • 布局容器（网格、区块、标签页）
  • 操作定义及其行为

Livewire Integration

Livewire集成

All components mount as Livewire components, providing:
  • Real-time reactivity without page reloads
  • Automatic state management
  • Event handling and AJAX updates
  • Form validation with instant feedback
所有组件都以Livewire组件的形式加载，提供：
  • 无需页面刷新的实时响应
  • 自动状态管理
  • 事件处理和AJAX更新
  • 即时反馈的表单验证

Resource-First Design

资源优先设计

The framework encourages a resource-first approach:
  1. Define your Eloquent models
  2. Create resources that map to those models
  3. Configure forms and tables for each resource
  4. Add actions and widgets as needed
该框架鼓励资源优先的设计方式：
  1. 定义Eloquent模型
  2. 创建与这些模型对应的资源
  3. 为每个资源配置表单和表格
  4. 根据需要添加操作和小组件

Command Reference

命令参考

CommandPurpose
filament:install --scaffold
Install Filament with panel scaffolding
make:filament-resource
Create CRUD resource
make:filament-page
Create custom page
make:filament-widget
Create dashboard widget
make:filament-panel
Create additional panel
make:filament-user
Create admin user
make:filament-relation-manager
Create relation manager
filament:cache-components
Cache for production
命令用途
filament:install --scaffold
安装Filament并搭建面板框架
make:filament-resource
创建CRUD资源
make:filament-page
创建自定义页面
make:filament-widget
创建仪表盘小组件
make:filament-panel
创建额外的面板
make:filament-user
创建管理员用户
make:filament-relation-manager
创建关联管理器
filament:cache-components
生产环境下的组件缓存

Detailed Documentation

详细文档

Reference Guides

参考指南

Comprehensive documentation for each component:
  • Forms - All form components, validation rules, layouts, and conditional logic
  • Tables - Column types, filters, actions, and table configuration
  • Resources - CRUD resources, relation managers, infolists, and global search
  • Infolists - Read-only data display components (TextEntry, ImageEntry, IconEntry)
  • Widgets - Stats overview, charts, and table widgets
  • Actions - Modal actions, notifications, action groups, and wizards
  • Notifications - Flash messages, database, and broadcast notifications
  • Schemas - Schema system, layouts, and component organization
  • Testing - Pest testing patterns for resources, forms, tables, and authorization
  • Authorization - Access control, policies, roles, and multi-tenancy
每个组件的全面文档：
  • Forms - 所有表单组件、验证规则、布局和条件逻辑
  • Tables - 列类型、筛选器、操作和表格配置
  • Resources - CRUD资源、关联管理器、信息列表和全局搜索
  • Infolists - 只读数据展示组件（TextEntry、ImageEntry、IconEntry）
  • Widgets - 统计概览、图表和表格小组件
  • Actions - 模态框操作、通知、操作组和向导
  • Notifications - 闪存消息、数据库和广播通知
  • Schemas - Schema系统、布局和组件组织
  • Testing - 针对资源、表单、表格和授权的Pest测试模式
  • Authorization - 访问控制、策略、角色和多租户

Code Examples

代码示例

See examples.md for complete working code examples including:
  • Complete resource implementations
  • Form configurations
  • Table setups
  • Widget configurations
  • Test suites
  • Authorization patterns
查看examples.md获取完整的可运行代码示例，包括：
  • 完整的资源实现
  • 表单配置
  • 表格设置
  • 小组件配置
  • 测试套件
  • 授权模式

Best Practices

最佳实践

Performance

性能

  • Use 
    getEloquentQuery()
    to eager load relationships and prevent N+1 queries
  • Enable component caching in production with 
    filament:cache-components
  • Limit pagination options and use deferred loading for large datasets
  • Cache expensive calculations in widgets
  • 使用
    getEloquentQuery()
    预加载关联关系，避免N+1查询
  • 在生产环境中使用
    filament:cache-components
    启用组件缓存
  • 限制分页选项，对大型数据集使用延迟加载
  • 在小组件中缓存耗时的计算

Security

安全

  • Always implement the FilamentUser contract for panel access control
  • Use Laravel policies for resource-level authorization
  • Validate all input with appropriate form rules
  • Never skip authorization in production environments
  • Implement proper tenant isolation for multi-tenant applications
  • 始终实现FilamentUser契约以控制面板访问
  • 使用Laravel策略进行资源级授权
  • 使用适当的表单规则验证所有输入
  • 生产环境中绝不要跳过授权检查
  • 为多租户应用实现适当的租户隔离

Code Organization

代码组织

  • Organize by feature: 
    app/Filament/Admin/Resources/
  • Extract complex forms and tables to separate classes
  • Create reusable form components for common patterns
  • Keep resources focused on single responsibility
  • Use dedicated pages for non-CRUD functionality
  • 按功能组织：
    app/Filament/Admin/Resources/
  • 将复杂的表单和表格提取到单独的类中
  • 为常见模式创建可复用的表单组件
  • 保持资源专注于单一职责
  • 为非CRUD功能使用专用页面

Testing

测试

  • Test all CRUD operations for each resource
  • Validate form validation rules with multiple scenarios
  • Test table features: search, filters, sorting, actions
  • Verify authorization with different user roles
  • Use factories to create realistic test data
  • 测试每个资源的所有CRUD操作
  • 使用多种场景验证表单验证规则
  • 测试表格功能：搜索、筛选、排序、操作
  • 验证不同用户角色的授权情况
  • 使用工厂创建真实的测试数据

When to Use Filament

适用场景

Filament is ideal for:
  • Admin Panels: Back-office interfaces for managing application data
  • CMS: Content management systems with rich editing capabilities
  • CRM: Customer relationship management tools
  • E-commerce: Product, order, and inventory management
  • SaaS Applications: Multi-tenant admin interfaces
  • Internal Tools: Business process management and data entry
Filament非常适合：
  • 管理面板: 用于管理应用数据的后台界面
  • CMS: 具备丰富编辑功能的内容管理系统
  • CRM: 客户关系管理工具
  • 电商: 商品、订单和库存管理
  • SaaS应用: 多租户管理界面
  • 内部工具: 业务流程管理和数据录入

Additional Resources

额外资源

Version: 1.0.0
License: MIT
Compatibility: Laravel 11+, PHP 8.2+, Livewire v4
版本: 1.0.0
许可证: MIT
兼容性: Laravel 11+, PHP 8.2+, Livewire v4