# Blade 模板
Blade 是 Laravel 提供的一個簡單而又強大的模板引擎。和其他流行的 PHP 模板引擎不同，Blade 并不限制你在視圖中使用原生 PHP 代碼。所有 Blade 視圖文件都將被編譯成原生的 PHP 代碼并緩存起來，除非它被修改，否則不會重新編譯，這就意味著 Blade 基本上不會給你的應用增加任何負擔。Blade 視圖文件使用`.blade.php`作為文件擴展名，被存放在`resources/views`目錄。
## 模板繼承
### 定義布局
Blade 的兩個主要優點是*模板繼承*和*區塊*。為方便入門，讓我們先通過一個簡單的例子來上手。首先，我們來研究一個「主」頁面布局。因為大多數 web 應用會在不同的頁面中使用相同的布局方式，因此可以很方便地定義單個 Blade 布局視圖：
~~~php
<!-- 保存在 resources/views/layouts/app.blade.php 文件中 -->
<html>
<head>
<title>App Name - @yield('title')</title>
</head>
<body>
@section('sidebar')
This is the master sidebar.
@show
<div class="container">
@yield('content')
</div>
</body>
</html>
~~~
如你所見，該文件包含了典型的 HTML 語法。不過，請注意`@section`和`@yield`指令。`@section`指令定義了視圖的一部分內容，而`@yield`指令是用來顯示指定部分的內容。
現在，我們已經定義好了這個應用程序的布局，接下來，我們定義一個繼承此布局的子頁面。
### 繼承布局
當定義子視圖時，你可以使用 Blade 提供的`@extends`命令來為子視圖指定應該 「繼承」 的布局。 繼承 Blade 布局的視圖可使用`@section`命令將內容注入于布局的`@section`中。而「主」布局中使用`@yield`的地方會顯示這些子視圖中的`@section`間的內容：
~~~php
<!-- 文件保存于 resources/views/child.blade.php -->
@extends('layouts.app')
@section('title', 'Page Title')
@section('sidebar')
@parent
<p>這將追加到主布局的側邊欄。</p>
@endsection
@section('content')
<p>這是主體內容。</p>
@endsection
~~~
在上面的例子里，`@section`中的`sidebar`使用`@parent`命令在「主」布局的`@section('sidebar')`中增加內容（不是覆蓋）。渲染視圖時，`@parent`指令會被替換為「主」布局中`@section('sidebar')`間的內容。
> {tip} 與上一個示例相反，此側邊欄部分以`@endsection`而不是`@show`結尾。`@endsection`指令只定義一個區塊，而`@show`則是定義并立即生成該區塊。
你也可以通過在路由中使用全局輔助函數`view`來返回 Blade 視圖：
~~~php
Route::get('blade', function () {
return view('child');
});
~~~
## Components & Slots
Components 和 slots 類似于布局中的`@section`，但其使用方式更容易被人理解。首先，假設我們有一個能在整個應用中被重復使用的「警告」組件：
~~~php
<!-- /resources/views/alert.blade.php -->
<div class="alert alert-danger">
{{ $slot }}
</div>
~~~
`{{ $slot }}`變量將包含我們希望注入到組件的內容。然后，我們可以使用 Blade 命令`@component`來構建這個組件：
~~~php
@component('alert')
<strong>Whoops!</strong> Something went wrong!
@endcomponent
~~~
有時為組件定義多個 slots 是很有幫助的。現在我們要對「警報」組件進行修改，讓它可以注入「標題」。通過簡單地「打印」匹配其名稱的變量來顯示被命名的`@slot`之間的內容：
~~~php
<!-- /resources/views/alert.blade.php -->
<div class="alert alert-danger">
<div class="alert-title">{{ $title }}</div>
{{ $slot }}
</div>
~~~
現在，我們可以使用`@slot`指令注入內容到已命名的 slot 中，任何沒有被`@slot`指令包裹住的內容將傳遞給組件中的`$slot`變量：
~~~php
@component('alert')
@slot('title')
Forbidden
@endslot
You are not allowed to access this resource!
@endcomponent
~~~
#### 向組件傳遞數據
需要向組件傳遞數據的時候，可以給`@component`指令的第二個參數傳入一個數組。數組中的數據將在組件模版以變量的形式生效：
~~~php
@component('alert', ['foo' => 'bar'])
...
@endcomponent
~~~
#### 組件別名
子目錄中的 Blade 組件，使用別名訪問更方便。現在假設有一個 Blade 組件存儲在`resources/views/components/alert.blade.php`，可以使用`component`方法給它起個`alert`的別名。通常，在`AppServiceProvider`的`boot`方法中完成這個操作：
~~~php
use Illuminate\Support\Facades\Blade;
Blade::component('components.alert', 'alert');
~~~
組件定義好別名后，使用指令渲染：
~~~php
@alert(['type' => 'danger'])
You are not allowed to access this resource!
@endalert
~~~
也可以不傳參數：
~~~php
@alert
You are not allowed to access this resource!
@endalert
~~~
## 顯示數據
傳入 Blade 視圖的數據，通過雙花括號包裹來顯示。例如，給出如下路由：
~~~php
Route::get('greeting', function () {
return view('welcome', ['name' => 'Samantha']);
});
~~~
應該這樣顯示`name`變量的內容：
~~~php
Hello, {{ $name }}.
~~~
當然，不限于顯示傳入視圖的變量內容，還可以輸出 PHP 函數結果。實際上，可以在 Blade echo 語句里放置任何 PHP 代碼：
~~~php
The current UNIX timestamp is {{ time() }}.
~~~
> {tip} Blade`{{ }}`語句會自動調用 PHP 的`htmlspecialchars`函數防止 XSS 攻擊。
#### 顯示未轉義數據
默認情況下，Blade`{{ }}`語句會自動調用 PHP 的`htmlspecialchars`函數防止 XSS 攻擊。不想轉義的話，可以使用以下語法：
~~~php
Hello, {!! $name !!}.
~~~
> {note} 輸出用戶提供的數據時，千萬要小心。對用戶提供的數據，總是要使用雙花括號進行顯示，防止 XSS 攻擊。
#### 渲染 JSON
有時，為了初始化 JavaScript 變量，需要將傳入視圖的數組進行 JSON 化。例如：
~~~php
<script>
var app = <?php echo json_encode($array); ?>;
</script>
~~~
然而，可以用`@json`Blade 指令替代手動`json_encode`：
~~~php
<script>
var app = @json($array);
</script>
~~~
#### HTML 實體轉換
默認情況下， Blade (和 Laravel 的輔助函數`e`) 會將 HTML 全部轉換。要關閉全部轉換，可以在`AppServiceProvider`的`boot`方法里調用`Blade::withoutDoubleEncoding`：
~~~php
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* Bootstrap any application services.
*
* @return void
*/
public function boot()
{
Blade::withoutDoubleEncoding();
}
}
~~~
### Blade & JavaScript 框架
由于許多 JavaScript 框架都使用花括號來表示給定的表達式應用在瀏覽器中顯示，你可以使用`@`符號來告知 Blade 渲染引擎你需要保留這個表達式的原始形態。例如：
~~~php
<h1>Laravel</h1>
Hello, @{{ name }}.
~~~
在這個例子中，`@`符號最終將會被 Blade 引擎刪除；達到不受 Blade 模版引擎影響的目的， 最終`{{ name }}`表達式會保持不變使得 JavaScript 框架可以使用它。
#### `@verbatim`指令
在頁面中如果你需要大部分內容展現 JavaScript 變量，你可以使用`@verbatim`指令來包裹 HTML 內容，這樣你就不必在每個 Blade 打印語句前加上`@`符號：
~~~php
@verbatim
<div class="container">
Hello, {{ name }}.
</div>
@endverbatim
~~~
## 結構控制
除了模板繼承和顯示數據之外， Blade 還提供了常見的 PHP 結構控制語句，比如表達式和循環語句。這些語句與 PHP 語句相似，與其一樣清晰簡明。
### If 語法
你可以使用`@if`、`@elseif`、`@else`和`@endif`指令來構`if`表達式。這些命令的功能等同于 PHP 中的語法：
~~~php
@if (count($records) === 1)
我有一個記錄！
@elseif (count($records) > 1)
我有多個記錄！
@else
我沒有任何記錄！
@endif
~~~
為了方便， Blade 還提供了一個`@unless`指令：
~~~php
@unless (Auth::check())
您還沒有登錄。
@endunless
~~~
除了上述的條件指令之外，`@isset`和`@empty`指令也可以視為與 PHP 函數有相同的功能：
~~~php
@isset($records)
// $records 被定義且不為空...
@endisset
@empty($records)
// $records 是 "empty" 的...
@endempty
~~~
#### 身份驗證快捷方式
`@auth`和`@guest`指令可以用來快速確定當前用戶是否已通過身份驗證，是否為訪客：
~~~php
@auth
// 用戶已通過身份驗證...
@endauth
@guest
// 用戶沒有通過身份驗證...
@endguest
~~~
如果需要，你可以使用`@auth`和`@guest`指令檢查驗證[authentication guard](https://laravel-china.org/docs/laravel/5.7/authentication)：
~~~php
@auth('admin')
// 用戶已通過身份驗證...
@endauth
@guest('admin')
// 用戶未經過身份驗證...
@endguest
~~~
#### 部分指令
你可以使用`@hasSection`指令檢測某個部分是否包含內容：
~~~php
@hasSection('navigation')
<div class="pull-right">
@yield('navigation')
</div>
<div class="clearfix"></div>
@endif
~~~
### Switch 語句
Switch 語句可以通過`@switch`，`@case`，`@break`，`@default`以及`@endswitch`指令來進行構造。
~~~php
@switch($i)
@case(1)
First case...
@break
@case(2)
Second case...
@break
@default
Default case...
@endswitch
~~~
### 循環
除了條件表達式外，Blade 也支持 PHP 的循環結構。同樣，以下這些指令中的每一個都與其 PHP 對應的函數相同：
~~~php
@for ($i = 0; $i < 10; $i++)
The current value is {{ $i }}
@endfor
@foreach ($users as $user)
<p>This is user {{ $user->id }}</p>
@endforeach
@forelse ($users as $user)
<li>{{ $user->name }}</li>
@empty
<p>No users</p>
@endforelse
@while (true)
<p>I'm looping forever.</p>
@endwhile
~~~
> {tip} 循環時，你可以使用[循環變量](https://laravel-china.org/docs/laravel/5.7/blade/2265#the-loop-variable)來獲取循環的相關信息，例如判定你是在循環的首次或者末次迭代中。
使用循環時，你也可以結束循環或跳過當前迭代：
~~~php
@foreach ($users as $user)
@if ($user->type == 1)
@continue
@endif
<li>{{ $user->name }}</li>
@if ($user->number == 5)
@break
@endif
@endforeach
~~~
你也可使用單行指令來包含指令聲明條件：
~~~php
@foreach ($users as $user)
@continue($user->type == 1)
<li>{{ $user->name }}</li>
@break($user->number == 5)
@endforeach
~~~
### 循環變量
循環時，可以在循環內使用`$loop`變量。這個變量可以提供一些有用的信息，比如當前循環的索引，當前循環是否為首次迭代，抑或當前循環是否為末次迭代：
~~~php
@foreach ($users as $user)
@if ($loop->first)
This is the first iteration.
@endif
@if ($loop->last)
This is the last iteration.
@endif
<p>This is user {{ $user->id }}</p>
@endforeach
~~~
在一個嵌套的循環中，可以通過使用`$loop`變量的`parent`屬性來獲取父循環中的`$loop`變量：
~~~php
@foreach ($users as $user)
@foreach ($user->posts as $post)
@if ($loop->parent->first)
This is first iteration of the parent loop.
@endif
@endforeach
@endforeach
~~~
`$loop`變量也包含了其它各種有用的屬性：
| 屬性 | 描述 |
| --- | --- |
| `$loop->index` | 當前循環迭代的索引（從0開始）。 |
| `$loop->iteration` | 當前循環迭代 （從1開始）。 |
| `$loop->remaining` | 循環中剩余迭代數量。 |
| `$loop->count` | 迭代中的數組元素總數。 |
| `$loop->first` | 當前迭代是否為循環中的首次迭代。 |
| `$loop->last` | 當前迭代是否為循環中的末次迭代。 |
| `$loop->depth` | 當前循環的嵌套深度級別。 |
| `$loop->parent` | 在嵌套循環中，父循環的 loop 變量。 |
### 注釋
Blade 也能在視圖中定義注釋。但是，和 HTML 的注釋不同的是，Blade 注釋不會被包含在應用程序返回的 HTML 內：
~~~php
{{-- This comment will not be present in the rendered HTML --}}
~~~
### PHP
在某些情況下，將 PHP 代碼嵌入到視圖中很有用。你可以使用 Blade 的`@php`指令在模板中執行一段純 PHP 代碼：
~~~php
@php
//
@endphp
~~~
> {tip} 雖然 Blade 提供了這個功能，但頻繁地使用意味著你的模版中嵌入了太多的邏輯。
## 引入子視圖
Blade的`@include`指令允許你從另一個視圖中引入 Blade 視圖。所有在父視圖的可用變量在被引入的視圖中都是可用的。
~~~php
<div>
@include('shared.errors')
<form>
<!--表單內容 -->
</form>
</div>
~~~
被引入的視圖會繼承父視圖中的所有數據，同時也可以向引入的視圖傳遞額外的數組數據：
~~~php
@include('view.name', ['some' => 'data'])
~~~
當然，如果嘗試使用`@include`去引入一個不存在的視圖，Laravel 會拋出一個錯誤。如果想引入一個不能確定存在與否的視圖，你應當使用 @includeIf 指令：
~~~php
@includeIf('view.name', ['some' => 'data'])
~~~
如果想根據給定的布爾條件來`@include`一個視圖，你可以使用`@includeWhen`指令：
~~~php
@includeWhen($boolean, 'view.name', ['some' => 'data'])
~~~
如果想引入給定視圖數組中的第一個視圖，你可以使用`includeFirst`指令：
~~~php
@includeFirst(['custom.admin', 'admin'], ['some' => 'data'])
~~~
> {note} 應當盡量避免在 Blade 視圖中使用`__DIR__`和`__FILE__`之類的魔術常量，因它們會引用緩存編譯的視圖路徑。
### 為集合渲染視圖
你可以使用 Blade 的`@each`命令將循環及引入寫成一行代碼：
~~~php
@each('view.name', $jobs, 'job')
~~~
第一個參數是對數組或集合中的每個元素進行渲染的部分視圖。第二個參數是要迭代的數組或集合，而第三個參數是將被分配給視圖中當前迭代的變量名稱。舉個例子，如果你要迭代一個`jobs`數組，通常會使用子視圖中的變量`job`來獲取每個`job`。當前迭代的 key 將作為子視圖中的`key`變量。
你可以在`@each`指令中傳入第四個參數。當需要迭代的數組為空時，將會使用這個參數提供的視圖來渲染。
~~~php
@each('view.name', $jobs, 'job', 'view.empty')
~~~
> {note}通過`@each`渲染的視圖不會從父視圖繼承變量。 如果子視圖需要這些變量，則應該使用`@foreach`和`@include`。
## 堆棧
Blade 允許你將數據壓入命名堆棧中，這些堆棧可以在其他視圖或者布局中再進行渲染。這在子視圖中指定所需的 JavaScript 庫時非常有用：
~~~php
@push('scripts')
<script src="/example.js"></script>
@endpush
~~~
你可以按需多次壓棧，通過`@stack`命令中傳遞堆棧的名稱來渲染完整的堆棧內容：
~~~php
<head>
<!-- 頭部內容 -->
@stack('scripts')
</head>
~~~
如果想將內容放置在棧頂，你應當使用`@prepend`指令：
~~~php
@push('scripts')
這里將會排在第二……
@endpush
// 然后……
@prepend('scripts')
此處將會排在第一
@endprepend
~~~
## 服務注入
`@inject`指令可從 Laravel[服務容器](https://laravel-china.org/docs/laravel/5.7/container)中檢索服務。`@inject`指令的第一個參數用于存放服務名稱，第二個參數則為需要解析的類或者接口名稱：
~~~php
@inject('metrics', 'App\Services\MetricsService')
<div>
Monthly Revenue: {{ $metrics->monthlyRevenue() }}.
</div>
~~~
## 拓展 Blade
Blade 甚至允許你使用`directive`方法來自定義指令。當 Blade 編譯器遇到自定義指令時，它將使用指令包含的表達式調用提供的回調。
以下示例創建一個`@datetime($var)`偽指令，該偽指令格式化給定的`DateTime`實例`$var`：
~~~php
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* 執行注冊后引導服務。
*
* @return void
*/
public function boot()
{
Blade::directive('datetime', function ($expression) {
return "<?php echo ($expression)->format('m/d/Y H:i'); ?>";
});
}
/**
* 在容器中注冊綁定。
*
* @return void
*/
public function register()
{
//
}
}
~~~
如你所見，我們可以鏈式調用在指令中傳遞的任何表達式的`format`方法。所以，在這個例子里，該指令最終生成了以下 PHP 代碼：
~~~php
<?php echo ($var)->format('m/d/Y H:i'); ?>
~~~
> {note} 更新 Blade 指令的邏輯后，你需要刪除所有已緩存的 Blade 視圖。使用 Artisan 指令`view:clear`來清除被緩存的視圖。
### 自定義 If 語句
編寫自定義指令有時候比定義簡單、常見的條件語句更復雜，但是它非常必要。因此，Blade 提供了一個`Blade::if`方法，它能使用閉包來快速定義自定義條件指令。例如，定義一個自定義條件來檢查當前的應用程序環境。我們可以在`AppServiceProvider`的`boot`方法中這樣做：
~~~php
use Illuminate\Support\Facades\Blade;
/**
* 執行服務的注冊后引導。
*
* @return void
*/
public function boot()
{
Blade::if('env', function ($environment) {
return app()->environment($environment);
});
}
~~~
一旦你定義了自定義條件之后，就可以很輕松地在模板中使用它：
~~~php
@env('local')
// 該應用在本地環境中...
@elseenv('testing')
// 該應用在測試環境中...
@else
// 該應用不在本地或測試環境中...
@endenv
~~~
