Yii 2 小部件(Widget)完全指南:使用、创建与最佳实践
Yii 2 小部件(Widget)完全指南:使用、创建与最佳实践
小部件(Widget)是 Yii 2 框架中在视图里使用的可重用单元,它以面向对象的方式封装复杂且可配置的用户界面片段,是 Yii 视图层复用能力的重要载体。本文以官方中文指南《小部件》为核心,结合本仓库(Yii 2 框架源码)中 yii\base\Widget 的底层实现与测试用例,系统讲解小部件的调用方式、基于 DI 容器的全局默认值配置、两种创建方式、视图路径约定与最佳实践。读完本文,你将能够在视图与自定义组件中熟练使用和编写可复用、可配置的小部件。
什么是小部件
小部件是在视图中使用的可重用单元,使用面向对象方式创建复杂和可配置用户界面单元。例如,日期选择器小部件可以生成一个精致的、允许用户选择日期的日期选择器,你只需要在视图中插入如下代码:
<?php
use yii\jui\DatePicker;
?>
<?= DatePicker::widget(['name' => 'date']) ?>
Yii 2 提供了许多优秀的小部件,例如:
- [[yii\widgets\ActiveForm|ActiveForm]]:基于模型生成交互式表单;
- [[yii\widgets\Menu|Menu]]:根据路由自动高亮当前项的菜单;
- jQuery UI 小部件(如
DatePicker、Select2等),由yii2-jui扩展提供; - Twitter Bootstrap 小部件(如
Nav、Modal、ActiveForm的 Bootstrap 风格),由yii2-bootstrap扩展提供。
以上框架内置小部件类集中在 framework/widgets 目录下,包括 ActiveField.php、ActiveForm.php、Breadcrumbs.php、DetailView.php、ListView.php、LinkPager.php、Menu.php、Pjax.php 等。如果你想了解某个具体小部件的用法,可以参考对应的类 API 文档。下面先介绍小部件的基本知识。
使用小部件
小部件基本上在视图中使用。在视图中可以调用 <a href="https://link.gitcode.com/i/166d05ae4dba04247aa4ce2a1873bb5a" target="_blank">[yii\base\Widget::widget()]] 方法来使用小部件,该方法使用[配置数组初始化小部件,并返回小部件渲染后的结果。
例如,如下代码插入一个日期选择器小部件,它配置为使用俄罗斯语,输入框内容为 $model 的 from_date 属性值:
<?php
use yii\jui\DatePicker;
?>
<?= DatePicker::widget([
'model' => $model,
'attribute' => 'from_date',
'language' => 'ru',
'dateFormat' => 'php:Y-m-d',
]) ?>
其中 model 与 attribute 指定数据来源,language 指定界面语言,dateFormat 指定日期格式(php: 前缀表示使用 PHP 日期格式语法)。
使用 begin() 与 end() 包裹内容
一些小部件可以在 [[yii\base\Widget::begin()]] 和 [[yii\base\Widget::end()]] 调用之间使用数据内容。例如如下代码使用 [[yii\widgets\ActiveForm]] 小部件生成一个登录表单:小部件会在 begin() 和 end() 执行处分别生成 <form> 的开始标签和结束标签,中间的任何代码也会被渲染:
<?php
use yii\widgets\ActiveForm;
use yii\helpers\Html;
?>
<?php $form = ActiveForm::begin(['id' => 'login-form']); ?>
<?= $form->field($model, 'username') ?>
<?= $form->field($model, 'password')->passwordInput() ?>
<div class="form-group">
<?= Html::submitButton('Login') ?>
</div>
<?php ActiveForm::end(); ?>
注意,和调用 [[yii\base\Widget::widget()]] 返回渲染结果不同,调用 [[yii\base\Widget::begin()]] 方法返回一个可组建小部件内容的小部件实例,随后由 end() 触发渲染并输出结果。
Note(输出缓冲注意事项):当调用
[[yii\base\Widget::end()]]的时候,一些小部件将使用输出缓冲来调整封闭的内容。因此,当调用[[yii\base\Widget::begin()]]和[[yii\base\Widget::end()]]时,最好在同一个视图文件里。不遵循这个规则可能会导致意外的输出。
源码级原理:begin() / end() 与 widget() 的实现差异
从 framework/base/Widget.php 的源码可以看到这两种调用方式的底层实现:
Widget::begin($config)(L89-L98)通过Yii::createObject($config)创建实例并压入静态栈self::$stack,返回该实例;Widget::end()(L107-L129)从栈中弹出实例,依次调用beforeRun()、run()、afterRun(),并把结果直接echo输出。若begin()与end()未正确嵌套,会抛出InvalidCallException;Widget::widget($config)(L138-L166)则先开启输出缓冲ob_start(),执行run()后通过ob_get_clean()捕获渲染结果并作为字符串返回,同时用try/catch保证异常时正确清理缓冲。
仓库测试 tests/framework/base/WidgetTest.php 中的 testBeginEnd()(L38-L50)验证了 begin()/end() 会把 run() 的返回值直接输出到缓冲区;testStackTracking() 与 testStackTrackingDisorder()(L100-L116)则验证了 begin/end 必须严格配对嵌套,否则抛出 InvalidCallException。
此外,Widget::beforeRun() 与 afterRun()(L305-L339)会分别触发 EVENT_BEFORE_RUN 与 EVENT_AFTER_RUN 事件,且 beforeRun() 返回 false 时小部件将不会执行——这正是测试 testEvents()(L121-L136)与 testPreventRun()(L141-L150)所验证的行为。你可以利用这些事件在渲染前后做拦截或改写输出。
配置全局默认值
小部件的全局默认值可以通过 DI 容器配置:
\Yii::$container->set('yii\widgets\LinkPager', ['maxButtonCount' => 5]);
这样,所有 LinkPager 实例的 maxButtonCount 属性都会被初始化为 5,而不是类中定义的默认值 10(见 framework/widgets/LinkPager.php 中 public $maxButtonCount = 10; 的定义,L96)。
有关详细信息,请参阅依赖注入容器"实践中的应用"一节。需要强调的是:
- 在小部件调用中显式给出的属性值始终覆盖 DI 容器中的定义;
- 即使你指定了一个数组(例如
'options' => ['id' => 'mypager']),这些值也会替换而非与 DI 容器中的配置合并。
之所以能实现全局定制,是因为 widget() 与 begin() 内部均通过 Yii::createObject() 创建实例(framework/base/Widget.php),而 Yii::createObject() 会委托给 DI 容器 Yii::$container 的 get() 方法完成对象的创建与依赖注入,因此容器配置对小部件同样生效。
创建小部件
可以根据需要以两种不同方式创建小部件。
方式一:使用 widget() 方法
继承 [[yii\base\Widget]] 类并覆盖 [[yii\base\Widget::init()]] 和/或 [[yii\base\Widget::run()]] 方法即可创建小部件。通常:
init()方法处理小部件属性(在构造结束时被调用,并触发EVENT_INIT事件);run()方法包含小部件生成渲染结果的代码,渲染结果可以直接"输出",也可以通过run()方法作为字符串返回。
如下代码中,HelloWidget 编码并显示赋给 message 属性的值;如果属性没有被赋值,默认显示 "Hello World":
namespace app\components;
use yii\base\Widget;
use yii\helpers\Html;
class HelloWidget extends Widget
{
public $message;
public function init()
{
parent::init();
if ($this->message === null) {
$this->message = 'Hello World';
}
}
public function run()
{
return Html::encode($this->message);
}
}
使用这个小部件只需在视图中简单使用如下代码:
<?php
use app\components\HelloWidget;
?>
<?= HelloWidget::widget(['message' => 'Good morning']) ?>
有时小部件需要渲染很多内容。虽然你可以在 run() 方法中嵌入内容,但更好的做法是将内容放入一个视图文件,然后调用 [[yii\base\Widget::render()]] 方法渲染该视图文件,例如:
public function run()
{
return $this->render('hello');
}
Widget::render()(framework/base/Widget.php)底层委托给当前视图对象 View::render() 完成渲染,视图对象默认取应用的 view 组件(getView() 方法,L203-L212)。
方式二:使用 begin() 和 end() 方法
这种方式与方式一类似,但有细微差别。以下是另一种可在 begin() 和 end() 调用中使用的 HelloWidget,它会 HTML 编码封闭内容后显示:
namespace app\components;
use yii\base\Widget;
use yii\helpers\Html;
class HelloWidget extends Widget
{
public function init()
{
parent::init();
ob_start();
}
public function run()
{
$content = ob_get_clean();
return Html::encode($content);
}
}
如上所示,PHP 输出缓冲在 init() 中启动,所有在 init() 和 run() 方法之间的输出内容都会被捕获,并在 run() 中处理并返回。
Info:当你调用
[[yii\base\Widget::begin()]]时会创建一个新的小部件实例,并在构造结束时调用init()方法;在end()时会调用run()方法并输出返回结果。
如下代码显示如何使用这种 HelloWidget:
<?php
use app\components\HelloWidget;
?>
<?php HelloWidget::begin(); ?>
sample content that may contain one or more <strong>HTML</strong> <pre>tags</pre>
If this content grows too big, use sub views
For e.g.
<?php echo $this->render('viewfile'); // Note: here render() method is of class \yii\base\View as this part of code is within view file and not in Widget class file ?>
<?php HelloWidget::end(); ?>
小部件视图路径约定
默认情况下,小部件的视图应存储在 WidgetPath/views 目录下,其中 WidgetPath 代表小部件类文件所在的目录。假如小部件类文件在 @app/components 下,上述示例会渲染 @app/components/views/hello.php 视图文件。
你可以覆盖 <a href="https://link.gitcode.com/i/8e7774b0b61aea22197147685a56e14c" target="_blank">[yii\base\Widget::getViewPath()]] 方法自定义视图文件所在路径。从源码看,默认实现([framework/base/Widget.php)利用反射获取小部件类文件所在目录,并拼接 DIRECTORY_SEPARATOR . 'views' 作为视图目录,即"类文件目录下的 views 子目录"。
另外,Widget::getId()(L175-L182)会自动为未指定 ID 的小部件生成形如 w0、w1、w2……的递增 ID(前缀由静态属性 $autoIdPrefix = 'w' 控制),这在多个小部件同时出现在一个页面时能保证 DOM ID 唯一。
最佳实践
小部件是面向对象的方式来重用视图代码。创建小部件时仍需要遵循 MVC 模式,通常:
- 逻辑代码放在小部件类中;
- 展示内容放在视图中。
小部件设计时应是独立的,也就是说,使用一个小部件时可以"直接丢弃"它而不需要额外的处理。但是当小部件需要外部资源(如 CSS、JavaScript、图片等)时,这会比较棘手——幸运的是,Yii 提供了资源包(Asset Bundle)来解决这个问题。框架内置小部件也遵循这一约定,例如 ActiveForm 依赖 ActiveFormAsset(framework/widgets/ActiveFormAsset.php)、MaskedInput 依赖 MaskedInputAsset(framework/widgets/MaskedInputAsset.php),它们把所需的 CSS/JS 以资源包形式注册到视图。
当一个小部件只包含视图代码时,它和视图很相似。实际上,在这种情况下,唯一的区别是:小部件是可重用的类,而视图只是应用中使用的普通 PHP 脚本。
常用内置小部件速览
结合框架内置实现,这里列出几个高频使用的小部件及其关键配置(完整参数请查阅对应类的 API 文档):
| 小部件 | 文件 | 典型用途 | 常用属性 |
|---|---|---|---|
yii\widgets\ActiveForm |
framework/widgets/ActiveForm.php | 基于模型生成交互式表单 | action、method(默认 post)、options、fieldConfig、validateOnSubmit |
yii\widgets\ActiveField |
framework/widgets/ActiveField.php | 表单中单个字段的渲染与验证 | model、attribute、options、inputOptions |
yii\widgets\Menu |
framework/widgets/Menu.php | 根据路由自动高亮当前项的菜单 | items、activeCssClass、activateItems、encodeLabels |
yii\widgets\LinkPager |
framework/widgets/LinkPager.php | 配合 Pagination 输出分页链接 |
pagination、maxButtonCount(默认 10)、options |
yii\widgets\ListView |
framework/widgets/ListView.php | 按数据提供者渲染列表 | dataProvider、itemView、layout |
yii\widgets\Breadcrumbs |
framework/widgets/Breadcrumbs.php | 面包屑导航 | links、homeLink、encodeLabels |
yii\widgets\DetailView |
framework/widgets/DetailView.php | 以键值对形式展示单条模型数据 | model、attributes、options |
例如 Menu 的 items 属性接受标签与 URL 数组,配合 activeCssClass(默认 active)与 activateItems(默认 true)会在当前路由匹配时自动为对应菜单项加上高亮类;LinkPager 的 maxButtonCount 默认显示 10 个分页按钮,这也是上文 DI 容器全局配置示例的默认值来源。这些类均继承自 yii\base\Widget,因此前文介绍的使用、创建与配置方式对它们完全适用。