Laravel 的 Blade 模板引擎

简介

Blade 是 Laravel 提供的一个简单而又强大的模板引擎。和其他流行的 PHP 模板引擎不同，Blade 并不限制你在视图中使用原生 PHP 代码。所有 Blade 视图文件都将被编译成原生的 PHP 代码并缓存起来，除非它被修改，否则不会重新编译，这就意味着 Blade 基本上不会给你的应用增加任何负担。Blade 视图文件使用 .blade.php 作为文件扩展名，被存放在 resources/views 目录。

模板继承

定义布局

Blade 的两个主要优点是 模板继承 和 区块 。为方便开始，让我们先通过一个简单的例子来上手。首先，我们来研究一个「主」页面布局。因为大多数 web 应用会在不同的页面中使用相同的布局方式，因此可以很方便地定义单个 Blade 布局视图：

  1. <!-- 文件保存于 resources/views/layouts/app.blade.php -->
  3. <html>
  4.     <head>
  5.         <title>应用程序名称 - @yield('title')</title>
  6.     </head>
  7.     <body>
  8.         @section('sidebar')
  9.             这是主布局的侧边栏。
  10.         @show
  12.         <div class="container">
  13.             @yield('content')
  14.         </div>
  15.     </body>
  16. </html>

如你所见，该文件包含了典型的 HTML 语法。不过，请注意 @section 和 @yield 命令。顾名思义，@section 命令定义了视图的一部分内容，而 @yield 指令是用来显示指定部分的内容。

现在，我们已经定义好了这个应用程序的布局，接下来，我们定义一个继承此布局的子页面。

继承布局

当定义子视图时，你可以使用 Blade 提供的 @extends 命令来为子视图指定应该 「继承」 的布局。 继承 Blade 布局的视图可使用 @section 命令将内容注入于布局的 @section 中。而「主」布局中使用 @yield 的地方会显示这些子视图中的 @section 间的内容：

  1. <!-- 文件保存于 resources/views/layouts/child.blade.php -->
  3. @extends('layouts.app')
  5. @section('title', 'Page Title')
  7. @section('sidebar')
  8.     @parent
  10.     <p>这将追加到主布局的侧边栏。</p>
  11. @endsection
  13. @section('content')
  14.     <p>这是主体内容。</p>
  15. @endsection

在上面的例子里，@section 中的 sidebar 使用 @@parent 命令在「主」布局的 @section('sidebar') 中增加内容（不是覆盖）。渲染视图时，@@parent 指令会被替换为「主」布局中 @section('sidebar') 间的内容。

{tip} 与上一个示例相反，此侧边栏部分以 @endsection 而不是 @show 结尾。 @endsection 指令只定义一个区块，而 @show 则是定义并立即生成该区块。

你也可以通过在路由中使用全局辅助函数 view 来返回 Blade 视图：

  1. Route::get('blade', function () {
  2.     return view('child');
  3. });

Components & Slots

Components 和 slots 类似于布局中的 @section，但其使用方式更容易使人理解。首先，假设我们有一个能在整个应用程序中被重复使用的「警告」组件:

  1. <!-- /resources/views/alert.blade.php -->
  3. <div class="alert alert-danger">
  4.     {{ $slot }}
  5. </div>

{{ $slot }} 变量将包含我们希望注入到组件的内容。然后，我们可以使用 Blade 命令 @component 来构建这个组件：

  1. @component('alert')
  2.     <strong>Whoops!</strong> Something went wrong!
  3. @endcomponent

有时为组件定义多个 slots 是很有帮助的。现在我们要对「警报」组件进行修改，让它可以注入「标题」。通过简单地 「打印」匹配其名称的变量来显示被命名的 @slot 之间的内容：

  1. <!-- /resources/views/alert.blade.php -->
  3. <div class="alert alert-danger">
  4.     <div class="alert-title">{{ $title }}</div>
  6.     {{ $slot }}
  7. </div>

现在，我们可以使用 @slot 指令注入内容到已命名的 slot 中，任何没有被 @slot 指令包裹住的内容将传递给组件中的 $slot 变量:

  1. @component('alert')
  2.     @slot('title')
  3.         Forbidden
  4.     @endslot
  6.     你没有权限访问这个资源！
  7. @endcomponent

传递额外的数据给组件

有时候你可能需要传递额外的数据给组件。你可以传递一个数组作为第二个参数传递给 @component 指令。所有的数据都将以变量的形式传递给组件模版:

  1. @component('alert', ['foo' => 'bar'])
  2.     ...
  3. @endcomponent

