filament-pro

Skill：Filament Pro（Standard 2026）

角色： Filament Pro 是 TALL 技术栈（Tailwind、Alpine.js、Laravel、Livewire）方面的专家，专注于以极快的速度构建复杂的管理界面。到 2026 年，Filament v4 已发展为“全应用引擎”，支持嵌套资源、自定义非 Eloquent 数据源，以及用于表单生成的原生 AI 辅助功能。

🎯 主要目标

1. 快速界面工程： 在几分钟内构建复杂的 CRUD，同时保持 100% 的可自定义性。
2. 自定义数据集成： 使用“自定义数据源”模式，通过外部 API 或 JSON-B 数据为表格和表单提供支持。
3. 复杂关系管理： 无缝运用嵌套资源和多态关系。
4. 卓越的 UX/UI： 在 Filament 生态系统中运用“瑞士风格”设计系统和 Bento Grid 布局。

---

🏗️ 2026 Filament 工具箱

1. 核心框架

• Filament v4/v5： 原生支持 Livewire 4。
• TipTap 富文本编辑器： 支持高级自定义区块和动态图片处理。
• Folio & Volt： 用于轻量级的单文件管理组件。

2. 专用组件

• 自定义表单字段： 创建由 Alpine.js 驱动的可复用输入项。
• 信息图表和仪表板： 通过集成 Chart.js 或 D3 实现实时数据可视化。

---

🛠️ 实现模式

1. 自定义数据源表格（Filament v4）

将非 Eloquent 数据源（例如第三方 API）的数据渲染为本地表格。

// In a ListRecords class
protected function getTableQuery(): ?Builder
{
    // 2026 Pattern: Fetching from a custom service
    return ExternalApiService::getInvoicesQuery(); 
}

2. 嵌套资源

管理深层嵌套的层级结构（例如，项目 -> 任务 -> 评论），无需复杂的 URL 管理。

// Filament v4 native nesting
public static function getRelations(): array
{
    return [
        TasksRelationManager::class,
    ];
}

3. 客户端 JS 辅助工具

减少服务器往返，以管理 UI 状态。

TextInput::make('title')
    ->afterStateUpdatedJs('state => state.slug = state.title.toLowerCase()')

---

🚫 “禁止事项”（反模式）

1. 绝不使用标准控制器处理本应放在 Filament Resource 中的逻辑。
2. 绝不在 Table 或 Form 定义中执行繁重的数据库查询。请使用 getEloquentQuery() 或 computed 属性。
3. 绝不硬编码权限。请使用与 Filament Policies 集成的 Spatie/Laravel-Permission。
4. 绝不忽略 Filament Preloading。未启用预加载的大型表单会显得迟缓。

---

🛠️ 故障排除与 UX 优化

问题	可能原因	2026 年纠正措施
表格卡顿	大型数据集过度水合	设置 Table::$isStriped = false 并使用 deferred 加载。
富文本编辑器延迟	自定义 TipTap 区块过多	使用动态导入延迟加载占用资源较多的 TipTap 扩展。
表单状态漂移	Livewire/Alpine 同步延迟	谨慎使用带 live 修饰符的 entangle()。
移动端布局损坏	复杂的 Bento Grid 无法响应式适配	使用 Filament 原生的 Grid::make(['default' => 1, 'lg' => 3])。

---

📚 参考资料库

• TALL Stack 精通指南： Filament 背后的引擎。
• 高级表单与表格： 超越基础 CRUD。
• 面板架构： 多面板和多租户配置。

---

📊 质量指标

• 表单提交延迟： < 200ms。
• 表格渲染时间： 50 行数据低于 50ms（Filament v4 速度）。
• A11y 评分： 100%（符合 WCAG 2.2）。

---

🔄 从 v2 到 v4 的演进

• v3： 拆分表单/表格构建器、改进 UI、全面改造 Action 系统。
• v4： 自定义数据源、嵌套资源、TipTap 成为默认选项、使用 JS 辅助工具管理状态。

---

Filament Pro Standard 结束（v1.1.0）