Android source code learning yii2 source code learning notes 19)

<span>  1</span><span>/*</span><span>*
</span><span>  2</span><span>     * @return string|boolean the view file currently being rendered. False if no view file is being rendered.
</span><span>  3</span><span>     * 当前正在渲染的视图文件
</span><span>  4</span><span>*/</span><span>  5</span><span>public</span><span> function getViewFile()
</span><span>  6</span><span>    {
</span><span>  7</span><span>return</span> end($<span>this</span>-><span>_viewFiles);
</span><span>  8</span><span>    }
</span><span>  9</span><span> 10</span><span>/*</span><span>*
</span><span> 11</span><span>     * This method is invoked right before [[renderFile()]] renders a view file.
</span><span> 12</span><span>     * The default implementation will trigger the [[EVENT_BEFORE_RENDER]] event.
</span><span> 13</span><span>     * 前置事件，执行[renderFile()]时被调用，默认触发[[EVENT_BEFORE_RENDER]]事件
</span><span> 14</span><span>     * If you override this method, make sure you call the parent implementation first.
</span><span> 15</span><span>     * @param string $viewFile the view file to be rendered. 要渲染的视图文件。
</span><span> 16</span><span>     * @param array $params the parameter array passed to the [[render()]] method.
</span><span> 17</span><span>     * 参数数组传递到[render()]方法。
</span><span> 18</span><span>     * @return boolean whether to continue rendering the view file. 是否继续渲染视图文件。
</span><span> 19</span><span>*/</span><span> 20</span><span>public</span> function beforeRender($viewFile, $<span>params</span><span>)
</span><span> 21</span><span>    {
</span><span> 22</span>         $<span>event</span> = <span>new</span> ViewEvent([<span>//</span><span>实例化ViewEvent</span><span> 23</span><span>'</span><span>viewFile</span><span>'</span> =><span> $viewFile,
</span><span> 24</span><span>'</span><span>params</span><span>'</span> => $<span>params</span><span>,
</span><span> 25</span><span>        ]);
</span><span> 26</span>         $<span>this</span>->trigger(self::EVENT_BEFORE_RENDER, $<span>event</span>);<span>//</span><span>触发[EVENT_BEFORE_RENDER]事件</span><span> 27</span><span> 28</span><span>return</span> $<span>event</span>->isValid;<span>//</span><span>判断是否继续渲染文件</span><span> 29</span><span>    }
</span><span> 30</span><span> 31</span><span>/*</span><span>*
</span><span> 32</span><span>     * This method is invoked right after [[renderFile()]] renders a view file.
</span><span> 33</span><span>     * The default implementation will trigger the [[EVENT_AFTER_RENDER]] event.
</span><span> 34</span><span>     * 后置事件，在执行[renderFile()]方法后被调用，默认触发[[EVENT_AFTER_RENDER]]事件
</span><span> 35</span><span>     * If you override this method, make sure you call the parent implementation first.
</span><span> 36</span><span>     * @param string $viewFile the view file being rendered.要渲染的视图文件。
</span><span> 37</span><span>     * @param array $params the parameter array passed to the [[render()]] method.
</span><span> 38</span><span>     * 参数数组传递到[render()]方法。
</span><span> 39</span><span>     * @param string $output the rendering result of the view file. Updates to this parameter
</span><span> 40</span><span>     * will be passed back and returned by [[renderFile()]].
</span><span> 41</span><span>     * 返回视图渲染的结果
</span><span> 42</span><span>*/</span><span> 43</span><span>public</span> function afterRender($viewFile, $<span>params</span>, &<span>$output)
</span><span> 44</span><span>    {
</span><span> 45</span><span>if</span> ($<span>this</span>->hasEventHandlers(self::EVENT_AFTER_RENDER)) {<span>//</span><span>判断[EVENT_AFTER_RENDER]事件是否存在</span><span> 46</span>             $<span>event</span> = <span>new</span><span> ViewEvent([
</span><span> 47</span><span>'</span><span>viewFile</span><span>'</span> =><span> $viewFile,
</span><span> 48</span><span>'</span><span>params</span><span>'</span> => $<span>params</span><span>,
</span><span> 49</span><span>'</span><span>output</span><span>'</span> =><span> $output,
</span><span> 50</span><span>            ]);
</span><span> 51</span><span>//</span><span>触发[EVENT_AFTER_RENDER]事件</span><span> 52</span>             $<span>this</span>->trigger(self::EVENT_AFTER_RENDER, $<span>event</span><span>);
</span><span> 53</span>             $output = $<span>event</span>->output;<span>//</span><span>返回结果</span><span> 54</span><span>        }
</span><span> 55</span><span>    }
</span><span> 56</span><span> 57</span><span>/*</span><span>*
</span><span> 58</span><span>     * Renders a view file as a PHP script.
</span><span> 59</span><span>     * 返回一个视图文件当作PHP脚本
</span><span> 60</span><span>     * This method treats the view file as a PHP script and includes the file.
</span><span> 61</span><span>     * It extracts the given parameters and makes them available in the view file.
</span><span> 62</span><span>     * The method captures the output of the included view file and returns it as a string.
</span><span> 63</span><span>     * 将传入的参数转换为变量，包含并执行view文件，返回执行结果
</span><span> 64</span><span>     * This method should mainly be called by view renderer or [[renderFile()]].
</span><span> 65</span><span>     *
</span><span> 66</span><span>     * @param string $_file_ the view file. 视图文件
</span><span> 67</span><span>     * @param array $_params_ the parameters (name-value pairs) that will be extracted and made available in the view file.
</span><span> 68</span><span>     * @return string the rendering result 执行结果
</span><span> 69</span><span>*/</span><span> 70</span><span>public</span> function renderPhpFile($_file_, $_params_ =<span> [])
</span><span> 71</span><span>    {
</span><span> 72</span>         ob_start(); <span>//</span><span>打开输出缓冲</span><span> 73</span>         ob_implicit_flush(<span>false</span>); <span>//</span><span>关闭缓冲区</span><span> 74</span>         extract($_params_, EXTR_OVERWRITE);<span>//</span><span> 将一个数组转换为变量使用</span><span> 75</span><span>        require($_file_);
</span><span> 76</span><span> 77</span><span>return</span> ob_get_clean();<span>//</span><span>得到缓冲区的内容并清除当前输出缓冲</span><span> 78</span><span>    }
</span><span> 79</span><span> 80</span><span>/*</span><span>*
</span><span> 81</span><span>     * Renders dynamic content returned by the given PHP statements. 渲染动态内容
</span><span> 82</span><span>     * This method is mainly used together with content caching (fragment caching and page caching)
</span><span> 83</span><span>     * 用来聚合缓存的内容
</span><span> 84</span><span>     * when some portions of the content (called *dynamic content*) should not be cached.
</span><span> 85</span><span>     * The dynamic content must be returned by some PHP statements.
</span><span> 86</span><span>     * 渲染某些被PHP语句返回的动态内容
</span><span> 87</span><span>     * @param string $statements the PHP statements for generating the dynamic content.生成动态内容的PHP语句。
</span><span> 88</span><span>     * @return string the placeholder of the dynamic content, or the dynamic content if there is no
</span><span> 89</span><span>     * active content cache currently. 动态内容占位符 如果当前没有有效的内容缓存，调用evaluateDynamicContent输出
</span><span> 90</span><span>*/</span><span> 91</span><span>public</span><span> function renderDynamic($statements)
</span><span> 92</span><span>    {
</span><span> 93</span><span>if</span> (!empty($<span>this</span>->cacheStack)) {<span>//</span><span>动态内容的列表不为空</span><span> 94</span>             $n = count($<span>this</span>->dynamicPlaceholders);<span>//</span><span>统计动态内容条数</span><span> 95</span>             $placeholder = <span>"</span><span><![CDATA[YII-DYNAMIC-$n]]></span><span>"</span>;<span>//</span><span>生成占位符</span><span> 96</span>             $<span>this</span>->addDynamicPlaceholder($placeholder, $statements);<span>//</span><span>添加动态内容占位符</span><span> 97</span><span> 98</span><span>return</span><span> $placeholder;
</span><span> 99</span>         } <span>else</span> {<span>//</span><span>没有有效缓存 执行传入的PHP语句，返回执行结果</span><span>100</span><span>return</span> $<span>this</span>-><span>evaluateDynamicContent($statements);
</span><span>101</span><span>        }
</span><span>102</span><span>    }
</span><span>103</span><span>104</span><span>/*</span><span>*
</span><span>105</span><span>     * Adds a placeholder for dynamic content. 添加一个动态内容占位符
</span><span>106</span><span>     * This method is internally used. 内部使用
</span><span>107</span><span>     * @param string $placeholder the placeholder name 占位符名称
</span><span>108</span><span>     * @param string $statements the PHP statements for generating the dynamic content
</span><span>109</span><span>     * 生成动态内容的PHP语句
</span><span>110</span><span>*/</span><span>111</span><span>public</span><span> function addDynamicPlaceholder($placeholder, $statements)
</span><span>112</span><span>    {
</span><span>113</span><span>foreach</span> ($<span>this</span>->cacheStack <span>as</span><span> $cache) {
</span><span>114</span>             $cache->dynamicPlaceholders[$placeholder] = $statements;<span>//</span><span>添加动态内容占位符</span><span>115</span><span>        }
</span><span>116</span>         $<span>this</span>->dynamicPlaceholders[$placeholder] = $statements;<span>//</span><span>给当前视图添加动态内容占位符</span><span>117</span><span>    }
</span><span>118</span><span>119</span><span>/*</span><span>*
</span><span>120</span><span>     * Evaluates the given PHP statements. 给定的PHP语句的值
</span><span>121</span><span>     * This method is mainly used internally to implement dynamic content feature.内部使用实现动态内容功能
</span><span>122</span><span>     * @param string $statements the PHP statements to be evaluated. PHP语句进行计算
</span><span>123</span><span>     * @return mixed the return value of the PHP statements. PHP语句的值
</span><span>124</span><span>*/</span><span>125</span><span>public</span><span> function evaluateDynamicContent($statements)
</span><span>126</span><span>    {
</span><span>127</span><span>return</span><span> eval($statements);
</span><span>128</span><span>    }
</span><span>129</span><span>130</span><span>/*</span><span>*
</span><span>131</span><span>     * Begins recording a block.
</span><span>132</span><span>     * This method is a shortcut to beginning [[Block]]
</span><span>133</span><span>     * 数据块开始的标记，该方法是开始[Block]的快捷方式
</span><span>134</span><span>     * 数据块可以在一个地方指定视图内容在另一个地方显示，通常和布局一起使用
</span><span>135</span><span>     * @param string $id the block ID. 数据块标识
</span><span>136</span><span>     * @param boolean $renderInPlace whether to render the block content in place. 是否渲染块内容。
</span><span>137</span><span>     * Defaults to false, meaning the captured block will not be displayed.
</span><span>138</span><span>     * @return Block the Block widget instance 数据块部件实例
</span><span>139</span><span>*/</span><span>140</span><span>public</span> function beginBlock($id, $renderInPlace = <span>false</span><span>)
</span><span>141</span><span>    {
</span><span>142</span><span>return</span><span> Block::begin([
</span><span>143</span><span>'</span><span>id</span><span>'</span> => $id,<span>//</span><span>数据块唯一标识</span><span>144</span><span>'</span><span>renderInPlace</span><span>'</span> => $renderInPlace,<span>//</span><span>是否显示标识</span><span>145</span><span>'</span><span>view</span><span>'</span> => $<span>this</span><span>,
</span><span>146</span><span>        ]);
</span><span>147</span><span>    }
</span><span>148</span><span>149</span><span>/*</span><span>*
</span><span>150</span><span>     * Ends recording a block. 数据块结束标识
</span><span>151</span><span>*/</span><span>152</span><span>public</span><span> function endBlock()
</span><span>153</span><span>    {
</span><span>154</span><span>        Block::end();
</span><span>155</span><span>    }
</span><span>156</span><span>157</span><span>/*</span><span>*
</span><span>158</span><span>     * Begins the rendering of content that is to be decorated by the specified view.
</span><span>159</span><span>     * This method can be used to implement nested layout. For example, a layout can be embedded
</span><span>160</span><span>     * in another layout file specified as '@app/views/layouts/base.php' like the following:
</span><span>161</span><span>     * 开始指定的view渲染内容，用来实现嵌套布局，传入的第一个参数为布局文件的路径
</span><span>162</span><span>     * ~~~
</span><span>163</span><span>     * <?php $this->beginContent('@app/views/layouts/base.php'); ?>
</span><span>164</span><span>     * ...layout content here...
</span><span>165</span><span>     * <?php $this->endContent(); ?>
</span><span>166</span><span>     * ~~~
</span><span>167</span><span>     *
</span><span>168</span><span>     * @param string $viewFile the view file that will be used to decorate the content enclosed by this widget.
</span><span>169</span><span>     * This can be specified as either the view file path or path alias.布局文件的路径或路径别名。
</span><span>170</span><span>     * @param array $params the variables (name => value) to be extracted and made available in the decorative view.
</span><span>171</span><span>     * 可以在视图中运用的参数
</span><span>172</span><span>     * @return ContentDecorator the ContentDecorator widget instance 部件实例
</span><span>173</span><span>     * @see ContentDecorator
</span><span>174</span><span>*/</span><span>175</span><span>public</span> function beginContent($viewFile, $<span>params</span> =<span> [])
</span><span>176</span><span>    {
</span><span>177</span><span>return</span><span> ContentDecorator::begin([
</span><span>178</span><span>'</span><span>viewFile</span><span>'</span> =><span> $viewFile,
</span><span>179</span><span>'</span><span>params</span><span>'</span> => $<span>params</span><span>,
</span><span>180</span><span>'</span><span>view</span><span>'</span> => $<span>this</span><span>,
</span><span>181</span><span>        ]);
</span><span>182</span><span>    }
</span><span>183</span><span>184</span><span>/*</span><span>*
</span><span>185</span><span>     * Ends the rendering of content.结束渲染内容
</span><span>186</span><span>*/</span><span>187</span><span>public</span><span> function endContent()
</span><span>188</span><span>    {
</span><span>189</span><span>        ContentDecorator::end();
</span><span>190</span><span>    }
</span><span>191</span><span>192</span><span>/*</span><span>*
</span><span>193</span><span>     * Begins fragment caching. 开始片段缓存
</span><span>194</span><span>     * This method will display cached content if it is available.
</span><span>195</span><span>     * If not, it will start caching and would expect an [[endCache()]]
</span><span>196</span><span>     * call to end the cache and save the content into cache.
</span><span>197</span><span>     * 展示可用的缓存内容，否则将开始缓存内容直到出现[endCache()]方法
</span><span>198</span><span>     * A typical usage of fragment caching is as follows,
</span><span>199</span><span>     *
</span><span>200</span><span>     * ~~~
</span><span>201</span><span>     * if ($this->beginCache($id)) {
</span><span>202</span><span>     *     // ...generate content here
</span><span>203</span><span>     *     $this->endCache();
</span><span>204</span><span>     * }
</span><span>205</span><span>     * ~~~
</span><span>206</span><span>     *
</span><span>207</span><span>     * @param string $id a unique ID identifying the fragment to be cached.缓存片段的唯一标识
</span><span>208</span><span>     * @param array $properties initial property values for [[FragmentCache]]初始属性[FragmentCache]
</span><span>209</span><span>     * @return boolean whether you should generate the content for caching. 是否生成缓存的内容。
</span><span>210</span><span>     * False if the cached version is available.
</span><span>211</span><span>*/</span><span>212</span><span>public</span> function beginCache($id, $properties =<span> [])
</span><span>213</span><span>    {
</span><span>214</span>         $properties[<span>'</span><span>id</span><span>'</span>] = $id;    <span>//</span><span>片段标识</span><span>215</span>         $properties[<span>'</span><span>view</span><span>'</span>] = $<span>this</span>;    <span>//</span><span>调用初始化属性</span><span>216</span><span>/*</span><span> @var $cache FragmentCache </span><span>*/</span><span>217</span>         $cache =<span> FragmentCache::begin($properties); 
</span><span>218</span><span>if</span> ($cache->getCachedContent() !== <span>false</span><span>) {
</span><span>219</span>             $<span>this</span>->endCache();<span>//</span><span>从缓存中读取到了缓存的内容，则渲染内容并返回 false，不再进行缓存</span><span>220</span><span>221</span><span>return</span><span>false</span><span>;
</span><span>222</span>         } <span>else</span><span> {
</span><span>223</span><span>return</span><span>true</span><span>;
</span><span>224</span><span>        }
</span><span>225</span><span>    }
</span><span>226</span><span>227</span><span>/*</span><span>*
</span><span>228</span><span>     * Ends fragment caching. 结束片段缓存
</span><span>229</span><span>*/</span><span>230</span><span>public</span><span> function endCache()
</span><span>231</span><span>    {
</span><span>232</span><span>        FragmentCache::end();
</span><span>233</span><span>    }
</span><span>234</span><span>235</span><span>/*</span><span>*
</span><span>236</span><span>     * Marks the beginning of a page.页面开始标记
</span><span>237</span><span>*/</span><span>238</span><span>public</span><span> function beginPage()
</span><span>239</span><span>    {
</span><span>240</span>         ob_start(); <span>//</span><span>打开输出缓冲</span><span>241</span>         ob_implicit_flush(<span>false</span>);<span>//</span><span>关闭缓冲区</span><span>242</span><span>243</span>         $<span>this</span>-><span>trigger(self::EVENT_BEGIN_PAGE);
</span><span>244</span><span>    }
</span><span>245</span><span>246</span><span>/*</span><span>*
</span><span>247</span><span>     * Marks the ending of a page. 页面结束标记
</span><span>248</span><span>*/</span><span>249</span><span>public</span><span> function endPage()
</span><span>250</span><span>    {
</span><span>251</span>         $<span>this</span>-><span>trigger(self::EVENT_END_PAGE);
</span><span>252</span>         ob_end_flush();<span>//</span><span>关闭输出缓冲区</span><span>253</span>     }