Blade 模板 · Laravel 5.6 中文文檔

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