yii2源码学习笔记(二十），yii2源码学习笔记

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的计数器
</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>     * 将应用配置文件创建调用类的实例，与[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>     * 用于初始化属性的参数
</span><span> 53</span> <span>     * @return static the newly created widget instance 静态新创建的部件实例
</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>后期静态绑定类的名称</span>
<span> 58</span>         <span>/*</span><span> @var $widget Widget </span><span>*/</span>
<span> 59</span>         $widget = Yii::createObject($config);<span>//</span><span>通过类名和传入的配置，实例化调用类</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. 静态结束的部件实例。
</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>正在呈现的小部件堆栈中存在调用类实例</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>如果删除的实例类名和当前调用类名相同，输出小部件的内容</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.   创建一个部件实例，并运行
</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>     * 用于初始化对象属性的参数
</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>打开输出缓冲区</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>获取调用类的类名</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>返回内部缓冲区的内容，关闭缓冲区</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()]方法用视图对象实现实际的视图显示。
</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>如果视图对象为空，调用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. 设置当前部件调用的视图对象实例
</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. 执行部件
</span><span>162</span> <span>     * @return string the result of widget execution to be outputted.
</span><span>163</span> <span>     * 控件执行的结果输出。
</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>     * 渲染一个视图   实际调用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>     * 在视图中可用的参数
</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>调用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> }