filament-pro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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:

Define your Eloquent models
Create resources that map to those models
Configure forms and tables for each resource
Add actions and widgets as needed

该框架鼓励资源优先的设计方式：

定义Eloquent模型
创建与这些模型对应的资源
为每个资源配置表单和表格
根据需要添加操作和小组件

Command Reference

命令参考

Command	Purpose
`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