kiri-router/src/Blade/SYNTAX.md

Blade 语法糖参考手册

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

变量输出

转义输出

{{ $variable }}
{{ $user->name }}
{{ $array['key'] }}

自动转义 HTML 特殊字符，防止 XSS 攻击。

原始输出

{!! $htmlContent !!}

不转义，直接输出原始 HTML（谨慎使用）。

JSON 输出

@json($data)

将数据编码为 JSON 字符串输出。

控制结构

条件判断

@if / @elseif / @else / @endif

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

@unless / @endunless

@unless($user->isBanned())
    <p>用户正常</p>
@endunless

等同于 @if(!condition)

@isset / @endisset

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

@empty / @endempty

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

循环

@foreach / @endforeach

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

@for / @endfor

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

@while / @endwhile

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

@forelse / @empty / @endforelse

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

@break 和 @continue

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

Switch 语句

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

布局和继承

@extends

@extends('layouts.app')

@section / @endsection

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

@yield

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

@parent

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

@hasSection / @endhasSection

@hasSection('sidebar')
    @yield('sidebar')
@endhasSection

@sectionMissing / @endsectionMissing

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

包含和组件

@include

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

@each

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

栈和推送

@push / @endpush

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

@prepend / @endprepend

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

@stack

@stack('scripts')

表单辅助

@csrf

<form method="POST">
    @csrf
    ...
</form>

@method

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

@old

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

@checked

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

@selected

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

@disabled

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

@readonly

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

@required

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

权限和认证

@auth / @endauth

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

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

@guest / @endguest

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

@can / @endcan

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

@cannot / @endcannot

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

错误处理

@error / @enderror

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

其他语法糖

@once / @endonce

@once
    <script src="/js/unique.js"></script>
@endonce

确保内容只输出一次。

@lang

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

@class

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

@style

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

@php / @endphp

@php
    $count = count($items);
    $total = array_sum($prices);
@endphp

注释

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

使用示例

完整的页面模板

@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

布局文件

<!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>