Widget类是所有部件的基类。yii2\base\Widget.php
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/ namespace yii\base; use Yii;
use ReflectionClass; /**
* Widget is the base class for widgets.
* Widget是所有小部件的基类
* @property string $id ID of the widget. 小部件标识
* @property \yii\web\View $view The view object that can be used to render views or view files. Note that the
* type of this property differs in getter and setter. See [[getView()]] and [[setView()]] for details.
* 用于渲染视图或视图文件的视图对象 在getter 和 setter中是不同的
* @property string $viewPath The directory containing the view files for this widget. This property is
* read-only. 包含此控件的视图文件目录
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
*/
class Widget extends Component implements ViewContextInterface
{
/**
* @var integer a counter used to generate [[id]] for widgets.
* @internal 用于生成widget ID的计数器
*/
public static $counter = ;
/**
* @var string the prefix to the automatically generated widget IDs.
* @see getId() 自动生成的前缀
*/
public static $autoIdPrefix = 'w';
/**
* @var Widget[] the widgets that are currently being rendered (not ended). This property
* is maintained by [[begin()]] and [[end()]] methods. 目前正在渲染的小部件
* @internal
*/
public static $stack = []; /**
* Begins a widget. 开始一个部件
* This method creates an instance of the calling class. It will apply the configuration
* to the created instance. A matching [[end()]] call should be called later.
* 将应用配置文件创建调用类的实例，与[end()]方法相对应
* @param array $config name-value pairs that will be used to initialize the object properties
* 用于初始化属性的参数
* @return static the newly created widget instance 静态新创建的部件实例
*/
public static function begin($config = [])
{
$config['class'] = get_called_class();//后期静态绑定类的名称
/* @var $widget Widget */
$widget = Yii::createObject($config);//通过类名和传入的配置，实例化调用类
static::$stack[] = $widget;//将对象放入正在渲染的部件堆栈中 return $widget;
} /**
* Ends a widget. 结束小部件
* Note that the rendering result of the widget is directly echoed out.渲染结果是直接呼应的
* @return static the widget instance that is ended. 静态结束的部件实例。
* @throws InvalidCallException if [[begin()]] and [[end()]] calls are not properly nested
*/
public static function end()
{
if (!empty(static::$stack)) {//正在呈现的小部件堆栈中存在调用类实例
$widget = array_pop(static::$stack);//从堆栈中删除最后一个实例
if (get_class($widget) === get_called_class()) {
echo $widget->run(); //如果删除的实例类名和当前调用类名相同，输出小部件的内容
return $widget;
} else {
throw new InvalidCallException("Expecting end() of " . get_class($widget) . ", found " . get_called_class());
}
} else {
throw new InvalidCallException("Unexpected " . get_called_class() . '::end() call. A matching begin() is not found.');
}
} /**
* Creates a widget instance and runs it. 创建一个部件实例，并运行
* The widget rendering result is returned by this method. 返回部件渲染的结果。
* @param array $config name-value pairs that will be used to initialize the object properties
* 用于初始化对象属性的参数
* @return string the rendering result of the widget. 控件的渲染结果。
*/
public static function widget($config = [])
{
ob_start(); //打开输出缓冲区
ob_implicit_flush(false);//关闭绝对刷新
/* @var $widget Widget */
$config['class'] = get_called_class(); //获取调用类的类名
$widget = Yii::createObject($config); //实例化类
$out = $widget->run();//运行部件 return ob_get_clean() . $out; //返回内部缓冲区的内容，关闭缓冲区
} private $_id; /**
* Returns the ID of the widget. 返回插件的标识
* @param boolean $autoGenerate whether to generate an ID if it is not set previously
* 是否生成一个唯一标识，如果没有设置
* @return string ID of the widget. 部件唯一标识
*/
public function getId($autoGenerate = true)
{
if ($autoGenerate && $this->_id === null) {
//如果标识为空，并且设置为允许自动生成标识，自动生成
$this->_id = static::$autoIdPrefix . static::$counter++;
} return $this->_id;
} /**
* Sets the ID of the widget. 设置小部件标识
* @param string $value id of the widget. 部件的标识。
*/
public function setId($value)
{
$this->_id = $value;
} private $_view; /**
* Returns the view object that can be used to render views or view files.返回视图对象
* The [[render()]] and [[renderFile()]] methods will use
* this view object to implement the actual view rendering.
* [render()]和[renderFile()]方法用视图对象实现实际的视图显示。
* If not set, it will default to the "view" application component.
* @return \yii\web\View the view object that can be used to render views or view files.
*/
public function getView()
{
if ($this->_view === null) {
$this->_view = Yii::$app->getView();//如果视图对象为空，调用getView()取得视图对象实例
} return $this->_view;
} /**
* Sets the view object to be used by this widget. 设置当前部件调用的视图对象实例
* @param View $view the view object that can be used to render views or view files.
*/
public function setView($view)
{
$this->_view = $view;//要用的视图对象
} /**
* Executes the widget. 执行部件
* @return string the result of widget execution to be outputted.
* 控件执行的结果输出。
*/
public function run()
{
} /**
* Renders a view.
* The view to be rendered can be specified in one of the following formats:
* 渲染一个视图 实际调用View类中的同名方法 渲染的视图可以用下列方式指定路径
* - path alias (e.g. "@app/views/site/index");
* - absolute path within application (e.g. "//site/index"): the view name starts with double slashes.
* The actual view file will be looked for under the [[Application::viewPath|view path]] of the application.
* - absolute path within module (e.g. "/site/index"): the view name starts with a single slash.
* The actual view file will be looked for under the [[Module::viewPath|view path]] of the currently
* active module.
* - relative path (e.g. "index"): the actual view file will be looked for under [[viewPath]].
*
* If the view name does not contain a file extension, it will use the default one `.php`.
*
* @param string $view the view name. 视图名
* @param array $params the parameters (name-value pairs) that should be made available in the view.
* 在视图中可用的参数
* @return string the rendering result. 渲染结果
* @throws InvalidParamException if the view file does not exist.
*/
public function render($view, $params = [])
{
//调用view类中的render渲染指定的视图
return $this->getView()->render($view, $params, $this);
} /**
* Renders a view file. 渲染一个视图文件 同上
* @param string $file the view file to be rendered. This can be either a file path or a path alias.
* @param array $params the parameters (name-value pairs) that should be made available in the view.
* @return string the rendering result.
* @throws InvalidParamException if the view file does not exist.
*/
public function renderFile($file, $params = [])
{
return $this->getView()->renderFile($file, $params, $this);
} /**
* Returns the directory containing the view files for this widget. 返回视图文件路径
* The default implementation returns the 'views' subdirectory under the directory containing the widget class file.
* @return string the directory containing the view files for this widget.
*/
public function getViewPath()
{
$class = new ReflectionClass($this);
//取得部件类文件的目录，拼接为视图目录
return dirname($class->getFileName()) . DIRECTORY_SEPARATOR . 'views';
}
}