laravel-blade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Laravel Blade

Agent Workflow (MANDATORY)

Agent工作流程（强制要求）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Check existing views, components structure
fuse-ai-pilot:research-expert - Verify latest Blade docs via Context7
mcp__context7__query-docs - Query specific patterns (components, slots)

After implementation, run fuse-ai-pilot:sniper for validation.

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

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

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

Overview

概述

Blade is Laravel's templating engine. It provides a clean syntax for PHP in views while compiling to pure PHP for performance.

Component Type	When to Use
Anonymous	Simple UI, no logic needed
Class-based	Dependency injection, complex logic
Layout	Page structure, reusable shells
Dynamic	Runtime component selection

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

组件类型	适用场景
Anonymous	简单UI，无需逻辑
Class-based	依赖注入、复杂逻辑
Layout	页面结构、可复用外壳
Dynamic	运行时组件选择

Critical Rules

核心规则

Always escape output - Use
```
{{ }}
```
not
```
{!! !!}
```
unless absolutely necessary
Use @props - Declare expected props explicitly
Merge attributes - Allow class/attribute overrides with
```
$attributes->merge()
```
Prefer anonymous - Use class components only when logic is needed
Use named slots - For complex layouts with multiple content areas
CSRF in forms - Always include
```
@csrf
```
in forms

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

Decision Guide

决策指南

Component Type Selection

组件类型选择

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

需要依赖注入？
├── 是 → 类组件
└── 否 → 匿名组件
    │
    需要复杂的props逻辑？
    ├── 是 → 类组件
    └── 否 → 匿名组件

Layout Strategy

布局策略

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

页面结构简单？
├── 是 → 组件布局(<x-layout>)
└── 否 → 需要细粒度的区块？
    ├── 是 → @extends/@section
    └── 否 → 组件布局

Key Concepts

核心概念

Concept	Description	Reference
@props	Declare component properties	components.md
$attributes	Pass-through HTML attributes	slots-attributes.md
x-slot	Named content areas	slots-attributes.md
@yield/@section	Traditional layout inheritance	layouts.md
$loop	Loop iteration info	directives.md

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

Reference Guide

参考指南

Concepts (WHY & Architecture)

概念（设计思路与架构）

Topic	Reference	When to Consult
Components	components.md	Class vs anonymous, namespacing
Slots & Attributes	slots-attributes.md	Data flow, $attributes bag
Layouts	layouts.md	Page structure, inheritance
Directives	directives.md	@if, @foreach, @auth, @can
Security	security.md	XSS, CSRF, escaping
Vite	vite.md	Asset bundling
Advanced Directives	advanced-directives.md	@once, @use, @inject, @switch, stacks
Custom Directives	custom-directives.md	Blade::if, Blade::directive
Advanced Components	advanced-components.md	@aware, shouldRender, index
Forms & Validation	forms-validation.md	@error, form helpers
Fragments	fragments.md	@fragment, HTMX integration

主题	参考文档	适用场景
Components	components.md	类组件vs匿名组件、命名空间
Slots & Attributes	slots-attributes.md	数据流、$attributes集合
Layouts	layouts.md	页面结构、继承
Directives	directives.md	@if、@foreach、@auth、@can
Security	security.md	XSS、CSRF、转义
Vite	vite.md	资源打包
Advanced Directives	advanced-directives.md	@once、@use、@inject、@switch、stacks
Custom Directives	custom-directives.md	Blade::if、Blade::directive
Advanced Components	advanced-components.md	@aware、shouldRender、index
Forms & Validation	forms-validation.md	@error、表单助手
Fragments	fragments.md	@fragment、HTMX集成

Templates (Complete Code)

模板（完整代码）

Template	When to Use
ClassComponent.php.md	Component with logic/DI
AnonymousComponent.blade.md	Simple reusable UI
LayoutComponent.blade.md	Page layout structure
FormComponent.blade.md	Form with validation
CardWithSlots.blade.md	Named slots pattern
DynamicComponent.blade.md	Runtime component
AdvancedDirectives.blade.md	@once, @use, @inject, @switch
CustomDirectives.php.md	Create custom directives
AdvancedComponents.blade.md	@aware, shouldRender, index
Fragments.blade.md	HTMX partial updates

模板	适用场景
ClassComponent.php.md	带逻辑/依赖注入的组件
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局部更新

Quick Reference

快速参考

Anonymous Component

匿名组件

blade

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

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

blade

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

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

Class Component

类组件

php

// 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');
    }
}

php

// 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');
    }
}

Named Slots

命名插槽

blade

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

    Content goes here

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

blade

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

    Content goes here

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

Attribute Merging

属性合并

blade

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

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

blade

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

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

Best Practices

最佳实践

DO

建议做法

Use
```
@props
```
to document expected props
Use
```
$attributes->merge()
```
for flexibility
Prefer anonymous components for simple UI
Use named slots for complex layouts
Keep components focused and reusable

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

DON'T

避免做法

Use
```
{!! !!}
```
without sanitization
Forget
```
@csrf
```
in forms
Put business logic in Blade templates
Create deeply nested component hierarchies
Hardcode classes (allow overrides)

未经过滤就使用
```
{!! !!}
```
表单中遗漏
```
@csrf
```
在Blade模板中写入业务逻辑
创建深度嵌套的组件层级
硬编码类名（允许覆盖）