Android source code learning yii2 source code learning notes 20)

<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> 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> }