Appearance
Blade 模板
简介
Blade 是 Laravel 中包含的简单而强大的模板引擎。与一些 PHP 模板引擎不同,Blade 不会限制您在模板中使用纯 PHP 代码。事实上,所有 Blade 模板都会被编译成纯 PHP 代码并缓存,直到被修改为止,这意味着 Blade 几乎不会给您的应用程序增加任何开销。Blade 模板文件使用 .blade.php
文件扩展名,通常存储在 resources/views
目录中。
Blade 视图可以从路由或控制器中使用全局 view
辅助函数返回。当然,如视图文档中所述,可以使用 view
辅助函数的第二个参数将数据传递给 Blade 视图:
php
Route::get('/', function () {
return view('greeting', ['name' => 'Finn']);
});
使用 Livewire 增强 Blade
想要将 Blade 模板提升到下一个水平并轻松构建动态界面吗?查看 Laravel Livewire。Livewire 允许您编写增强了动态功能的 Blade 组件,这些功能通常只能通过前端框架(如 React 或 Vue)实现,提供了一种构建现代、响应式前端的好方法,而无需处理许多 JavaScript 框架的复杂性、客户端渲染或构建步骤。
显示数据
您可以使用花括号包裹变量来显示传递给 Blade 视图的数据。例如,给定以下路由:
php
Route::get('/', function () {
return view('welcome', ['name' => 'Samantha']);
});
您可以这样显示 name
变量的内容:
blade
Hello, {{ $name }}.
NOTE
Blade 的 echo 语句会自动通过 PHP 的
htmlspecialchars
函数进行处理,以防止 XSS 攻击。
您不仅限于显示传递给视图的变量的内容。您还可以回显任何 PHP 函数的结果。事实上,您可以在 Blade echo 语句中放置任何您想要的 PHP 代码:
blade
The current UNIX timestamp is {{ time() }}.
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.
*/
public function boot(): void
{
Blade::withoutDoubleEncoding();
}
}
显示未转义的数据
默认情况下,Blade 语句会自动通过 PHP 的
htmlspecialchars
函数进行处理,以防止 XSS 攻击。如果您不想对数据进行转义,可以使用以下语法:
blade
Hello, {!! $name !!}.
WARNING
当显示应用程序用户提供的内容时,请务必非常小心。您通常应该使用转义的双花括号语法来防止 XSS 攻击,而显示用户提供的数据。
Blade 与 JavaScript 框架
由于许多 JavaScript 框架也使用 "花括号" 来表示应该在浏览器中显示的给定表达式,您可以使用 @
符号告知 Blade 渲染引擎某个表达式应保持不变。例如:
blade
<h1>Laravel</h1>
Hello, @{{ name }}.
在此示例中,@
符号将被 Blade 移除;但是, 表达式将保持不变,由您的 JavaScript 框架进行渲染。
@
符号还可用于转义 Blade 指令:
blade
{{-- Blade template --}}
@@if()
<!-- HTML output -->
@if()
渲染 JSON
有时您可能会将数组传递给视图,并希望将其渲染为 JSON,以初始化 JavaScript 变量。例如:
blade
<script>
var app = <?php echo json_encode($array); ?>;
</script>
但是,您可以使用 Illuminate\Support\Js::from
方法指令代替手动调用 json_encode
。from
方法接受与 PHP 的 json_encode
函数相同的参数;但是,它会确保生成的 JSON 正确转义以便包含在 HTML 引号中。from
方法将返回一个字符串 JSON.parse
JavaScript 语句,该语句将把给定的对象或数组转换为有效的 JavaScript 对象:
blade
<script>
var app = {{ Illuminate\Support\Js::from($array) }};
</script>
最新版本的 Laravel 应用程序骨架包括一个 Js
门面,它在您的 Blade 模板中提供了方便的访问此功能:
blade
<script>
var app = {{ Js::from($array) }};
</script>
WARNING
您应该只使用 Js::from
方法来渲染现有变量为 JSON。Blade 模板基于正则表达式,尝试将复杂表达式传递给指令可能会导致意外失败。
@verbatim
指令
如果您在模板的大部分内容中显示 JavaScript 变量,您可以使用 @verbatim
指令将 HTML 包裹起来,这样就不必在每个 Blade echo 语句前加上 @
符号:
blade
@verbatim
<div class="container">
Hello, {{ name }}.
</div>
@endverbatim
Blade 指令
除了模板继承和显示数据之外,Blade 还提供了方便的快捷方式,用于常见的 PHP 控制结构,例如条件语句和循环。这些快捷方式提供了一种非常清晰、简洁的方式来处理 PHP 控制结构,同时仍然与它们的 PHP 对应物保持一致。
If 语句
您可以使用 @if
、@elseif
、@else
和 @endif
指令构建 if
语句。这些指令的功能与它们的 PHP 对应物完全相同:
blade
@if (count($records) === 1)
I have one record!
@elseif (count($records) > 1)
I have multiple records!
@else
I don't have any records!
@endif
为了方便起见,Blade 还提供了一个 @unless
指令:
blade
@unless (Auth::check())
You are not signed in.
@endunless
除了已经讨论过的条件指令之外,@isset
和 @empty
指令可用作它们各自 PHP 函数的便捷快捷方式:
blade
@isset($records)
// $records is defined and is not null...
@endisset
@empty($records)
// $records is "empty"...
@endempty
身份验证指令
@auth
和 @guest
指令可用于快速确定当前用户是否已身份验证或是游客:
blade
@auth
// The user is authenticated...
@endauth
@guest
// The user is not authenticated...
@endguest
如果需要,您可以指定在使用 @auth
和 @guest
指令时应检查的身份验证守卫:
blade
@auth('admin')
// The user is authenticated...
@endauth
@guest('admin')
// The user is not authenticated...
@endguest
环境指令
您可以使用 @production
指令检查应用程序是否在生产环境中运行:
blade
@production
// Production specific content...
@endproduction
或者,您可以使用 @env
指令确定应用程序是否在特定环境中运行:
blade
@env('staging')
// The application is running in "staging"...
@endenv
@env(['staging', 'production'])
// The application is running in "staging" or "production"...
@endenv
部分指令
您可以使用 @hasSection
指令确定模板继承部分是否有内容:
blade
@hasSection('navigation')
<div class="pull-right">
@yield('navigation')
</div>
<div class="clearfix"></div>
@endif
您还可以使用 sectionMissing
指令确定某个部分是否没有内容:
blade
@sectionMissing('navigation')
<div class="pull-right">
@include('default-navigation')
</div>
@endif
会话指令
@session
指令可用于确定是否存在会话值。如果会话值存在,则 @session
和 @endsession
指令内的模板内容将被评估。在 @session
指令的内容中,您可以回显 $value
变量来显示会话值:
blade
@session('status')
<div class="p-4 bg-green-100">
{{ $value }}
</div>
@endsession
Switch 语句
可以使用 @switch
、@case
、@break
、@default
和 @endswitch
指令构建 switch 语句:
blade
@switch($i)
@case(1)
First case...
@break
@case(2)
Second case...
@break
@default
Default case...
@endswitch
循环
除了条件语句之外,Blade 还提供了简单的指令来处理 PHP 的循环结构。同样,每个指令的功能与它们的 PHP 对应物完全相同:
blade
@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
NOTE
在 foreach
循环中迭代时,您可以使用循环变量获取有关循环的有用信息,例如这是否是循环的第一次或最后一次迭代。
在使用循环时,您还可以使用 @continue
和 @break
指令跳过当前迭代或结束循环:
blade
@foreach ($users as $user)
@if ($user->type == 1)
@continue
@endif
<li>{{ $user->name }}</li>
@if ($user->number == 5)
@break
@endif
@endforeach
您还可以在指令声明中包含继续或中断条件:
blade
@foreach ($users as $user)
@continue($user->type == 1)
<li>{{ $user->name }}</li>
@break($user->number == 5)
@endforeach
循环变量
在 foreach
循环中,将在循环内部可用一个 $loop
变量。此变量提供对一些有用的信息的访问,例如当前循环索引以及这是否是循环的第一次或最后一次迭代:
blade
@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
如果您在嵌套循环中,可以通过 parent
属性访问父循环的 $loop
变量:
blade
@foreach ($users as $user)
@foreach ($user->posts as $post)
@if ($loop->parent->first)
This is the 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->even | 这是否是循环的偶数次迭代。 |
$loop->odd | 这是否是循环的奇数次迭代。 |
$loop->depth | 当前循环的嵌套级别。 |
$loop->parent | 在嵌套循环中,父循环的循环变量。 |
条件类和样式
@class
指令有条件地编译 CSS 类字符串。该指令接受一个类数组,其中数组键包含您希望添加的类或类,而值是布尔表达式。如果数组元素有数字键,它将始终包含在渲染的类列表中:
blade
@php
$isActive = false;
$hasError = true;
@endphp
<span @class([
'p-4',
'font-bold' => $isActive,
'text-gray-500' => ! $isActive,
'bg-red' => $hasError,
])></span>
<span class="p-4 text-gray-500 bg-red"></span>
同样,@style
指令可用于有条件地向 HTML 元素添加内联 CSS 样式:
blade
@php
$isActive = true;
@endphp
<span @style([
'background-color: red',
'font-weight: bold' => $isActive,
])></span>
<span style="background-color: red; font-weight: bold;"></span>
附加属性
为了方便起见,您可以使用 @checked
指令轻松指示给定的 HTML 复选框输入是否被"选中"。如果提供的条件评估为 true
,此指令将回显 checked
:
blade
<input type="checkbox"
name="active"
value="active"
@checked(old('active', $user->active)) />
同样,@selected
指令可用于指示给定的选择选项是否应该被"选中":
blade
<select name="version">
@foreach ($product->versions as $version)
<option value="{{ $version }}" @selected(old('version') == $version)>
{{ $version }}
</option>
@endforeach
</select>
此外,@disabled
指令可用于指示给定元素是否应该被"禁用":
blade
<button type="submit" @disabled($errors->isNotEmpty())>Submit</button>
此外,@readonly
指令可用于指示给定元素是否应该是"只读"的:
blade
<input type="email"
name="email"
value="email@laravel.com"
@readonly($user->isNotAdmin()) />
此外,@required
指令可用于指示给定元素是否应该是"必需"的:
blade
<input type="text"
name="title"
value="title"
@required($user->isAdmin()) />
包含子视图
NOTE
虽然您可以使用 @include
指令,但 Blade 组件提供了类似的功能,并且相对于 @include
指令具有几个优点,例如数据和属性绑定。
Blade 的 @include
指令允许您在另一个视图中包含 Blade 视图。所有在父视图中可用的变量也将在包含的视图中可用:
blade
<div>
@include('shared.errors')
<form>
<!-- Form Contents -->
</form>
</div>
即使包含的视图将继承所有父视图中可用的数据,您还可以传递一个附加数据数组,该数组应在包含的视图中可用:
blade
@include('view.name', ['status' => 'complete'])
如果您尝试 @include
一个不存在的视图,Laravel 将抛出错误。如果您希望包含一个可能存在或不存在的视图,您应该使用 @includeIf
指令:
blade
@includeIf('view.name', ['status' => 'complete'])
如果您希望在给定的布尔表达式评估为 true
或 false
时 @include
一个视图,您可以使用 @includeWhen
和 @includeUnless
指令:
blade
@includeWhen($boolean, 'view.name', ['status' => 'complete'])
@includeUnless($boolean, 'view.name', ['status' => 'complete'])
要包含给定视图数组中第一个存在的视图,您可以使用 includeFirst
指令:
blade
@includeFirst(['custom.admin', 'admin'], ['status' => 'complete'])
WARNING
您应该避免在 Blade 视图中使用 __DIR__
和 __FILE__
常量,因为它们将引用缓存的编译视图的位置。
为集合渲染视图
您可以使用 Blade 的 @each
指令将循环和包含合并为一行:
blade
@each('view.name', $jobs, 'job')
@each
指令的第一个参数是要为数组或集合中的每个元素渲染的视图。第二个参数是您希望迭代的数组或集合,而第三个参数是将在视图中分配给当前迭代的变量名称。因此,例如,如果您正在迭代一个 jobs
数组,通常您会希望将每个作业作为视图中的 job
变量访问。数组的键将在视图中作为 key
变量可用。
您还可以向 @each
指令传递第四个参数。此参数确定给定数组为空时要渲染的视图。
blade
@each('view.name', $jobs, 'job', 'view.empty')
WARNING
通过 @each
渲染的视图不会继承父视图的变量。如果子视图需要这些变量,您应该使用 @foreach
和 @include
指令。
@once
指令
@once
指令允许您定义一部分模板,该部分只会在每次渲染周期中评估一次。当您在循环中渲染给定的组件时,这可能会很有用。例如,您可能希望只在第一次渲染组件时将 JavaScript 推送到页面的头部:
blade
@once
@push('scripts')
<script>
// Your custom JavaScript...
</script>
@endpush
@endonce
由于 @once
指令通常与 @push
或 @prepend
指令一起使用,因此还提供了 @pushOnce
和 @prependOnce
指令供您方便使用:
blade
@pushOnce('scripts')
<script>
// Your custom JavaScript...
</script>
@endPushOnce
原始 PHP
在某些情况下,将 PHP 代码嵌入到您的视图中是有用的。您可以使用 Blade @php
指令在模板中执行一块纯 PHP:
blade
@php
$counter = 1;
@endphp
或者,如果您只需要使用 PHP 来导入一个类,您可以使用 @use
指令:
blade
@use('App\Models\Flight')
@use
指令的第二个参数可用于别名导入的类:
php
@use('App\Models\Flight', 'FlightModel')
注释
Blade 还允许您在视图中定义注释。但是,与 HTML 注释不同,Blade 注释不会包含在应用程序返回的 HTML 中:
blade
{{-- This comment will not be present in the rendered HTML --}}
组件
组件和插槽提供了与部分、布局和包含类似的好处;但是,有些人可能会发现组件和插槽的心智模型更容易理解。有两种编写组件的方法:基于类的组件和匿名组件。
要创建基于类的组件,您可以使用 make:component
Artisan 命令。为了说明如何使用组件,我们将创建一个简单的 Alert
组件。make:component
命令将把组件放在 app/View/Components
目录中:
shell
php artisan make:component Alert
make:component
命令还将为组件创建一个视图模板。该视图将放在 resources/views/components
目录中。当为您自己的应用程序编写组件时,组件会自动在 app/View/Components
目录和 resources/views/components
目录中发现,因此通常不需要进行任何其他组件注册。
您还可以在子目录中创建组件:
shell
php artisan make:component Forms/Input
上面的命令将在 app/View/Components/Forms
目录中创建一个 Input
组件,并且视图将放在 resources/views/components/forms
目录中。
如果您想创建匿名组件(只有 Blade 模板而没有类的组件),您可以在调用 make:component
命令时使用 --view
标志:
shell
php artisan make:component forms.input --view
上面的命令将在 resources/views/components/forms/input.blade.php
创建一个 Blade 文件,该文件可以作为组件渲染 <x-forms.input />
。
手动注册包组件
当为您自己的应用程序编写组件时,组件会自动在 app/View/Components
目录和 resources/views/components
目录中发现。
但是,如果您正在构建一个使用 Blade 组件的包,您将需要手动注册您的组件类和其 HTML 标签别名。您通常应该在包的服务提供者的 boot
方法中注册您的组件:
php
use Illuminate\Support\Facades\Blade;
/**
* Bootstrap your package's services.
*/
public function boot(): void
{
Blade::component('package-alert', Alert::class);
}
一旦您的组件已注册,它就可以使用其标签别名进行渲染:
blade
<x-package-alert/>
或者,您可以使用 componentNamespace
方法按约定自动加载组件类。例如,一个名为 Nightshade
的包可能有 Calendar
和 ColorPicker
组件,它们位于 Package\Views\Components
命名空间中:
php
use Illuminate\Support\Facades\Blade;
/**
* Bootstrap your package's services.
*/
public function boot(): void
{
Blade::componentNamespace('Nightshade\\Views\\Components', 'nightshade');
}
这将允许使用包组件的供应商命名空间使用 package-name::
语法:
blade
<x-nightshade::calendar />
<x-nightshade::color-picker />
Blade 将自动检测与此组件链接的类,使用组件名称的 Pascal 大小写。子目录也支持使用 "点" 表示法。
渲染组件
要显示组件,您可以在 Blade 模板中使用 Blade 组件标签。Blade 组件标签以字符串 x-
开头,后跟组件类的 kebab case 名称:
blade
<x-alert/>
<x-user-profile/>
如果组件类在 app/View/Components
目录中更深层,您可以使用 .
字符来表示目录嵌套。例如,如果我们假设一个组件位于 app/View/Components/Inputs/Button.php
,我们可以这样渲染它:
blade
<x-inputs.button/>
如果您想有条件地渲染组件,您可以在组件类上定义一个 shouldRender
方法。如果 shouldRender
方法返回 false
,组件将不会被渲染:
php
use Illuminate\Support\Str;
/**
* Whether the component should be rendered
*/
public function shouldRender(): bool
{
return Str::length($this->message) > 0;
}
传递数据给组件
您可以使用 HTML 属性将数据传递给 Blade 组件。硬编码的原始值可以使用简单的 HTML 属性字符串传递给组件。PHP 表达式和变量应该通过使用 :
字符作为前缀的属性传递给组件:
blade
<x-alert type="error" :message="$message"/>
您应该在组件的类构造函数中定义所有组件的数据属性。组件的所有公共属性都将自动在组件的视图中可用。不需要将数据传递给组件的 render
方法:
php
<?php
namespace App\View\Components;
use Illuminate\View\Component;
use Illuminate\View\View;
class Alert extends Component
{
/**
* Create the component instance.
*/
public function __construct(
public string $type,
public string $message,
) {}
/**
* Get the view / contents that represent the component.
*/
public function render(): View
{
return view('components.alert');
}
}
当您的组件被渲染时,您可以通过回显组件的公共变量的内容来显示组件的内容:
blade
<div class="alert alert-{{ $type }}">
{{ $message }}
</div>
大小写
组件构造函数参数应该使用 camelCase
,而 kebab-case
应该用于引用属性名称。例如,给定以下组件构造函数:
php
/**
* Create the component instance.
*/
public function __construct(
public string $alertType,
) {}
可以这样提供 $alertType
参数:
blade
<x-alert alert-type="danger" />
简短属性语法
传递属性给组件时,您还可以使用 "简短属性" 语法。这通常很方便,因为属性名称经常与它们对应的变量名称相匹配:
blade
{{-- 简短属性语法... --}}
<x-profile :$userId :$name />
{{-- 等同于... --}}
<x-profile :user-id="$userId" :name="$name" />
转义属性渲染
由于一些 JavaScript 框架(如 Alpine.js)也使用冒号前缀的属性,您可以使用双冒号 (::
) 前缀告知 Blade 该属性不是 PHP 表达式。例如,给定以下组件:
blade
<x-button ::class="{ danger: isDeleting }">
Submit
</x-button>
Blade 将渲染以下 HTML:
blade
<button :class="{ danger: isDeleting }">
Submit
</button>
组件方法
除了公共变量可用于组件模板之外,组件的任何公共方法也可以被调用。例如,假设一个组件有一个 isSelected
方法:
php
/**
* Determine if the given option is the currently selected option.
*/
public function isSelected(string $option): bool
{
return $option === $this->selected;
}
您可以从组件模板中执行此方法,方法是调用与方法名称匹配的变量:
blade
<option {{ $isSelected($value) ? 'selected' : '' }} value="{{ $value }}">
{{ $label }}
</option>
在组件类中访问属性和插槽
Blade 组件还允许您在组件类的 render
方法中访问组件名称、属性和插槽。但是,为了访问这些数据,您应该从组件的 render
方法返回一个闭包:
php
use Closure;
/**
* Get the view / contents that represent the component.
*/
public function render(): Closure
{
return function () {
return '<div {{ $attributes }}>Components content</div>';
};
}
返回给组件的 render
方法的闭包还可以接收一个 $data
数组作为其唯一参数。此数组将包含几个元素,提供有关组件的信息:
php
return function (array $data) {
// $data['componentName'];
// $data['attributes'];
// $data['slot'];
return '<div {{ $attributes }}>Components content</div>';
}
WARNING
$data
数组中的元素永远不应该直接嵌入到 render
方法返回的 Blade 字符串中,因为这可能会允许远程代码执行通过恶意属性内容。
闭包返回的字符串应该是一个字符串。如果返回的字符串对应于一个现有的视图,那么该视图将被渲染;否则,返回的字符串将被评估为一个内联 Blade 视图。
附加依赖
如果您的组件需要从 Laravel 的服务容器中获取依赖项,您可以在组件的任何数据属性之前列出它们,它们将由容器自动注入:
php
use App\Services\AlertCreator;
/**
* Create the component instance.
*/
public function __construct(
public AlertCreator $creator,
public string $type,
public string $message,
) {}
隐藏属性/方法
如果您想阻止一些公共方法或属性作为变量暴露给组件模板,您可以将它们添加到组件的 $except
数组属性中:
php
<?php
namespace App\View\Components;
use Illuminate\View\Component;
class Alert extends Component
{
/**
* The properties / methods that should not be exposed to the component template.
*
* @var array
*/
protected $except = ['type'];
/**
* Create the component instance.
*/
public function __construct(
public string $type,
) {}
}
组件属性
我们已经讨论过如何传递数据属性给组件;但是,有时您可能需要指定其他 HTML 属性,例如 class
,这些属性不是组件功能所需的一部分。通常,您希望将这些附加属性传递给组件模板的根元素。例如,假设我们想要以这种方式渲染一个 alert
组件:
blade
<x-alert type="error" :message="$message" class="mt-4"/>
所有不是组件构造函数的一部分的属性都将自动添加到组件的 "属性包" 中。此属性包将自动在组件的 $attributes
变量中可用。所有属性都可以在组件中回显此变量:
blade
<div {{ $attributes }}>
<!-- Component content -->
</div>
WARNING
在组件标签中使用指令(如 @env
)目前不受支持。例如,<x-alert :live="@env('production')"/>
将不会被编译。
默认/合并属性
有时您可能需要为属性指定默认值或将一些属性的值合并到其他属性中。为此,您可以使用属性包的 merge
方法。此方法特别有用于定义应始终应用于组件的一组默认 CSS 类:
blade
<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
{{ $message }}
</div>
如果我们假设这个组件被这样使用:
blade
<x-alert type="error" :message="$message" class="mb-4"/>
组件的最终渲染 HTML 将如下所示:
blade
<div class="alert alert-error mb-4">
<!-- Contents of the $message variable -->
</div>
有条件合并类
有时您可能希望在给定条件为 true
时合并类。您可以使用 class
方法来实现这一点,该方法接受一个类数组,其中数组键包含您希望添加的类或类,而值是一个布尔表达式。如果数组元素有数字键,它将始终包含在渲染的类列表中:
blade
<div {{ $attributes->class(['p-4', 'bg-red' => $hasError]) }}>
{{ $message }}
</div>
如果您需要将其他属性合并到组件中,您可以将 merge
方法链接到 class
方法:
blade
<button {{ $attributes->class(['p-4'])->merge(['type' => 'button']) }}>
{{ $slot }}
</button>
NOTE
如果您需要在不应该接收合并属性的其他 HTML 元素上有条件地编译类,您可以使用 @class
指令。
非类属性合并
当合并不是 class
属性的属性时,merge
方法提供的值将被视为该属性的 "默认" 值。但是,与 class
属性不同,这些属性不会与注入的属性值合并。相反,它们将被覆盖。例如,button
组件的实现可能如下所示:
blade
<button {{ $attributes->merge(['type' => 'button']) }}>
{{ $slot }}
</button>
要以自定义 type
渲染按钮组件,它可以在使用组件时指定。如果未指定类型,将使用 button
类型:
blade
<x-button type="submit">
Submit
</x-button>
如果您想要一个属性(而不是 class
)的默认值和注入的值连接在一起,您可以使用 prepends
方法。在此示例中,data-controller
属性将始终以 profile-controller
开头,并且任何附加的注入 data-controller
值将放置在此默认值之后:
blade
<div {{ $attributes->merge(['data-controller' => $attributes->prepends('profile-controller')]) }}>
{{ $slot }}
</div>
检索和过滤属性
您可以使用 filter
方法过滤属性。此方法接受一个闭包,如果您希望在属性包中保留该属性,该闭包应返回 true
:
blade
{{ $attributes->filter(fn (string $value, string $key) => $key == 'foo') }}
为方便起见,您可以使用 whereStartsWith
方法检索所有以给定字符串开头的键的属性:
blade
{{ $attributes->whereStartsWith('wire:model') }}
相反,whereDoesntStartWith
方法可用于排除所有以给定字符串开头的键的属性:
blade
{{ $attributes->whereDoesntStartWith('wire:model') }}
使用 first
方法,您可以渲染给定属性包中的第一个属性:
blade
{{ $attributes->whereStartsWith('wire:model')->first() }}
如果您想检查组件上是否存在某个属性,您可以使用 has
方法。此方法接受属性名称作为其唯一参数,并返回一个布尔值,指示组件上是否存在该属性:
blade
@if ($attributes->has('class'))
<div>Class attribute is present</div>
@endif
如果传递给 has
方法的是一个数组,该方法将确定组件上是否存在所有给定的属性:
blade
@if ($attributes->has(['name', 'class']))
<div>All of the attributes are present</div>
@endif
hasAny
方法可用于确定组件上是否存在任何给定的属性:
blade
@if ($attributes->hasAny(['href', ':href', 'v-bind:href']))
<div>One of the attributes is present</div>
@endif
您可以使用 get
方法检索特定属性的值:
blade
{{ $attributes->get('class') }}
保留关键字
默认情况下,一些关键字是 Blade 内部使用的,用于渲染组件。以下关键字不能在组件中定义为公共属性或方法名称:
data
render
resolveView
shouldRender
view
withAttributes
withName
插槽
您通常需要通过 "插槽" 将额外的内容传递给组件。组件插槽由回显 $slot
变量来渲染。为了探讨这个概念,让我们想象一个 alert
组件有以下标记:
blade
<!-- /resources/views/components/alert.blade.php -->
<div class="alert alert-danger">
{{ $slot }}
</div>
我们可以通过将内容注入组件来传递内容给 slot
:
blade
<x-alert>
<strong>Whoops!</strong> Something went wrong!
</x-alert>
有时,一个组件可能需要在组件的不同位置渲染多个不同的插槽。让我们修改我们的警报组件,以允许注入 "标题" 插槽:
blade
<!-- /resources/views/components/alert.blade.php -->
<span class="alert-title">{{ $title }}</span>
<div class="alert alert-danger">
{{ $slot }}
</div>
您可以使用 x-slot
标签定义命名插槽的内容。任何不在显式 x-slot
标签中的内容都将作为 $slot
变量传递给组件:
xml
<x-alert>
<x-slot:title>
Server Error
</x-slot>
<strong>Whoops!</strong> Something went wrong!
</x-alert>
您可以调用插槽的 isEmpty
方法来确定插槽是否包含内容:
blade
<span class="alert-title">{{ $title }}</span>
<div class="alert alert-danger">
@if ($slot->isEmpty())
This is default content if the slot is empty.
@else
{{ $slot }}
@endif
</div>
此外,hasActualContent
方法可用于确定插槽是否包含任何 "实际" 内容,而不是 HTML 注释:
blade
@if ($slot->hasActualContent())
The scope has non-comment content.
@endif
作用域插槽
如果您使用过像 Vue 这样的 JavaScript 框架,您可能熟悉 "作用域插槽",它允许您在插槽中访问组件的数据或方法。您可以在 Laravel 中实现类似的行为,方法是在组件上定义公共方法或属性,并在插槽中通过 $component
变量访问组件:在此示例中,我们将假设 x-alert
组件在其组件类上有一个公共的 formatAlert
方法:
blade
<x-alert>
<x-slot:title>
{{ $component->formatAlert('Server Error') }}
</x-slot>
<strong>Whoops!</strong> Something went wrong!
</x-alert>
插槽属性
与 Blade 组件一样,您可以为插槽分配其他属性,例如 CSS 类名:
xml
<x-card class="shadow-sm">
<x-slot:heading class="font-bold">
Heading
</x-slot>
Content
<x-slot:footer class="text-sm">
Footer
</x-slot>
</x-card>
要与插槽属性交互,您可以访问插槽变量的 attributes
属性。有关如何与属性交互的更多信息,请参阅组件属性文档:
blade
@props([
'heading',
'footer',
])
<div {{ $attributes->class(['border']) }}>
<h1 {{ $heading->attributes->class(['text-lg']) }}>
{{ $heading }}
</h1>
{{ $slot }}
<footer {{ $footer->attributes->class(['text-gray-700']) }}>
{{ $footer }}
</footer>
</div>
内联组件视图
对于非常小的组件,管理组件类和组件的视图模板可能会感到麻烦。因此,您可以直接从 render
方法返回组件的标记:
php
/**
* Get the view / contents that represent the component.
*/
public function render(): string
{
return <<<'blade'
<div class="alert alert-danger">
{{ $slot }}
</div>
blade;
}
生成内联视图组件
要创建一个渲染内联视图的组件,您可以在执行 make:component
命令时使用 inline
选项:
shell
php artisan make:component Alert --inline
动态组件
有时您可能需要渲染一个组件,但不知道应该渲染哪个组件直到运行时。在这种情况下,您可以使用 Laravel 的内置 dynamic-component
组件,根据运行时值或变量渲染组件:
blade
// $componentName = "secondary-button";
<x-dynamic-component :component="$componentName" class="mt-4" />
手动注册组件
WARNING
以下有关手动注册组件的文档主要适用于那些正在编写 Laravel 包并包含视图组件的人。如果您不是在编写包,此部分组件文档可能与您无关。
当为您自己的应用程序编写组件时,组件会自动在 app/View/Components
目录和 resources/views/components
目录中发现。
但是,如果您正在构建一个使用 Blade 组件的包或将组件放在非常规目录中,您将需要手动注册您的组件类和其 HTML 标签别名,以便 Laravel 知道在哪里找到该组件。您通常应该在包的服务提供者的 boot
方法中注册您的组件:
php
use Illuminate\Support\Facades\Blade;
use VendorPackage\View\Components\AlertComponent;
/**
* Bootstrap your package's services.
*/
public function boot(): void
{
Blade::component('package-alert', AlertComponent::class);
}
一旦您的组件已注册,它就可以使用其标签别名进行渲染:
blade
<x-package-alert/>
自动加载包组件
或者,您可以使用 componentNamespace
方法按约定自动加载组件类。例如,一个名为 Nightshade
的包可能有 Calendar
和 ColorPicker
组件,它们位于 Package\Views\Components
命名空间中:
php
use Illuminate\Support\Facades\Blade;
/**
* Bootstrap your package's services.
*/
public function boot(): void
{
Blade::componentNamespace('Nightshade\\Views\\Components', 'nightshade');
}
这将允许使用包组件的供应商命名空间使用 package-name::
语法:
blade
<x-nightshade::calendar />
<x-nightshade::color-picker />
Blade 将自动检测与此组件链接的类,使用组件名称的 Pascal 大小写。子目录也支持使用 "点" 表示法。
匿名组件
与内联组件类似,匿名组件提供了一种通过单个文件管理组件的机制。但是,匿名组件仅使用单个视图文件,没有相关的类。要定义匿名组件,您只需要在 resources/views/components
目录中放置一个 Blade 模板。例如,假设您在 resources/views/components/alert.blade.php
定义了一个组件,您可以这样渲染它:
blade
<x-alert/>
您可以使用 .
字符来指示组件是否嵌套在 components
目录内。例如,假设组件定义在 resources/views/components/inputs/button.blade.php
,您可以这样渲染它:
blade
<x-inputs.button/>
匿名索引组件
有时,当一个组件由许多 Blade 模板组成时,您可能希望将给定组件的模板分组在一个单独的目录中。例如,假设一个 "accordion" 组件有以下目录结构:
php
/resources/views/components/accordion.blade.php
/resources/views/components/accordion/item.blade.php
这个目录结构允许您这样渲染 accordion 组件和它的 item:
blade
<x-accordion>
<x-accordion.item>
...
</x-accordion.item>
</x-accordion>
但是,为了通过 x-accordion
渲染 accordion 组件,我们被迫将 "index" accordion 组件模板放在 resources/views/components
目录中,而不是将它与其他与 accordion 相关的模板一起嵌套在 accordion
目录中。
幸运的是,Blade 允许您在组件的模板目录中放置一个 index.blade.php
文件。当组件的 index.blade.php
模板存在时,它将被渲染为组件的 "根" 节点。因此,我们可以继续使用上面的示例中给出的相同 Blade 语法;但是,我们将调整我们的目录结构如下:
php
/resources/views/components/accordion/index.blade.php
/resources/views/components/accordion/item.blade.php
数据属性/属性
由于匿名组件没有任何相关的类,您可能想知道哪些数据应该作为变量传递给组件,哪些属性应该放在组件的属性包中。
您可以使用 Blade 模板中的 @props
指令指定哪些属性应该被视为数据变量。所有其他组件上的属性将通过组件的属性包可用。如果您希望给定数据变量一个默认值,您可以将变量名称作为数组键,将默认值作为数组值:
blade
<!-- /resources/views/components/alert.blade.php -->
@props(['type' => 'info', 'message'])
<div {{ $attributes->merge(['class' => 'alert alert-'.$type]) }}>
{{ $message }}
</div>
给定上面的组件定义,我们可以这样渲染组件:
blade
<x-alert type="error" :message="$message" class="mb-4"/>
访问父数据
有时您可能希望在子组件中访问父组件的数据。在这些情况下,您可以使用 @aware
指令。例如,假设我们正在构建一个复杂的菜单组件,由父 <x-menu>
和子 <x-menu.item>
组成:
blade
<x-menu color="purple">
<x-menu.item>...</x-menu.item>
<x-menu.item>...</x-menu.item>
</x-menu>
<x-menu>
组件可能有以下实现:
blade
<!-- /resources/views/components/menu/index.blade.php -->
@props(['color' => 'gray'])
<ul {{ $attributes->merge(['class' => 'bg-'.$color.'-200']) }}>
{{ $slot }}
</ul>
因为 color
prop 只传递给了父组件(<x-menu>
),它不会在 <x-menu.item>
中可用。但是,如果我们使用 @aware
指令,我们可以在 <x-menu.item>
中使其可用:
blade
<!-- /resources/views/components/menu/item.blade.php -->
@aware(['color' => 'gray'])
<li {{ $attributes->merge(['class' => 'text-'.$color.'-800']) }}>
{{ $slot }}
</li>
WARNING
@aware
指令无法访问未显式传递给父组件的 HTML 属性的父数据。未显式传递给父组件的默认 @props
值不能被 @aware
指令访问。
匿名组件路径
如前所述,匿名组件通常是由放置在 resources/views/components
目录中的 Blade 模板定义的。但是,您可能偶尔希望向 Laravel 注册其他匿名组件路径,以及默认路径之外的路径。
anonymousComponentPath
方法接受匿名组件位置的 "路径" 作为其第一个参数,以及组件应放置在其下的可选 "命名空间" 作为其第二个参数。通常,此方法应该从应用程序的服务提供者之一的 boot
方法中调用:
php
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Blade::anonymousComponentPath(__DIR__.'/../components');
}
当注册不带前缀的组件路径时,它们可以在 Blade 组件中不带相应前缀地渲染。例如,如果 panel.blade.php
组件存在于上面注册的路径中,您可以这样渲染它:
blade
<x-panel />
可以提供前缀 "命名空间" 作为 anonymousComponentPath
方法的第二个参数:
php
Blade::anonymousComponentPath(__DIR__.'/../components', 'dashboard');
当提供前缀时,可以通过在组件名称前加上组件的命名空间来渲染该命名空间中的组件:
blade
<x-dashboard::panel />
构建布局
使用组件构建布局
大多数 Web 应用程序在各个页面上保持相同的通用布局。如果我们在每个创建的视图中都重复整个布局 HTML,那将是非常麻烦且难以维护的。幸运的是,我们可以将此布局定义为一个单一的 Blade 组件,并在整个应用程序中使用它。
定义布局组件
例如,假设我们正在构建一个 "todo" 列表应用程序。我们可能会定义一个 layout
组件,如下所示:
blade
<!-- resources/views/components/layout.blade.php -->
<html>
<head>
<title>{{ $title ?? 'Todo Manager' }}</title>
</head>
<body>
<h1>Todos</h1>
<hr/>
{{ $slot }}
</body>
</html>
应用布局组件
一旦 layout
组件已定义,我们可以创建一个 Blade 视图来使用该组件。在此示例中,我们将定义一个简单的视图来显示我们的任务列表:
blade
<!-- resources/views/tasks.blade.php -->
<x-layout>
@foreach ($tasks as $task)
<div>{{ $task }}</div>
@endforeach
</x-layout>
请记住,注入到组件中的内容将作为默认的 $slot
变量传递给我们的 layout
组件。正如您可能已经注意到的,我们的 layout
还尊重 $title
插槽,如果提供了该插槽,则显示该插槽;否则,显示默认标题。我们可以从任务列表视图中使用标准插槽语法注入自定义标题,如组件文档中所述:
blade
<!-- resources/views/tasks.blade.php -->
<x-layout>
<x-slot:title>
Custom Title
</x-slot>
@foreach ($tasks as $task)
<div>{{ $task }}</div>
@endforeach
</x-layout>
现在我们已经定义了布局和任务列表视图,我们只需要从路由返回任务
视图:
php
use App\Models\Task;
Route::get('/tasks', function () {
return view('tasks', ['tasks' => Task::all()]);
});
使用模板继承的布局
定义布局
布局也可以通过 “template inheritance” 创建。这是在引入组件之前构建应用程序的主要方式。
首先,让我们看一个简单的示例。首先,我们将检查页面布局。由于大多数 Web 应用程序在各个页面上维护相同的常规布局,因此将此布局定义为单个 Blade 视图很方便:
blade
<!-- 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
指令用于显示给定部分的内容。
现在我们已经为应用程序定义了布局,让我们定义一个继承该布局的子页面。
扩展布局
定义子视图时,请使用 @extends
Blade 指令指定子视图应“继承”的布局。扩展 Blade 布局的视图可以使用 @section
指令将内容注入布局的各个部分。请记住,如上例所示,这些部分的内容将使用 @yield
显示在布局中:
blade
<!-- resources/views/child.blade.php -->
@extends('layouts.app')
@section('title', 'Page Title')
@section('sidebar')
@@parent
<p>This is appended to the master sidebar.</p>
@endsection
@section('content')
<p>This is my body content.</p>
@endsection
在此示例中,侧边栏
部分利用 @parent
指令将内容附加(而不是覆盖)到布局的侧边栏。@parent
指令将在呈现视图时替换为布局的内容。
NOTE
与前面的示例相反,此侧边栏
部分以 @endsection
结尾,而不是 @show
。@endsection
指令将仅定义一个部分,而 @show
将定义并立即生成该部分。
@yield
指令还接受 default 值作为其第二个参数。如果生成的部分未定义,则将呈现此值:
blade
@yield('content', 'Default content')
表单
CSRF 字段
无论何时在应用程序中定义 HTML 表单,都应该在表单中包含隐藏的 CSRF 令牌字段,以便 CSRF 保护中间件可以验证请求。您可以使用 @csrf
Blade 指令生成 token 字段:
blade
<form method="POST" action="/profile">
@csrf
...
</form>
Method 字段
由于 HTML 表单无法发出 PUT
、PATCH
或 DELETE
请求,因此您需要添加一个隐藏的 _method
字段来欺骗这些 HTTP 动词。@method
Blade 指令可以为您创建此字段:
blade
<form action="/foo/bar" method="POST">
@method('PUT')
...
</form>
验证错误
@error
指令可用于快速检查给定属性是否存在验证错误消息。在 @error
指令中,您可以回显 $message
变量以显示错误消息:
blade
<!-- /resources/views/post/create.blade.php -->
<label for="title">Post Title</label>
<input id="title"
type="text"
class="@error('title') is-invalid @enderror">
@error('title')
<div class="alert alert-danger">{{ $message }}</div>
@enderror
由于 @error
指令编译为 “if” 语句,因此您可以使用 @else
指令在属性没有错误时呈现内容:
blade
<!-- /resources/views/auth.blade.php -->
<label for="email">Email address</label>
<input id="email"
type="email"
class="@error('email') is-invalid @else is-valid @enderror">
您可以将特定错误包的名称作为第二个参数传递给 @error
指令,以检索包含多个表单的页面上的验证错误消息:
blade
<!-- /resources/views/auth.blade.php -->
<label for="email">Email address</label>
<input id="email"
type="email"
class="@error('email', 'login') is-invalid @enderror">
@error('email', 'login')
<div class="alert alert-danger">{{ $message }}</div>
@enderror
Stacks
Blade 允许您推送到命名堆栈,这些堆栈可以在另一个视图或布局中的其他位置呈现。这对于指定子视图所需的任何 JavaScript 库特别有用:
blade
@push('scripts')
<script src="/example.js"></script>
@endpush
如果您想在给定的布尔表达式计算结果为 true
时@push
内容,则可以使用 @pushIf
指令:
blade
@pushIf($shouldPush, 'scripts')
<script src="/example.js"></script>
@endPushIf
您可以根据需要多次推送到堆栈。要呈现完整的堆栈内容,请将堆栈的名称传递给 @stack
指令:
blade
<head>
<!-- Head Contents -->
@stack('scripts')
</head>
如果你想在堆栈的开头加上内容,你应该使用 @prepend
指令:
blade
@push('scripts')
This will be second...
@endpush
// Later...
@prepend('scripts')
This will be first...
@endprepend
服务注入
@inject
指令可用于从 Laravel 服务容器中检索服务。传递给 @inject
的第一个参数是服务将被放入的变量的名称,而第二个参数是你想要解析的服务的类或接口名称:
blade
@inject('metrics', 'App\Services\MetricsService')
<div>
Monthly Revenue: {{ $metrics->monthlyRevenue() }}.
</div>
渲染内联 Blade 模板
有时,您可能需要将原始 Blade 模板字符串转换为有效的 HTML。您可以使用 Blade
门面提供的 render
方法来实现这一点。render
方法接受 Blade 模板字符串和要提供给模板的可选数据数组:
php
use Illuminate\Support\Facades\Blade;
return Blade::render('Hello, {{ $name }}', ['name' => 'Julian Bashir']);
Laravel 通过将内联 Blade 模板写入 storage/framework/views
目录来呈现它们。如果你希望 Laravel 在渲染 Blade 模板后删除这些临时文件,你可以为该方法提供 deleteCachedView
参数:
php
return Blade::render(
'Hello, {{ $name }}',
['name' => 'Julian Bashir'],
deleteCachedView: true
);
渲染 Blade 片段
使用 Turbo 和 htmx 等前端框架时,有时可能只需要在 HTTP 响应中返回 Blade 模板的一部分。Blade “fragments” 允许您执行此操作。首先,将 Blade 模板的一部分放在 @fragment
和 @endfragment
指令中:
blade
@fragment('user-list')
<ul>
@foreach ($users as $user)
<li>{{ $user->name }}</li>
@endforeach
</ul>
@endfragment
然后,在渲染使用此模板的视图时,您可以调用 fragment
方法以指定仅应包含指定的 fragment in 传出 HTTP 响应中:
php
return view('dashboard', ['users' => $users])->fragment('user-list');
fragmentIf
方法允许您根据给定条件有条件地返回视图的片段。否则,将返回整个视图:
php
return view('dashboard', ['users' => $users])
->fragmentIf($request->hasHeader('HX-Request'), 'user-list');
fragments
和 fragmentsIf
方法允许您在响应中返回多个视图 fragment。片段将连接在一起:
php
view('dashboard', ['users' => $users])
->fragments(['user-list', 'comment-list']);
view('dashboard', ['users' => $users])
->fragmentsIf(
$request->hasHeader('HX-Request'),
['user-list', 'comment-list']
);
扩展 Blade
Blade 允许您使用 directive
方法定义自己的自定义指令。当 Blade 编译器遇到 custom 指令时,它将使用指令包含的表达式调用提供的回调。
下面的示例创建一个 @datetime($var)
指令,该指令格式化给定$var
,该应该是 DateTime
的实例:
php
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* Register any application services.
*/
public function register(): void
{
// ...
}
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Blade::directive('datetime', function (string $expression) {
return "<?php echo ($expression)->format('m/d/Y H:i'); ?>";
});
}
}
如你所见,我们将 format
方法链接到传递给指令的任何表达式上。因此,在此示例中,此指令生成的最终 PHP 将是:
<?php echo ($var)->format('m/d/Y H:i'); ?>
WARNING
更新 Blade 指令的逻辑后,您需要删除所有缓存的 Blade 视图。可以使用 view:clear
Artisan 命令删除缓存的 Blade 视图。
自定义 Echo 处理程序
如果尝试使用 Blade “回显”对象,将调用该对象的 __toString
方法。__toString
方法是 PHP 内置的 “魔术方法” 之一。但是,有时您可能无法控制给定类的 __toString
方法,例如,当您与之交互的类属于第三方库时。
在这些情况下,Blade 允许您为该特定类型的对象注册自定义回声处理程序。为此,您应该调用 Blade 的 stringable
方法。stringable
方法接受闭包。此闭包应类型提示它负责渲染的对象类型。通常,应在应用程序的 AppServiceProvider
类的 boot
方法中调用可字符串
化方法:
php
use Illuminate\Support\Facades\Blade;
use Money\Money;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Blade::stringable(function (Money $money) {
return $money->formatTo('en_GB');
});
}
定义自定义 echo 处理程序后,只需在 Blade 模板中回显对象即可:
blade
Cost: {{ $money }}
自定义 If 语句
在定义简单的自定义条件语句时,对自定义指令进行编程有时比必要的更复杂。因此,Blade 提供了一个 Blade::if
方法,它允许你使用闭包快速定义自定义条件指令。例如,让我们定义一个自定义条件,用于检查为应用程序配置的默认 “disk”。我们可以在 AppServiceProvider
的 boot
方法中执行此操作:
php
use Illuminate\Support\Facades\Blade;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Blade::if('disk', function (string $value) {
return config('filesystems.default') === $value;
});
}
定义自定义条件后,您可以在模板中使用它:
blade
@disk('local')
<!-- 应用程序正在使用本地磁盘... -->
@elsedisk('s3')
<!-- 用程序正在使用 s3 磁盘...-->
@else
<!-- 应用程序正在使用其他磁盘...- -->
@enddisk
@unlessdisk('local')
<!-- 应用程序未使用本地磁盘... -->
@enddisk