Widget ???? ?? ??? ?? ??????. yii2baseWidget.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. 小部件標(biāo)識(shí)
</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> * 用于渲染視圖或視圖文件的視圖對(duì)象 在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的計(jì)數(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() 自動(dòng)生成的前綴
</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.  開(kāi)始一個(gè)部件
</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>     * 將應(yīng)用配置文件創(chuàng)建調(diào)用類的實(shí)例，與[end()]方法相對(duì)應(yīng)
</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)建的部件實(shí)例
</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>通過(guò)類名和傳入的配置，實(shí)例化調(diào)用類</span><span> 60</span><span>static</span>::$stack[] = $widget;<span>//</span><span>將對(duì)象放入正在渲染的部件堆棧中</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.   結(jié)束小部件
</span><span> 67</span><span>     * Note that the rendering result of the widget is directly echoed out.渲染結(jié)果是直接呼應(yīng)的
</span><span> 68</span><span>     * @return static the widget instance that is ended. 靜態(tài)結(jié)束的部件實(shí)例。
</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)用類實(shí)例</span><span> 74</span>             $widget = array_pop(<span>static</span>::$stack);<span>//</span><span>從堆棧中刪除最后一個(gè)實(shí)例</span><span> 75</span><span>if</span> (get_class($widget) ===<span> get_called_class()) {
</span><span> 76</span>                 echo $widget->run(); <span>//</span><span>如果刪除的實(shí)例類名和當(dāng)前調(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)建一個(gè)部件實(shí)例，并運(yùn)行
</span><span> 88</span><span>     * The widget rendering result is returned by this method. 返回部件渲染的結(jié)果。
</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>     * 用于初始化對(duì)象屬性的參數(shù)
</span><span> 91</span><span>     * @return string the rendering result of the widget. 控件的渲染結(jié)果。
</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>打開(kāi)輸出緩沖區(qū)</span><span> 96</span>         ob_implicit_flush(<span>false</span>);<span>//</span><span>關(guān)閉絕對(duì)刷新</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>實(shí)例化類</span><span>100</span>         $<span>out</span> = $widget->run();<span>//</span><span>運(yùn)行部件</span><span>101</span><span>102</span><span>return</span> ob_get_clean() . $<span>out</span>; <span>//</span><span>返回內(nèi)部緩沖區(qū)的內(nèi)容，關(guān)閉緩沖區(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. 返回插件的標(biāo)識(shí)
</span><span>109</span><span>     * @param boolean $autoGenerate whether to generate an ID if it is not set previously
</span><span>110</span><span>     * 是否生成一個(gè)唯一標(biāo)識(shí)，如果沒(méi)有設(shè)置
</span><span>111</span><span>     * @return string ID of the widget. 部件唯一標(biāo)識(shí)
</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>如果標(biāo)識(shí)為空，并且設(shè)置為允許自動(dòng)生成標(biāo)識(shí)，自動(dòng)生成</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. 設(shè)置小部件標(biāo)識(shí)
</span><span>125</span><span>     * @param string $value id of the widget. 部件的標(biāo)識(shí)。
</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.返回視圖對(duì)象
</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()]方法用視圖對(duì)象實(shí)現(xiàn)實(shí)際的視圖顯示。
</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>如果視圖對(duì)象為空，調(diào)用getView()取得視圖對(duì)象實(shí)例</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. 設(shè)置當(dāng)前部件調(diào)用的視圖對(duì)象實(shí)例
</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>要用的視圖對(duì)象</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í)行的結(jié)果輸出。
</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>     * 渲染一個(gè)視圖   實(shí)際調(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. 渲染結(jié)果
</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. 渲染一個(gè)視圖文件 同上
</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> }

? ??? ????? ???? ?? ??? ???? ????? ???? ?? yii2 ???? ?? ?? 20)? ??? ????. PHP ????? ??? ?? ????? ??? ???? ?????.