Yii 2 小部件(Widget)完全指南:使用、创建与最佳实践

原创2026-09-23 13:15:151,635 阅读
文章标签:后端Web框架

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,因此前文介绍的使用、创建与配置方式对它们完全适用。

登录后查看全文
yii2