yii2源碼學習筆記(二十），yii2源碼學習筆記

Widget類是所有部件的基類。yii2\base\Widget.php

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

?