Yii 2 组件体系深度解析:Widget 小部件的使用、自定义与最佳实践
Yii 2 组件体系深度解析:Widget 小部件的使用、自定义与最佳实践
Yii 2 的 Widget(小部件)是构建在视图层之上、面向对象复用的 UI 构件体系,它以 yii\base\Widget 为根基,贯穿框架的 ActiveForm、Menu、LinkPager 等数十个内置组件。本文以 Yii 2 官方指南《Виджеты(小部件)》为核心骨架,结合本仓库源码(framework/base/Widget.php、framework/widgets/、tests/framework/base/WidgetTest.php)展开纵深剖析,帮助你完整掌握 Widget 的调用方式、widget()/begin()/end() 生命周期、DI 容器全局配置、自定义 Widget 的三种写法(直接输出、输出缓冲、视图渲染),以及遵循 MVC 的自包含设计原则。
什么是 Widget:可复用的 UI 构建块
Widget 是 Yii 2 中可复用的"积木式"构建块,用于在视图(views)中创建复杂且可配置的用户界面元素。它用面向对象的方式封装了视图代码:一个日期选择器(date picker)可以封装成 Widget,为用户提供交互式的日期输入界面;一个菜单、一个分页条、一个表单,都可以是 Widget。
使用 Widget 的成本极低——只需在视图中插入一段代码即可。例如在视图中加入一个日期选择器:
<?php
use yii\bootstrap\DatePicker;
?>
<?= DatePicker::widget(['name' => 'date']) ?>
Yii 2 框架内置了大量开箱即用的 Widget,常见的有:
- 表单类:yii\widgets\ActiveForm(活动表单)及其字段组件
ActiveField; - 导航类:yii\widgets\Menu(菜单);
- 数据展示类:
ListView、DetailView、Breadcrumbs(面包屑导航); - 分页类:yii\widgets\LinkPager(分页链接)与
LinkSorter(排序链接); - 缓存与性能类:
FragmentCache(片段缓存)、Pjax、Spaceless、Block、ContentDecorator; - 输入类:
InputWidget及其派生实现、MaskedInput(掩码输入)。
此外,jQuery UI 与 Twitter Bootstrap 系列的第三方扩展也提供了大量 Widget。本文介绍的是 Widget 的基础机制;具体某个 Widget 的用法请参考其对应的类 API 文档。
使用 Widget
Widget 主要在视图中使用。在视图中调用 Widget,核心入口是静态方法 [yii\base\Widget::widget()]]:它接收一个[配置(configuration)数组用于初始化 Widget,并返回该 Widget 的渲染结果。
例如,下面这段代码插入一个日期选择器 Widget,配置它使用俄语作为界面语言,并把用户输入保存到 $model 模型的 from_date 属性中:
<?php
use yii\bootstrap\DatePicker;
?>
<?= DatePicker::widget([
'model' => $model,
'attribute' => 'from_date',
'language' => 'ru',
'clientOptions' => [
'dateFormat' => 'yy-mm-dd',
],
]) ?>
从源码看,widget() 方法内部执行了这样一套流程(framework/base/Widget.php#L138-L166):
- 开启 PHP 输出缓冲(
ob_start()),并关闭隐式刷新; - 通过
Yii::createObject($config)创建 Widget 实例——这正是配置数组能被解析、且 DI 容器能介入的原因; - 依次调用
beforeRun()(触发EVENT_BEFORE_RUN事件,可通过WidgetEvent::isValid取消执行)、run()、afterRun()(触发EVENT_AFTER_RUN事件,可修改渲染结果); - 返回
ob_get_clean() . $out,即缓冲区内输出与run()返回值的拼接结果。
也就是说,widget() 返回的是渲染结果字符串,所以在视图中通常配合 <?= ... ?> 直接输出。
begin() 与 end():带内容块的 Widget
部分 Widget 支持包裹一段内容块,此时需要使用 [[yii\base\Widget::begin()]] 与 [[yii\base\Widget::end()]] 这对方法。最典型的例子是登录表单——ActiveForm::begin() 在调用处生成 <form> 开始标签,ActiveForm::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(); ?>
需要注意:与返回渲染结果的 widget() 不同,begin() 返回的是 Widget 的实例(见 framework/base/Widget.php#L89-L98),你可以持有这个实例来继续构建其内部内容,例如 $form->field($model, 'username') 就是基于该实例生成表单字段。
begin()/end() 的实现与 widget() 有两点关键差异:
begin()会通过Yii::createObject()创建实例,将实例压入静态栈self::$stack,然后返回实例——此时init()方法在构造函数结束时立即被调用,但run()尚未执行;end()从栈中弹出对应实例,依次调用beforeRun()、run()、afterRun(),并把run()的返回值直接echo输出(framework/base/Widget.php#L107-L129)。
由于栈机制的存在,begin() 与 end() 必须成对且按嵌套顺序调用(例如先 A 后 B,就必须先 A::end() 再 B::end());乱序调用会抛出 yii\base\InvalidCallException。这一点在 tests/framework/base/WidgetTest.php#L100-L116 的 testStackTracking 与 testStackTrackingDisorder 两个测试用例中得到了验证。
注意:部分 Widget 会借助 PHP 的输出缓冲在
end()时调整包裹内容,因此begin()与end()应写在同一个视图文件中,否则可能导致输出异常。
为某一类 Widget 设置全局默认值
如果希望某个 Widget 类型的所有实例都使用统一默认配置(例如把全站 LinkPager 的页码按钮数统一为 5),可以通过 DI 容器设置全局默认值:
\Yii::$container->set('yii\widgets\LinkPager', ['maxButtonCount' => 5]);
这样设置后,凡是创建 yii\widgets\LinkPager 实例的地方(包括 ListView 内部自动生成的分页条),maxButtonCount 都会默认为 5,除非在使用处显式覆盖。从 LinkPager 源码可以看到该属性默认值为 10(framework/widgets/LinkPager.php#L96),上面的全局设置可以将其降为 5。其底层原理是 widget()/begin() 都经由 Yii::createObject() 创建实例,而容器会合并全局定义、局部配置与调用时配置。详细机制参见「依赖注入容器」指南的「实践用法」小节。
创建自定义 Widget
创建自定义 Widget 有两种典型方式,取决于是否需要包裹内容块。但无论是哪种方式,核心动作都是:继承 [[yii\base\Widget]],并重写 init() 和/或 run() 方法。
通常约定:
init()中放置属性归一化逻辑(校验、补默认值等);run()中放置生成渲染结果的逻辑——结果既可以在run()内直接echo输出,也可以作为字符串return。
方式一:利用 widget() 方法
下面的 HelloWidget 会对 message 属性做 HTML 编码后输出;如果该属性未被赋值,则默认输出 "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']) ?>
这里配置数组中的 message 会被 Yii 的配置机制赋给公共属性 $message(widget() 内部通过 Yii::createObject() 完成属性注入)。init() 中的 parent::init() 并非可省略的"仪式代码"——基类的 init() 会触发 EVENT_INIT 事件(framework/base/Widget.php#L73-L77),允许外部通过 on init 回调介入初始化流程。
方式二:利用 begin() 与 end() 方法
当 Widget 需要把 begin() 与 end() 之间的内容当作"内部内容"捕获并处理时,可以用 PHP 输出缓冲实现。下面的变体版本把包裹内容整体捕获、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);
}
}
原理一目了然:init() 开启输出缓冲,于是 init() 与 run() 之间产生的所有输出都被截获,在 run() 中经 ob_get_clean() 取出、加工后返回。
Info:调用
begin()时会创建新的 Widget 实例,且init()会在构造函数其余代码执行完毕后立即被调用;调用end()时会执行run(),其返回值由end()负责输出。
使用这个版本:
<?php
use app\components\HelloWidget;
?>
<?php HelloWidget::begin(); ?>
content that may contain <tag>'s
<?php HelloWidget::end(); ?>
注意,如果包裹内容体积很大,不应把它们全部塞进 begin()/end() 之间的视图里,更优雅的做法是拆分子视图(见下文"渲染大块内容")。
渲染大块内容:用子视图 + render()
当 Widget 需要输出大量内容时,虽然可以直接写在 run() 里,但更符合 MVC 的做法是把内容放进一个视图文件,用 [[yii\base\Widget::render()]] 渲染:
public function run()
{
return $this->render('hello');
}
render() 最终委托给视图组件执行(framework/base/Widget.php#L252-L255)。默认约定:Widget 的视图文件必须放在 WidgetPath/views 目录下,其中 WidgetPath 是 Widget 类文件所在目录。因此上面的例子会渲染 @app/components/views/hello.php(假设类文件位于 @app/components)。
如果不想遵循默认目录,可以重写 [yii\base\Widget::getViewPath()]] 方法自定义视图目录。基类的默认实现是通过反射获取类文件所在目录并拼接 views 子目录([framework/base/Widget.php#L274-L279),这也解释了为何视图目录必须与类文件位置严格对应。
生命周期与事件钩子(源码级补充)
从源码可以梳理出 Widget 完整的执行生命周期(自 2.0.11 起支持事件):
| 阶段 | 触发方法 | 对应事件 | 作用 |
|---|---|---|---|
| 实例化 | init() |
EVENT_INIT |
属性归一化,事件可在此挂载 |
| 执行前 | beforeRun() |
EVENT_BEFORE_RUN |
将 WidgetEvent::isValid 置为 false 可取消执行 |
| 执行 | run() |
— | 生成渲染结果(字符串或直接输出) |
| 执行后 | afterRun($result) |
EVENT_AFTER_RUN |
通过修改 WidgetEvent::$result 调整最终结果 |
事件参数类型为 yii\base\WidgetEvent,它继承自事件基类并额外提供 result(可修改的 Widget 结果)与 isValid(是否继续执行)两个属性(framework/base/WidgetEvent.php)。
tests/framework/base/WidgetTest.php#L121-L150 的两个测试用例直观演示了这套机制:
testEvents:依次挂载on init、on beforeRun、on afterRun回调,最终输出顺序为<init><before-run><run-test><after-run>,验证了各事件按生命周期顺序触发;testPreventRun:在on beforeRun中把$event->isValid = false,结果run()完全未执行,输出为空字符串。
此外,Widget 还提供自动 ID 生成(getId(),前缀 w + 计数器)与 getView()/setView() 视图对象访问能力,前者的应用场景包括表单控件 id、Pjax 容器等需要唯一标识的场合。
最佳实践
Widget 的本质是面向对象的视图代码复用方式。在设计自定义 Widget 时,应遵循以下三条原则:
-
遵循 MVC 分层:主要逻辑放在 Widget 类中,负责输出标记(markup)的代码拆到视图中,两者职责分离。
render()+ 子视图就是为此设计的。 -
Widget 应当自包含(self-contained):使用一个 Widget 时,理想情况下只需把它"丢进"视图即可,无需额外手工引入 CSS、JavaScript、图片等外部资源。如果 Widget 依赖这类资源,应借助 Yii 的资源包(asset bundles)机制来解决——将依赖的样式与脚本声明到
AssetBundle中,由框架自动注册,从而保证"即插即用"。 -
纯展示型 Widget 与视图的关系:如果一个类只包含输出逻辑、没有业务逻辑,它与一个视图几乎没有区别。唯一的差别在于:Widget 是一个可独立分发、可复用的类(可以打进扩展包、跨项目复用),而视图只是一个普通的 PHP 脚本,通常仅适用于当前应用内部。因此,判断是否值得封装成 Widget,关键是看这段 UI 代码是否有跨页面、跨项目复用的价值。
总结
本文从"使用"与"创建"两个维度完整覆盖了 Yii 2 Widget 机制:
- 使用:视图内调用
widget()返回渲染结果;begin()/end()包裹内容块并返回实例;\Yii::$container->set()可为一类 Widget 统一设置全局默认值。 - 创建:继承
yii\base\Widget并重写init()/run();大块内容用render()渲染子视图(默认目录为WidgetPath/views,可重写getViewPath()定制);借助EVENT_INIT、EVENT_BEFORE_RUN、EVENT_AFTER_RUN三个事件与WidgetEvent实现执行前拦截与结果加工。 - 设计:遵循 MVC、利用 asset bundles 保证自包含、以可复用性为标准判断"该用 Widget 还是视图"。
掌握这套机制后,无论是组合框架内置 Widget,还是为项目沉淀可复用的自定义 UI 组件,都能做到游刃有余。