kiri-router/src/Blade/SYNTAX.md

# Blade 语法糖参考手册

本文档列出了所有可用的 Blade 语法糖和指令。

## 变量输出

### 转义输出
```blade
{{ $variable }}
{{ $user->name }}
{{ $array['key'] }}
```
自动转义 HTML 特殊字符，防止 XSS 攻击。

### 原始输出
```blade
{!! $htmlContent !!}
```
不转义，直接输出原始 HTML（谨慎使用）。

### JSON 输出
```blade
@json($data)
```
将数据编码为 JSON 字符串输出。

## 控制结构

### 条件判断

#### @if / @elseif / @else / @endif
```blade
@if($user->isAdmin())
    <p>管理员</p>
@elseif($user->isModerator())
    <p>版主</p>
@else
    <p>普通用户</p>
@endif
```

#### @unless / @endunless
```blade
@unless($user->isBanned())
    <p>用户正常</p>
@endunless
```
等同于 `@if(!condition)`

#### @isset / @endisset
```blade
@isset($variable)
    <p>{{ $variable }}</p>
@endisset
```

#### @empty / @endempty
```blade
@empty($items)
    <p>列表为空</p>
@endempty
```

### 循环

#### @foreach / @endforeach
```blade
@foreach($users as $user)
    <p>{{ $user->name }}</p>
@endforeach
```

#### @for / @endfor
```blade
@for($i = 0; $i < 10; $i++)
    <p>Item {{ $i }}</p>
@endfor
```

#### @while / @endwhile
```blade
@while($condition)
    <p>循环内容</p>
@endwhile
```

#### @forelse / @empty / @endforelse
```blade
@forelse($items as $item)
    <p>{{ $item->name }}</p>
@empty
    <p>没有项目</p>
@endforelse
```

#### @break 和 @continue
```blade
@foreach($items as $item)
    @if($item->hidden)
        @continue
    @endif
    <p>{{ $item->name }}</p>
    @if($item->id > 100)
        @break
    @endif
@endforeach
```

### Switch 语句

```blade
@switch($status)
    @case(1)
        <p>待处理</p>
        @break
    @case(2)
        <p>处理中</p>
        @break
    @default
        <p>未知状态</p>
@endswitch
```

## 布局和继承

### @extends
```blade
@extends('layouts.app')
```

### @section / @endsection
```blade
@section('content')
    <h1>页面内容</h1>
@endsection
```

### @yield
```blade
@yield('content')
@yield('title', '默认标题')
```

### @parent
在子视图的 section 中使用，输出父布局中对应 section 的内容。

### @hasSection / @endhasSection
```blade
@hasSection('sidebar')
    @yield('sidebar')
@endhasSection
```

### @sectionMissing / @endsectionMissing
```blade
@sectionMissing('sidebar')
    <p>没有侧边栏</p>
@endsectionMissing
```

## 包含和组件

### @include
```blade
@include('components.header')
@include('components.footer', ['year' => 2024])
```

### @each
```blade
@each('components.item', $items, 'item')
@each('components.item', $items, 'item', 'components.empty')
```

## 栈和推送

### @push / @endpush
```blade
@push('scripts')
    <script src="/js/custom.js"></script>
@endpush
```

### @prepend / @endprepend
```blade
@prepend('scripts')
    <script src="/js/jquery.js"></script>
@endprepend
```

### @stack
```blade
@stack('scripts')
```

## 表单辅助

### @csrf
```blade
<form method="POST">
    @csrf
    ...
</form>
```

### @method
```blade
<form method="POST">
    @method('PUT')
    ...
</form>
```

### @old
```blade
<input type="text" name="name" value="@old('name', '默认值')">
```

### @checked
```blade
<input type="checkbox" name="active" @checked($user->isActive())>
```

### @selected
```blade
<select name="status">
    <option value="1" @selected($status == 1)>启用</option>
    <option value="0" @selected($status == 0)>禁用</option>
</select>
```

### @disabled
```blade
<input type="text" @disabled($readonly)>
```

### @readonly
```blade
<input type="text" @readonly($readonly)>
```

### @required
```blade
<input type="text" @required($isRequired)>
```

## 权限和认证

### @auth / @endauth
```blade
@auth
    <p>欢迎，{{ auth()->user()->name }}</p>
@endauth

@auth('admin')
    <p>管理员面板</p>
@endauth
```

### @guest / @endguest
```blade
@guest
    <a href="/login">登录</a>
@endguest
```

### @can / @endcan
```blade
@can('edit', $post)
    <a href="/posts/{{ $post->id }}/edit">编辑</a>
@endcan
```

### @cannot / @endcannot
```blade
@cannot('edit', $post)
    <p>您没有编辑权限</p>
@endcannot
```

## 错误处理

### @error / @enderror
```blade
@error('email')
    <p class="error">{{ $message }}</p>
@enderror
```

## 其他语法糖

### @once / @endonce
```blade
@once
    <script src="/js/unique.js"></script>
@endonce
```
确保内容只输出一次。

### @lang
```blade
@lang('messages.welcome')
@lang('messages.greeting', ['name' => $user->name])
```

### @class
```blade
<div @class(['active' => $isActive, 'disabled' => $isDisabled])>
```

### @style
```blade
<div @style(['color' => 'red', 'font-size' => '14px'])>
```

### @php / @endphp
```blade
@php
    $count = count($items);
    $total = array_sum($prices);
@endphp
```

### 注释
```blade
{{-- 这是注释，不会输出到 HTML --}}
```

## 使用示例

### 完整的页面模板
```blade
@extends('layouts.app')

@section('title', '用户资料')

@push('styles')
    <link rel="stylesheet" href="/css/profile.css">
@endpush

@section('content')
    @auth
        <h1>欢迎，{{ auth()->user()->name }}</h1>
        
        @if($user->isAdmin())
            <p class="badge">管理员</p>
        @endif
        
        <form method="POST" action="/profile">
            @csrf
            @method('PUT')
            
            <input type="text" name="name" value="@old('name', $user->name)">
            @error('name')
                <p class="error">{{ $message }}</p>
            @enderror
            
            <button type="submit" @disabled($readonly)>保存</button>
        </form>
        
        <h2>文章列表</h2>
        @forelse($posts as $post)
            <article>
                <h3>{{ $post->title }}</h3>
                <p>{{ $post->content }}</p>
            </article>
        @empty
            <p>暂无文章</p>
        @endforelse
    @else
        <p>请先登录</p>
    @endauth
@endsection

@push('scripts')
    <script src="/js/profile.js"></script>
@endpush
```

### 布局文件
```blade
<!DOCTYPE html>
<html>
<head>
    <title>@yield('title', '默认标题')</title>
    @stack('styles')
</head>
<body>
    <header>
        @include('components.header')
    </header>
    
    <main>
        @yield('content')
    </main>
    
    <footer>
        @include('components.footer')
    </footer>
    
    @stack('scripts')
</body>
</html>
```