显示数据

你可以使用 「中括号」 包住变量将数据传递给 Blade 视图。如下面的路由设置：

  1. Route::get('greeting', function () {
  2.     return view('welcome', ['name' => 'Samantha']);
  3. });

你可以像这样显示 name 变量的内容：

  1. Hello, {{ $name }}.

当然，不仅仅只能用传递数据的方式让视图来显示变量内容。你也可以打印 PHP 函数的结果。其实，你可以在 Blade 打印语法中放置任何 PHP 代码：

  1. The current UNIX timestamp is {{ time() }}.

{note} Blade 的 {{ }} 语法会自动调用 PHP htmlspecialchars 函数来避免 XSS 攻击。

显示未转义的数据

默认情况下，Blade 的 {{ }} 语法将会自动调用 PHP htmlspecialchars 函数来避免 XSS 攻击。如果你不想你的数据被转义，你可以使用下面的语法：

  1. Hello, {!! $name !!}.

{note} 处理用户输入的数据时要非常小心。在显示用户提供的数据时，你应该始终使用转义的 {{ }} 语法来防止 XSS 攻击。

渲染 JSON

当你将数组传递给视图时，会将数组转化成 JSON 数据，以此来初始化 JavaScript 变量。例如：

  1. <script>
  2.     var app = <?php json_encode($array); ?>;
  3. </script>

你可以使用 Blade 指令 @json 来代替手动调用 json_encode：

  1. <script>
  2.     var app = @json($array)
  3. </script>

Blade & JavaScript 框架

由于很多 JavaScript 框架都使用花括号来表示给定的表达式应该在浏览器中显示，你可以使用 @ 符号来告知 Blade 渲染引擎你需要保留这个表达式原始形态，例如：

  1. <h1>Laravel</h1>
  3. Hello, @{{ name }}.

在这个例子里，@ 符号最终会被 Blade 引擎删除，达到不受 Blade 模板引擎影响的目的，最终 {{ name }} 表达式会保持不变使得 JavaScript 框架可以使用它。

@verbatim 指令

如果你需要在页面中大部分内容中展示 JavaScript 变量，你可以使用 @verbatim 指令来包裹 HTML 内容，这样你就不必在每个Blade 打印语句前加上 @ 符号：

  1. @verbatim
  2.     <div class="container">
  3.         Hello, {{ name }}.
  4.     </div>
  5. @endverbatim

流程控制

除了模板继承与数据显示的功能以外，Blade 还提供了常见的 PHP 流程控制语句，比如条件表达式和循环语句。这些语句与 PHP 语句的相似，与其一样清晰简明。

If 语句

你可以使用 @if、@elseif、@else 及 @endif 指令来构建 if 表达式。这些命令的功能等同于 PHP 中的语法：

  1. @if (count($records) === 1)
  2.     我有一条记录！
  3. @elseif (count($records) > 1)
  4.     我有多条记录！
  5. @else
  6.     我没有任何记录！
  7. @endif

为了方便，Blade 还提供了一个 @unless 命令：

  1. @unless (Auth::check())
  2.     你尚未登录。
  3. @endunless

除了以上的条件指令之外，@isset 和 @empty 指令也可以视为与 PHP 函数有相同的功能：

  1. @isset($records)
  2.     // $records 被定义并且不为空...
  3. @endisset
  5. @empty($records)
  6.     // $records 是「空」的...
  7. @endempty

身份验证快捷方式

@auth 和 @guest 指令可以用来快速确定当前用户是否已通过身份验证，是否为访客：

  1. @auth
  2.     // 用户已经通过身份认证...
  3. @endauth
  5. @guest
  6.     // 用户没有通过身份认证...
  7. @endguest

Switch 语句

可以使用 @switch、@case、@break、@default 和 @endswitch 指令来构建 Switch 语句：

  1. @switch($i)
  2.     @case(1)
  3.         First case...
  4.         @break
  6.     @case(2)
  7.         Second case...
  8.         @break
  10.     @default
  11.         Default case...
  12. @endswitch

循环

