# 小部件 小部件是在?[視圖](http://www.yiichina.com/doc/guide/2.0/structure-views)?中使用的可重用單元，使用面向對象方式創建復雜和可配置用戶界面單元。 例如，日期選擇器小部件可生成一個精致的允許用戶選擇日期的日期選擇器， 你只需要在視圖中插入如下代碼： ~~~ <?php use yii\jui\DatePicker; ?> <?= DatePicker::widget(['name' => 'date']) ?> ~~~ Yii提供許多優秀的小部件，比如yii\widgets\ActiveForm, [yii\widgets\Menu|menu]],?[jQuery UI widgets](http://www.yiichina.com/doc/guide/2.0/widget-jui),?[Twitter Bootstrap widgets](http://www.yiichina.com/doc/guide/2.0/widget-bootstrap)。 接下來介紹小部件的基本知識，如果你想了解某個小部件請參考對應的類API文檔。 ## 使用小部件 小部件基本上在[views](http://www.yiichina.com/doc/guide/2.0/structure-views)中使用，在視圖中可調用 yii\base\Widget::widget() 方法使用小部件。 該方法使用?[配置](http://www.yiichina.com/doc/guide/2.0/concept-configurations)?數組初始化小部件并返回小部件渲染后的結果。 例如如下代碼插入一個日期選擇器小部件，它配置為使用俄羅斯語，輸入框內容為`$model`的`from_date`屬性值。 ~~~ <?php use yii\jui\DatePicker; ?> <?= DatePicker::widget([ 'model' => $model, 'attribute' => 'from_date', 'language' => 'ru', 'clientOptions' => [ 'dateFormat' => 'yy-mm-dd', ], ]) ?> ~~~ 一些小部件可在yii\base\Widget::begin() 和 yii\base\Widget::end() 調用中使用數據內容。Some widgets can take a block of content which should be enclosed between the invocation of 例如如下代碼使用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() 方法返回一個可組建小部件內容的小部件實例。 ## 創建小部件 ## Creating Widgets 繼承 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(); ?> ~~~ 有時小部件需要渲染很多內容，一種更好的辦法是將內容放入一個[視圖](http://www.yiichina.com/doc/guide/2.0/structure-views)文件， 然后調用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模式，通常邏輯代碼在小部件類，展示內容在[視圖](http://www.yiichina.com/doc/guide/2.0/structure-views)中。 小部件設計時應是獨立的，也就是說使用一個小部件時候，可以直接丟棄它而不需要額外的處理。 但是當小部件需要外部資源如CSS, JavaScript, 圖片等會比較棘手， 幸運的時候Yii提供?[資源包](http://www.yiichina.com/doc/guide/2.0/structure-asset-bundles)?來解決這個問題。 當一個小部件只包含視圖代碼，它和[視圖](http://www.yiichina.com/doc/guide/2.0/structure-views)很相似， 實際上，在這種情況下，唯一的區別是小部件是可以重用類，視圖只是應用中使用的普通PHP腳本。