Widget類是所有部件的基類。yii2\base\Widget.php
1 <?php
2 /**
3 * @link http://www.yiiframework.com/
4 * @copyright Copyright (c) 2008 Yii Software LLC
5 * @license http://www.yiiframework.com/license/
6 */
7
8 namespace yii\base;
9
10 use Yii;
11 use ReflectionClass;
12
13 /**
14 * Widget is the base class for widgets.
15 * Widget是所有小部件的基類
16 * @property string $id ID of the widget. 小部件標識
17 * @property \yii\web\View $view The view object that can be used to render views or view files. Note that the
18 * type of this property differs in getter and setter. See [[getView()]] and [[setView()]] for details.
19 * 用於渲染視圖或視圖文件的視圖對象 在getter 和 setter中是不同的
20 * @property string $viewPath The directory containing the view files for this widget. This property is
21 * read-only. 包含此控件的視圖文件目錄
22 *
23 * @author Qiang Xue <qiang.xue@gmail.com>
24 * @since 2.0
25 */
26 class Widget extends Component implements ViewContextInterface
27 {
28 /**
29 * @var integer a counter used to generate [[id]] for widgets.
30 * @internal 用於生成widget ID的計數器
31 */
32 public static $counter = 0;
33 /**
34 * @var string the prefix to the automatically generated widget IDs.
35 * @see getId() 自動生成的前綴
36 */
37 public static $autoIdPrefix = 'w';
38 /**
39 * @var Widget[] the widgets that are currently being rendered (not ended). This property
40 * is maintained by [[begin()]] and [[end()]] methods. 目前正在渲染的小部件
41 * @internal
42 */
43 public static $stack = [];
44
45
46 /**
47 * Begins a widget. 開始一個部件
48 * This method creates an instance of the calling class. It will apply the configuration
49 * to the created instance. A matching [[end()]] call should be called later.
50 * 將應用配置文件創建調用類的實例，與[end()]方法相對應
51 * @param array $config name-value pairs that will be used to initialize the object properties
52 * 用於初始化屬性的參數
53 * @return static the newly created widget instance 靜態新創建的部件實例
54 */
55 public static function begin($config = [])
56 {
57 $config['class'] = get_called_class();//後期靜態綁定類的名稱
58 /* @var $widget Widget */
59 $widget = Yii::createObject($config);//通過類名和傳入的配置，實例化調用類
60 static::$stack[] = $widget;//將對象放入正在渲染的部件堆棧中
61
62 return $widget;
63 }
64
65 /**
66 * Ends a widget. 結束小部件
67 * Note that the rendering result of the widget is directly echoed out.渲染結果是直接呼應的
68 * @return static the widget instance that is ended. 靜態結束的部件實例。
69 * @throws InvalidCallException if [[begin()]] and [[end()]] calls are not properly nested
70 */
71 public static function end()
72 {
73 if (!empty(static::$stack)) {//正在呈現的小部件堆棧中存在調用類實例
74 $widget = array_pop(static::$stack);//從堆棧中刪除最後一個實例
75 if (get_class($widget) === get_called_class()) {
76 echo $widget->run(); //如果刪除的實例類名和當前調用類名相同，輸出小部件的內容
77 return $widget;
78 } else {
79 throw new InvalidCallException("Expecting end() of " . get_class($widget) . ", found " . get_called_class());
80 }
81 } else {
82 throw new InvalidCallException("Unexpected " . get_called_class() . '::end() call. A matching begin() is not found.');
83 }
84 }
85
86 /**
87 * Creates a widget instance and runs it. 創建一個部件實例，並運行
88 * The widget rendering result is returned by this method. 返回部件渲染的結果。
89 * @param array $config name-value pairs that will be used to initialize the object properties
90 * 用於初始化對象屬性的參數
91 * @return string the rendering result of the widget. 控件的渲染結果。
92 */
93 public static function widget($config = [])
94 {
95 ob_start(); //打開輸出緩沖區
96 ob_implicit_flush(false);//關閉絕對刷新
97 /* @var $widget Widget */
98 $config['class'] = get_called_class(); //獲取調用類的類名
99 $widget = Yii::createObject($config); //實例化類
100 $out = $widget->run();//運行部件
101
102 return ob_get_clean() . $out; //返回內部緩沖區的內容，關閉緩沖區
103 }
104
105 private $_id;
106
107 /**
108 * Returns the ID of the widget. 返回插件的標識
109 * @param boolean $autoGenerate whether to generate an ID if it is not set previously
110 * 是否生成一個唯一標識，如果沒有設置
111 * @return string ID of the widget. 部件唯一標識
112 */
113 public function getId($autoGenerate = true)
114 {
115 if ($autoGenerate && $this->_id === null) {
116 //如果標識為空，並且設置為允許自動生成標識，自動生成
117 $this->_id = static::$autoIdPrefix . static::$counter++;
118 }
119
120 return $this->_id;
121 }
122
123 /**
124 * Sets the ID of the widget. 設置小部件標識
125 * @param string $value id of the widget. 部件的標識。
126 */
127 public function setId($value)
128 {
129 $this->_id = $value;
130 }
131
132 private $_view;
133
134 /**
135 * Returns the view object that can be used to render views or view files.返回視圖對象
136 * The [[render()]] and [[renderFile()]] methods will use
137 * this view object to implement the actual view rendering.
138 * [render()]和[renderFile()]方法用視圖對象實現實際的視圖顯示。
139 * If not set, it will default to the "view" application component.
140 * @return \yii\web\View the view object that can be used to render views or view files.
141 */
142 public function getView()
143 {
144 if ($this->_view === null) {
145 $this->_view = Yii::$app->getView();//如果視圖對象為空，調用getView()取得視圖對象實例
146 }
147
148 return $this->_view;
149 }
150
151 /**
152 * Sets the view object to be used by this widget. 設置當前部件調用的視圖對象實例
153 * @param View $view the view object that can be used to render views or view files.
154 */
155 public function setView($view)
156 {
157 $this->_view = $view;//要用的視圖對象
158 }
159
160 /**
161 * Executes the widget. 執行部件
162 * @return string the result of widget execution to be outputted.
163 * 控件執行的結果輸出。
164 */
165 public function run()
166 {
167 }
168
169 /**
170 * Renders a view.
171 * The view to be rendered can be specified in one of the following formats:
172 * 渲染一個視圖 實際調用View類中的同名方法 渲染的視圖可以用下列方式指定路徑
173 * - path alias (e.g. "@app/views/site/index");
174 * - absolute path within application (e.g. "//site/index"): the view name starts with double slashes.
175 * The actual view file will be looked for under the [[Application::viewPath|view path]] of the application.
176 * - absolute path within module (e.g. "/site/index"): the view name starts with a single slash.
177 * The actual view file will be looked for under the [[Module::viewPath|view path]] of the currently
178 * active module.
179 * - relative path (e.g. "index"): the actual view file will be looked for under [[viewPath]].
180 *
181 * If the view name does not contain a file extension, it will use the default one `.php`.
182 *
183 * @param string $view the view name. 視圖名
184 * @param array $params the parameters (name-value pairs) that should be made available in the view.
185 * 在視圖中可用的參數
186 * @return string the rendering result. 渲染結果
187 * @throws InvalidParamException if the view file does not exist.
188 */
189 public function render($view, $params = [])
190 {
191 //調用view類中的render渲染指定的視圖
192 return $this->getView()->render($view, $params, $this);
193 }
194
195 /**
196 * Renders a view file. 渲染一個視圖文件 同上
197 * @param string $file the view file to be rendered. This can be either a file path or a path alias.
198 * @param array $params the parameters (name-value pairs) that should be made available in the view.
199 * @return string the rendering result.
200 * @throws InvalidParamException if the view file does not exist.
201 */
202 public function renderFile($file, $params = [])
203 {
204 return $this->getView()->renderFile($file, $params, $this);
205 }
206
207 /**
208 * Returns the directory containing the view files for this widget. 返回視圖文件路徑
209 * The default implementation returns the 'views' subdirectory under the directory containing the widget class file.
210 * @return string the directory containing the view files for this widget.
211 */
212 public function getViewPath()
213 {
214 $class = new ReflectionClass($this);
215 //取得部件類文件的目錄，拼接為視圖目錄
216 return dirname($class->getFileName()) . DIRECTORY_SEPARATOR . 'views';
217 }
218 }