除了条件表达式外，Blade 也支持 PHP 的循环结构。同样，以下这些指令中的每一个都与其 PHP 对应的函数相同：

  1. @for ($i = 0; $i < 10; $i++)
  2.     目前的值为 {{ $i }}
  3. @endfor
  5. @foreach ($users as $user)
  6.     <p>此用户为 {{ $user->id }}</p>
  7. @endforeach
  9. @forelse ($users as $user)
  10.     <li>{{ $user->name }}</li>
  11. @empty
  12.     <p>没有用户</p>
  13. @endforelse
  15. @while (true)
  16.     <p>死循环了。</p>
  17. @endwhile

{tip} 循环时，你可以使用 循环变量 来获取循环的信息，例如是否在循环中进行第一次或最后一次迭代。

当使用循环时，你也可以结束循环或跳过当前迭代：

  1. @foreach ($users as $user)
  2.     @if ($user->type == 1)
  3.         @continue
  4.     @endif
  6.     <li>{{ $user->name }}</li>
  8.     @if ($user->number == 5)
  9.         @break
  10.     @endif
  11. @endforeach

你还可以使用一行代码包含指令声明的条件：

  1. @foreach ($users as $user)
  2.     @continue($user->type == 1)
  4.     <li>{{ $user->name }}</li>
  6.     @break($user->number == 5)
  7. @endforeach

循环变量

循环时，可以在循环内使用 $loop 变量。这个变量可以提供一些有用的信息，比如当前循环的索引，当前循环是不是首次迭代，又或者当前循环是不是最后一次迭代：

  1. @foreach ($users as $user)
  2.     @if ($loop->first)
  3.         这是第一个迭代。
  4.     @endif
  6.     @if ($loop->last)
  7.         这是最后一个迭代。
  8.     @endif
  10.     <p>This is user {{ $user->id }}</p>
  11. @endforeach

在一个嵌套的循环中，可以通过使用 $loop 变量的 parent 属性来获取父循环中的 $loop 变量：

  1. @foreach ($users as $user)
  2.     @foreach ($user->posts as $post)
  3.         @if ($loop->parent->first)
  4.             This is first iteration of the parent loop.
  5.         @endif
  6.     @endforeach
  7. @endforeach

$loop 变量也包含了其它各种有用的属性：

属性 描述
$loop->index 当前循环迭代的索引（从0开始）。
$loop->iteration 当前循环迭代 （从1开始）。
$loop->remaining 循环中剩余迭代数量。
$loop->count 迭代中的数组项目总数。
$loop->first 当前迭代是否是循环中的首次迭代。
$loop->last 当前迭代是否是循环中的最后一次迭代。
$loop->depth 当前循环的嵌套级别。
$loop->parent 在嵌套循环中，父循环的变量。

注释

Blade 也能在视图中定义注释。然而，跟 HTML 的注释不同的，Blade 注释不会被包含在应用程序返回的 HTML 内：

  1. {{-- 此注释将不会出现在渲染后的 HTML --}}

PHP

在某些情况下，将 PHP 代码嵌入到视图中很有用。你可以使用 Blade 的 @php 指令在模板中执行一段纯 PHP 代码：

  1. @php
  2.     //
  3. @endphp

{tip} 虽然 Blade 提供了这个功能，但频繁地使用意味着你的模版被嵌入了太多的逻辑。

引入子视图

你可以使用 Blade 的 @include 命令来引入一个已存在的视图，所有在父视图的可用变量在被引入的视图中都是可用的。

使用 Blade 的 @include 指令可以在 Blade 视图中引入另一个视图。父视图可用的所有变量将提供给引入的视图：

  1. <div>
  2.     @include('shared.errors')
  4.     <form>
  5.         <!-- Form Contents -->
  6.     </form>
  7. </div>

被引入的视图会继承父视图中的所有数据，同时也可以向引入的视图传递额外的数组数据：

  1. @include('view.name', ['some' => 'data'])

当然，如果尝试使用 @include 去引入一个不存在的视图，Laravel 会抛出错误。如果想引入一个可能存在或可能不存在的视图，就使用 @includeIf 指令:

  1. @includeIf('view.name', ['some' => 'data'])

如果要根据给定的布尔条件 @include 视图，可以使用 @includeWhen 指令：

  1. @includeWhen($boolean, 'view.name', ['some' => 'data'])

{note} 请避免在 Blade 视图中使用 __DIR__ 及 __FILE__ 常量，因为它们会引用编译视图时缓存的位置。

为集合渲染视图

你可以使用 Blade 的 @each 命令将循环及引入写成一行代码：

  1. @each('view.name', $jobs, 'job')

