Yii--小部件（Widgets）

小部件 ¶

小部件是在 視圖 中使用的可重用單元， 使用面向對象方式建立複雜和可配置使用者界面單元。 例如，日期選擇器小部件可生成一個精緻的允許使用者選擇日期的日期選擇器， 你隻需要在視圖中插入如下代碼：

<?php
use yii\jui\DatePicker;
?>
<?= DatePicker::widget(['name' => 'date']) ?>
           

Yii提供許多優秀的小部件，比如active form, menu, jQuery UI widgets, Twitter Bootstrap widgets。 接下來介紹小部件的基本知識，如果你想了解某個小部件請參考對應的類API文檔。

使用小部件

小部件基本上在views中使用， 在視圖中可調用 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',
]) ?>
           

一些小部件可在yii\base\Widget::begin() 和 yii\base\Widget::end() 調用中使用資料内容。 例如如下代碼使用yii\widgets\ActiveForm小部件生成一個登入表單， 小部件會在

begin()

和0

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() 方法傳回一個可組建小部件内容的小部件執行個體。

注意： 當調用 yii\base\Widget::end() 的時候，一些小部件将使用 輸出緩沖 來調整封閉的内容。是以，當調用 yii\base\Widget::begin() 和 yii\base\Widget::end() 時，最好在同一個視圖檔案裡。 不遵循這個規則可能會導緻意外的輸出。

配置全局預設值

小部件的全局預設值可以通過 DI 容器配置:

\Yii::$container->set('yii\widgets\LinkPager', ['maxButtonCount' => 5]);
           

詳見 依賴注入容器 "實踐中的應用" 一節 。

建立小部件

繼承 yii\base\Widget 類并覆寫 yii\base\Widget::init() 和/或 yii\base\Widget::run() 方法可建立小部件。通常

init()

方法處理小部件屬性，

run()

方法包含小部件生成渲染結果的代碼。 渲染結果可在

run()

方法中直接"echoed"輸出或以字元串傳回。

如下代碼中

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']) ?>
           

以下是另一種可在

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()

處理和傳回。

資訊： 當你調用 yii\base\Widget::begin() 時會建立一個新的小部件 執行個體并在構造結束時調用

init()

方法， 在

end()

時會調用

run()

方法并輸出傳回結果。

如下代碼顯示如何使用這種

HelloWidget

:

<?php
use app\components\HelloWidget;
?>
<?php HelloWidget::begin(); ?>

    content that may contain <tag>'s

<?php HelloWidget::end(); ?>
           

有時小部件需要渲染很多内容，一種更好的辦法是将内容放入一個視圖檔案， 然後調用yii\base\Widget::render()方法渲染該視圖檔案， 例如：

public function run()
{
    return $this->render('hello');
}
           

小部件的視圖檔案預設存儲在

WidgetPath/views

目錄，

WidgetPath

代表小部件類檔案所在的目錄。 假如上述示例小部件類檔案在

@app/components

下， 會渲染

@app/components/views/hello.php

視圖檔案。 You may override 可以覆寫yii\base\Widget::getViewPath()方法自定義視圖檔案所在路徑。

最佳實踐

小部件是面向對象方式來重用視圖代碼。

建立小部件時仍需要遵循MVC模式，通常邏輯代碼在小部件類， 展示内容在視圖中。

小部件設計時應是獨立的，也就是說使用一個小部件時候， 可以直接丢棄它而不需要額外的處理。 但是當小部件需要外部資源如CSS, JavaScript, 圖檔等會比較棘手， 幸運的時候Yii提供 資源包 來解決這個問題。

當一個小部件隻包含視圖代碼，它和視圖很相似， 實際上，在這種情況下，唯一的差別是小部件是可以重用類， 視圖隻是應用中使用的普通PHP腳本。