laravel-blade

涵盖 Laravel Blade 模板：匿名组件和基于类的组件、命名插槽和属性包（$attributes->merge()）、布局（基于组件的布局和@extends/@section 继承）、指令（@if、@foreach、@auth、@can，以及 @once/@use/@inject/@switch/堆栈等高级指令）、自定义指令（Blade::if、Blade::directive）、安全性（XSS/CSRF 转义）、Vite 资源集成、表单/验证辅助功能（@error），以及用于 HTMX 风格局部更新的片段。

Laravel Blade

Agent 工作流（MANDATORY）

在进行任何实现之前，并行启动 3 个 Agent，每个使用一个带 name 的 Agent 调用：

1. fuse-ai-pilot:explore-codebase - 检查现有视图和组件结构
2. fuse-ai-pilot:research-expert - 通过 Context7 验证最新的 Blade 文档
3. mcp__context7__query-docs - 查询特定模式（组件、插槽）

实现之后，运行 fuse-ai-pilot:sniper 进行验证。

---

概述

Blade 是 Laravel 的模板引擎。它为视图中的 PHP 提供简洁的语法，同时会编译为纯 PHP，以提升性能。

组件类型	适用场景
匿名	简单 UI，无需逻辑
基于类	依赖注入、复杂逻辑
布局	页面结构、可复用外壳
动态	运行时选择组件

---

关键规则

1. 始终转义输出 - 使用 {{ }}，除非绝对必要，否则不要使用 {!! !!}
2. 使用 @props - 显式声明预期的 props
3. 合并属性 - 使用 $attributes->merge() 允许覆盖 class/属性
4. 优先使用匿名组件 - 仅在需要逻辑时使用基于类的组件
5. 使用命名插槽 - 用于包含多个内容区域的复杂布局
6. 在表单中使用 CSRF - 始终在表单中包含 @csrf

---

决策指南

组件类型选择

Need dependency injection?
├── YES → Class-based component
└── NO → Anonymous component
    │
    Need complex props logic?
    ├── YES → Class-based component
    └── NO → Anonymous component

布局策略

Simple page structure?
├── YES → Component layout (<x-layout>)
└── NO → Need fine-grained sections?
    ├── YES → @extends/@section
    └── NO → Component layout

---

核心概念

概念	说明	参考
@props	声明组件属性	components.md
$attributes	透传 HTML 属性	slots-attributes.md
x-slot	命名内容区域	slots-attributes.md
@yield/@section	传统布局继承	layouts.md
$loop	循环迭代信息	directives.md

---

参考指南

概念（原因与架构）

主题	参考	何时查阅
组件	components.md	基于类还是匿名、命名空间
插槽与属性	slots-attributes.md	数据流、$attributes 属性包
布局	layouts.md	页面结构、继承
指令	directives.md	@if、@foreach、@auth、@can
安全性	security.md	XSS、CSRF、转义
Vite	vite.md	资源打包
高级指令	advanced-directives.md	@once、@use、@inject、@switch、堆栈
自定义指令	custom-directives.md	Blade::if、Blade::directive
高级组件	advanced-components.md	@aware、shouldRender、index
表单与验证	forms-validation.md	@error、表单辅助功能
片段	fragments.md	@fragment、HTMX 集成

模板（完整代码）

模板	适用场景
ClassComponent.php.md	带逻辑/DI 的组件
AnonymousComponent.blade.md	简单的可复用 UI
LayoutComponent.blade.md	页面布局结构
FormComponent.blade.md	带验证的表单
CardWithSlots.blade.md	命名插槽模式
DynamicComponent.blade.md	运行时组件
AdvancedDirectives.blade.md	@once、@use、@inject、@switch
CustomDirectives.php.md	创建自定义指令
AdvancedComponents.blade.md	@aware、shouldRender、index
Fragments.blade.md	HTMX 局部更新

---

快速参考

匿名组件

{{-- resources/views/components/alert.blade.php --}}
@props(['type' => 'info', 'message'])

<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
    {{ $message }}
</div>

类组件

// app/View/Components/Alert.php
class Alert extends Component
{
    public function __construct(
        public string $type = 'info',
        public string $message = ''
    ) {}

    public function render(): View
    {
        return view('components.alert');
    }
}

命名插槽

<x-card>
    <x-slot:header class="font-bold">
        Title
    </x-slot>

    Content goes here

    <x-slot:footer>
        Footer content
    </x-slot>
</x-card>

属性合并

@props(['disabled' => false])

<button {{ $attributes->merge([
    'type' => 'submit',
    'class' => 'btn btn-primary'
])->class(['opacity-50' => $disabled]) }}
    @disabled($disabled)
>
    {{ $slot }}
</button>

---

最佳实践

应该做

• 使用 @props 记录预期的 props
• 使用 $attributes->merge() 提高灵活性
• 简单 UI 优先使用匿名组件
• 复杂布局使用命名插槽
• 保持组件专注且可复用

不应该做

• 未经消毒就使用 {!! !!}
• 忘记在表单中添加 @csrf
• 将业务逻辑放在 Blade 模板中
• 创建层级过深的组件结构
• 硬编码类（应允许覆盖）

---

Laravel 13 说明

控制器属性 #[Middleware] 和 #[Authorize]

Laravel 13 支持在控制器类和方法上使用 PHP 属性来声明中间件和授权（取代 __construct 中繁琐的中间件样板代码）。

use Illuminate\Routing\Attributes\Controllers\Middleware;
use Illuminate\Routing\Attributes\Controllers\Authorize;

#[Middleware(['auth', 'verified'])]
final class PostController extends Controller
{
    #[Authorize('viewAny', Post::class)]
    public function index() { return view('posts.index'); }

    #[Middleware('throttle:60,1')]
    #[Authorize('create', Post::class)]
    public function store(StorePostRequest $request) { /* ... */ }
}

通过属性声明的中间件会与组/路由中间件合并（13.8+），并由子控制器继承（13.5+）；还可使用 #[Middleware('log', only: ['index'])] / except: 和 #[WithoutMiddleware(...)]（13.20+）。#[Authorize] 是 can 中间件的简写（策略拒绝时返回 403）。

@fonts 指令（13.7+）

注入由 laravel-vite-plugin 的 fonts 选项生成的可自托管字体（参见 [[laravel-vite]]）。