# 小部件
小部件是在 [视图](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脚本。
- 介绍（Introduction）
- 关于 Yii（About Yii）
- 从 Yii 1.1 升级（Upgrading from Version 1.1）
- 入门（Getting Started）
- 安装 Yii（Installing Yii）
- 运行应用（Running Applications）
- 第一次问候（Saying Hello）
- 使用 Forms（Working with Forms）
- 玩转 Databases（Working with Databases）
- 用 Gii 生成代码（Generating Code with Gii）
- 更上一层楼（Looking Ahead）
- 应用结构（Application Structure）
- 结构概述（Overview）
- 入口脚本（Entry Scripts）
- 应用（Applications）
- 应用组件（Application Components）
- 控制器（Controllers）
- 模型（Models）
- 视图（Views）
- 模块（Modules）
- 过滤器（Filters）
- 小部件（Widgets）
- 前端资源（Assets）
- 扩展（Extensions）
- 请求处理（Handling Requests）
- 运行概述（Overview）
- 引导（Bootstrapping）
- 路由引导与创建 URL（Routing and URL Creation）
- 请求（Requests）
- 响应（Responses）
- Sessions and Cookies
- 错误处理（Handling Errors）
- 日志（Logging）
- 关键概念（Key Concepts）
- 组件（Components）
- 属性（Properties）
- 事件（Events）
- 行为（Behaviors）
- 配置（Configurations）
- 别名（Aliases）
- 类自动加载（Class Autoloading）
- 服务定位器（Service Locator）
- 依赖注入容器（Dependency Injection Container）
- 配合数据库工作（Working with Databases）
- 数据库访问（Data Access Objects）: 数据库连接、基本查询、事务和模式操作
- 查询生成器（Query Builder）: 使用简单抽象层查询数据库
- 活动记录（Active Record）: 活动记录对象关系映射（ORM），检索和操作记录、定义关联关系
- 数据库迁移（Migrations）: 在团体开发中对你的数据库使用版本控制
- Sphinx
- Redis
- MongoDB
- ElasticSearch
- 接收用户数据（Getting Data from Users）
- 创建表单（Creating Forms）
- 输入验证（Validating Input）
- 文件上传（Uploading Files）
- 收集列表输入（Collecting Tabular Input）
- 多模型同时输入（Getting Data for Multiple Models）
- 显示数据（Displaying Data）
- 格式化输出数据（Data Formatting）
- 分页（Pagination）
- 排序（Sorting）
- 数据提供器（Data Providers）
- 数据小部件（Data Widgets）
- 操作客户端脚本（Working with Client Scripts）
- 主题（Theming）
- 安全（Security）
- 认证（Authentication）
- 授权（Authorization）
- 处理密码（Working with Passwords）
- 客户端认证（Auth Clients）
- 安全领域的最佳实践（Best Practices）
- 缓存（Caching）
- 概述（Overview）
- 数据缓存（Data Caching）
- 片段缓存（Fragment Caching）
- 分页缓存（Page Caching）
- HTTP 缓存（HTTP Caching）
- RESTful Web 服务
- 快速入门（Quick Start）
- 资源（Resources）
- 控制器（Controllers）
- 路由（Routing）
- 格式化响应（Response Formatting）
- 授权验证（Authentication）
- 速率限制（Rate Limiting）
- 版本化（Versioning）
- 错误处理（Error Handling）
- 开发工具（Development Tools）
- 调试工具栏和调试器（Debug Toolbar and Debugger）
- 使用 Gii 生成代码（Generating Code using Gii）
- TBD 生成 API 文档（Generating API Documentation）
- 测试（Testing）
- 概述（Overview）
- 搭建测试环境（Testing environment setup）
- 单元测试（Unit Tests）
- 功能测试（Functional Tests）
- 验收测试（Acceptance Tests）
- 测试夹具（Fixtures）
- 高级专题（Special Topics）
- 高级应用模版（Advanced Project Template）
- 从头构建自定义模版（Building Application from Scratch）
- 控制台命令（Console Commands）
- 核心验证器（Core Validators）
- 国际化（Internationalization）
- 收发邮件（Mailing）
- 性能优化（Performance Tuning）
- 共享主机环境（Shared Hosting Environment）
- 模板引擎（Template Engines）
- 集成第三方代码（Working with Third-Party Code）
- 小部件（Widgets）
- Bootstrap 小部件（Bootstrap Widgets）
- jQuery UI 小部件（jQuery UI Widgets）
- 助手类（Helpers）
- 助手一览（Overview）
- Array 助手（ArrayHelper）
- Html 助手（Html）
- Url 助手（Url）