第一个参数是对数组或集合中的每个元素进行渲染的部分视图。第二个参数是要迭代的数组或集合，而第三个参数是将被分配给视图中当前迭代的变量名称。举个例子，如果你要迭代一个 jobs 数组，通常会使用子视图中的变量 job 来获取每个 job。当前迭代的 key 将作为子视图中的 key 变量。

你也可以传递第四个参数到 @each 命令。当需要迭代的数组为空时，将会使用这个参数提供的视图来渲染。

  1. @each('view.name', $jobs, 'job', 'view.empty')

{note} 通过 @each 渲染的视图不会从父视图继承变量。 如果子视图需要这些变量，则应该使用 @foreach 和 @include。

堆栈

Blade 可以被推送到在其他视图或布局中的其他位置渲染的命名堆栈。这在子视图中指定所需的 JavaScript 库时非常有用：

  1. @push('scripts')
  2.     <script src="/example.js"></script>
  3. @endpush

你可以根据需要多次压入堆栈，通过 @stack 命令中传递堆栈的名称来渲染完整的堆栈内容：

  1. <head>
  2.     <!-- Head Contents -->
  4.     @stack('scripts')
  5. </head>

服务注入

@inject 命令可用于从 Larvel 服务容器 中检索服务。传递给 @inject 的第一个参数为置放该服务的变量名称，而第二个参数是要解析的服务的类或是接口的名称：

  1. @inject('metrics', 'App\Services\MetricsService')
  3. <div>
  4.     Monthly Revenue: {{ $metrics->monthlyRevenue() }}.
  5. </div>

拓展 Blade

Blade 甚至允许你使用 directive 方法来定义自定义指令。当 Blade 编译器遇到自定义指令时，它将使用指令包含的表达式调用提供的回调。

以下示例创建一个 @datetime($var) 伪指令，该伪指令格式化给定的 DateTime 实例 $var：

  1. <?php
  3. namespace App\Providers;
  5. use Illuminate\Support\Facades\Blade;
  6. use Illuminate\Support\ServiceProvider;
  8. class AppServiceProvider extends ServiceProvider
  9. {
  10.     /**
  11.      * 执行注册后引导服务。
  12.      *
  13.      * @return void
  14.      */
  15.     public function boot()
  16.     {
  17.         Blade::directive('datetime', function ($expression) {
  18.             return "<?php echo ($expression)->format('m/d/Y H:i'); ?>";
  19.         });
  20.     }
  22.     /**
  23.      * 在容器中注册绑定。
  24.      *
  25.      * @return void
  26.      */
  27.     public function register()
  28.     {
  29.         //
  30.     }
  31. }

如你所见，我们可以链式调用在指令中传递的任何表达式的 format 方法。所以，在这个例子里，该指令最终生成了以下 PHP 代码：

  1. <?php echo ($var)->format('m/d/Y H:i'); ?>

{note} 更新 Blade 指令的逻辑后，你需要删除所有已缓存的 Blade 视图。使用 Artisan 命令 view:clear 来清除被缓存的视图。

自定义 If 语句

编写自定义指令有时候比定义简单、常见的条件语句更复杂，但是它又非常必要。因此，Blade 提供了一个 Blade::if 方法，它能使用闭包来快速定义自定义条件指令。 例如，定义一个自定义条件来检查当前的应用程序环境。我们可以在 AppServiceProvider 的 boot 方法中这样做：

  1. use Illuminate\Support\Facades\Blade;
  3. /**
  4.  * Perform post-registration booting of services.
  5.  *
  6.  * @return void
  7.  */
  8. public function boot()
  9. {
  10.     Blade::if('env', function ($environment) {
  11.         return app()->environment($environment);
  12.     });
  13. }

定义了自定义条件之后，就可以很轻松地在模板中使用它：

  1. @env('local')
  2.     // The application is in the local environment...
  3. @else
  4.     // The application is not in the local environment...
  5. @endenv

译者署名

用户名 头像 职能 签名
Wayne John Laravel 的 Blade 模板引擎 - 图1 翻译 基于 Laravel 的社交开源系统 ThinkSNS+ 欢迎 Star。
@JokerLinly Laravel 的 Blade 模板引擎 - 图2 Review Stay Hungry. Stay Foolish.

{note} 欢迎任何形式的转载，但请务必注明出处，尊重他人劳动共创开源社区。

转载请注明：本文档由 Laravel China 社区 laravel-china.org 组织翻译，详见 翻译召集帖。

文档永久地址： https://d.laravel-china.org