Yii源码阅读笔记（三十）

  1 namespace yii\base;
  2 
  3 use Yii;
  4 use ReflectionClass;
  5 
  6 /**
  7  * Widget is the base class for widgets.
  8  * Widget是所有小部件的基类
  9  *
 10  * @property string $id ID of the widget.
 11  * @property \yii\web\View $view The view object that can be used to render views or view files. Note that the
 12  * type of this property differs in getter and setter. See [[getView()]] and [[setView()]] for details.
 13  * @property string $viewPath The directory containing the view files for this widget. This property is
 14  * read-only.
 15  *
 16  * @author Qiang Xue <qiang.xue@gmail.com>
 17  * @since 2.0
 18  */
 19 class Widget extends Component implements ViewContextInterface
 20 {
 21     /**
 22      * @var integer a counter used to generate [[id]] for widgets.
 23      * @var integer 一个用于生成widget ID的计数器
 24      * @internal
 25      */
 26     public static $counter = 0;
 27     /**
 28      * @var string the prefix to the automatically generated widget IDs.
 29      * @var string widget IDs自动生成的前缀
 30      * @see getId()
 31      */
 32     public static $autoIdPrefix = ‘w‘;
 33     /**
 34      * @var Widget[] the widgets that are currently being rendered (not ended). This property
 35      * is maintained by [[begin()]] and [[end()]] methods.
 36      * @var 目前正在呈现的小部件
 37      * @internal
 38      */
 39     public static $stack = [];
 40 
 41 
 42     /**
 43      * Begins a widget.
 44      * 开始一个小部件
 45      * This method creates an instance of the calling class. It will apply the configuration
 46      * to the created instance. A matching [[end()]] call should be called later.
 47      * 该方法将应用配置文件创建调用类的实例，有一个[[end()]]方法相对应
 48      * @param array $config name-value pairs that will be used to initialize the object properties
 49      * @return static the newly created widget instance
 50      */
 51     public static function begin($config = [])
 52     {
 53         $config[‘class‘] = get_called_class();// get_called_class -- 后期静态绑定（"Late Static Binding"）类的名称
 54                                               // 就是用那个类调用的这个方法，就返回那个类，返回值中带有 namespace
 55         /* @var $widget Widget */
 56         $widget = Yii::createObject($config);//通过类名和传入的配置，实例化调用类
 57         static::$stack[] = $widget;//将实例放入正在呈现的小部件堆栈中
 58 
 59         return $widget;//返回小部件实例
 60     }
 61 
 62     /**
 63      * Ends a widget.
 64      * 结束一个小部件
 65      * Note that the rendering result of the widget is directly echoed out.
 66      * @return static the widget instance that is ended.
 67      * @throws InvalidCallException if [[begin()]] and [[end()]] calls are not properly nested
 68      */
 69     public static function end()
 70     {
 71         if (!empty(static::$stack)) {//正在呈现的小部件堆栈中存在调用类实例
 72             $widget = array_pop(static::$stack);//则从堆栈中删除最后一个实例--调用当前小部件的实例
 73             if (get_class($widget) === get_called_class()) {//如果删除的实例的类名和当前调用类的类名相同
 74                 echo $widget->run();//输出小部件的内容
 75                 return $widget;//返回调用类实例
 76             } else {
 77                 throw new InvalidCallException(‘Expecting end() of ‘ . get_class($widget) . ‘, found ‘ . get_called_class());
 78             }
 79         } else {//抛出异常，未找到对应的begin()开始方法
 80             throw new InvalidCallException(‘Unexpected ‘ . get_called_class() . ‘::end() call. A matching begin() is not found.‘);
 81         }
 82     }
 83 
 84     /**
 85      * Creates a widget instance and runs it.
 86      * 创建一个widget实例，并运行它
 87      * The widget rendering result is returned by this method.
 88      * widget的渲染结果将被该方法返回
 89      * @param array $config name-value pairs that will be used to initialize the object properties
 90      * @return string the rendering result of the widget.
 91      * @throws \Exception
 92      */
 93     public static function widget($config = [])
 94     {
 95         ob_start();//打开一个输出缓冲区，所有的输出信息不再直接发送到浏览器，而是保存在输出缓冲区里面
 96         ob_implicit_flush(false);//打开或关闭绝对刷新，默认为关闭，打开后ob_implicit_flush(true)，
 97           //所谓绝对刷新，即当有输出语句(e.g: echo)被执行时，便把输出直接发送到浏览器，而不再需要调用flush()或等到脚本结束时才输出
 98         try {
 99             /* @var $widget Widget */
100             $config[‘class‘] = get_called_class();//获取调用类的类名
101             $widget = Yii::createObject($config);//实例化调用类
102             $out = $widget->run();//运行widget
103         } catch (\Exception $e) {
104             // close the output buffer opened above if it has not been closed already
105             if (ob_get_level() > 0) {//返回输出缓冲机制的嵌套级别
106                 ob_end_clean();//删除内部缓冲区的内容，关闭缓冲区(不输出)
107             }
108             throw $e;
109         }
110 
111         return ob_get_clean() . $out;//返回内部缓冲区的内容，关闭缓冲区
112     }