YII 类库手册
> YII 类库手册 > CWidget
包 system.web.widgets
继承 class CWidget » CBaseController » CComponent
子类 CActiveForm, CBaseListView, CBasePager, CBreadcrumbs, CCaptcha, CClipWidget, CDetailView, CFilterWidget, CFlexWidget, CInputWidget, CJuiWidget, CMenu, CPortlet, CTabView, CTreeView
源自 1.0
版本 $Id: CWidget.php 3515 2011-12-28 12:29:24Z mDOMba $
源码
CWidget是各种微件类的基类。

一个微件是自包含的组件，它可以基于模型数据显示 相应的内容。我们可以将其视为一个嵌入到控制器管理 的视图中的微控制器。

与controller相比较，微件没有既没有动作，也没有过滤器。

使用格式可参见CBaseController和CBaseController::widget。

公共属性

属性 类型 描述 定义在
actionPrefix string actions的ID的前缀。 当微件在CController::actions中声明了 动作提供者，可以为其动作的ID指定前缀以区别 于别的微件或控制器。当微件用于控制器 的视图中时，必须配置同样的前缀。 CWidget
controller CController 返回此微件所属的控制器。 CWidget
id string 返回此微件的ID。如果需要的话，将生产一个新的ID并将其返回。 CWidget
owner CBaseController 返回此微件的所有者或创建者。 CWidget
skin mixed 微件使用的皮肤的名称。默认为“default”。 如果此属性设置为false，微件将不会有皮肤被使用。 CWidget
viewPath string 返回包含此微件所需的视图文件的路径。 CWidget

公共方法

方法 描述 定义在
__call() 如果类中没有调的方法名，则调用这个方法。 CComponent
__construct() 构造器。 CWidget
__get() 返回一个属性值、一个事件处理程序列表或一个行为名称。 CComponent
__isset() 检查一个属性是否为null。 CComponent
__set() 设置一个组件的属性值。 CComponent
__unset() 设置一个组件的属性为null。 CComponent
actions() 返回此widget使用的动作的列表。 CWidget
asa() 返回这个名字的行为对象。 CComponent
attachBehavior() 附加一个行为到组件。 CComponent
attachBehaviors() 附加一个行为列表到组件。 CComponent
attachEventHandler() 为事件附加一个事件处理程序。 CComponent
beginCache() Begins fragment caching. CBaseController
beginClip() Begins recording a clip. CBaseController
beginContent() Begins the rendering of content that is to be decorated by the specified view. CBaseController
beginWidget() Creates a widget and executes it. CBaseController
canGetProperty() 确定属性是否可读。 CComponent
canSetProperty() 确定属性是否可写。 CComponent
createWidget() Creates a widget and initializes it. CBaseController
detachBehavior() 从组件中分离一个行为。 CComponent
detachBehaviors() 从组件中分离所有行为。 CComponent
detachEventHandler() 分离一个存在的事件处理程序。 CComponent
disableBehavior() 禁用一个附加行为。 CComponent
disableBehaviors() 禁用组件附加的所有行为。 CComponent
enableBehavior() 启用一个附加行为。 CComponent
enableBehaviors() 启用组件附加的所有行为。 CComponent
endCache() Ends fragment caching. CBaseController
endClip() Ends recording a clip. CBaseController
endContent() Ends the rendering of content. CBaseController
endWidget() Ends the execution of the named widget. CBaseController
evaLuateExpression() 计算一个PHP表达式，或根据组件上下文执行回调。 CComponent
getController() 返回此微件所属的控制器。 CWidget
getEventHandlers() 返回一个事件的附加处理程序列表。 CComponent
getId() 返回此微件的ID。如果需要的话，将生产一个新的ID并将其返回。 CWidget
getOwner() 返回此微件的所有者或创建者。 CWidget
getViewFile() 根据视图名查找视图文件。 CWidget
getViewPath() 返回包含此微件所需的视图文件的路径。 CWidget
hasEvent() 确定一个事件是否定义。 CComponent
hasEventHandler() 检查事件是否有附加的处理程序。 CComponent
hasProperty() 确定属性是否被定义。 CComponent
init() 初始化此微件。 CWidget
raiseEvent() 发起一个事件。 CComponent
render() 渲染一个视图。 CWidget
renderFile() Renders a view file. CBaseController
renderInternal() Renders a view file. CBaseController
run() 运行此微件。 CWidget
setId() 设置此微件的ID。 CWidget
widget() Creates a widget and executes it. CBaseController

属性详细

actionPrefix 属性
public string $actionPrefix;

actions的ID的前缀。 当微件在CController::actions中声明了 动作提供者，可以为其动作的ID指定前缀以区别 于别的微件或控制器。当微件用于控制器 的视图中时，必须配置同样的前缀。

controller 属性 只读
public CController getController()

返回此微件所属的控制器。

id 属性
public string getId(boolean $autoGenerate=true)
public void setId(string $value)

返回此微件的ID。如果需要的话，将生产一个新的ID并将其返回。

owner 属性 只读
public CBaseController getOwner()

返回此微件的所有者或创建者。

skin 属性 （可用自 v1.1）
public mixed $skin;

微件使用的皮肤的名称。默认为“default”。 如果此属性设置为false，微件将不会有皮肤被使用。

参见

  • CWidgetFactory
viewPath 属性 只读
public string getViewPath(boolean $checkTheme=false)

返回包含此微件所需的视图文件的路径。 默认情况下返回此微件类文件所在目录的“views”子目录， 如果$checkTheme设置为true, 将返回“ThemeID/views/ClassName”目录。

方法详细

__construct() 方法
public void __construct(CBaseController $owner=NULL)
$owner CBaseController 此微件的所有者或创建者。可以是微件或控制器。 

public function __construct($owner=null)
{
    $this->_owner=$owner===null?Yii::app()->getController():$owner;
}

构造器。

actions() 方法
public static array actions()
{return} array 

public static function actions()
{
    return array();
}

返回此widget使用的动作的列表。 此方法的返回值的结构与CController::actions 的返回值的结构相类似。

当一个微件使用了多个动作，你可以使用此方法声明 这些动作。这个微件将变为一个动作提供者，这些 动作可以很容易地导入到一个控制器中。

注意：当创建指向由此方法返回的动作的URL时， 确保这些动作的ID的前缀是actionPrefix。

参见

  • actionPrefix
  • CController::actions
getController() 方法
public CController getController()
{return} CController 此微件所属的控制器。 

public function getController()
{
    if($this->_owner instanceof CController)
        return $this->_owner;
    else
        return Yii::app()->getController();
}

返回此微件所属的控制器。

getId() 方法
public string getId(boolean $autoGenerate=true)
$autoGenerate boolean 如果之前未设置ID，是否自动生成ID。
{return} string 此微件的ID。 

public function getId($autoGenerate=true)
{
    if($this->_id!==null)
        return $this->_id;
    else if($autoGenerate)
        return $this->_id='yw'.self::$_counter++;
}

返回此微件的ID。如果需要的话，将生产一个新的ID并将其返回。

getOwner() 方法
public CBaseController getOwner()
{return} CBaseController 此微件的所有者或创建者。可以是微件或控制器。 

public function getOwner()
{
    return $this->_owner;
}

返回此微件的所有者或创建者。

getViewFile() 方法
public string getViewFile(string $viewName)
$viewName string 视图名（不包括扩展名）
{return} string 视图文件路径。如果视图文件不存在将返回false。 

public function getViewFile($viewName)
{
    if(($renderer=Yii::app()->getViewRenderer())!==null)
        $extension=$renderer->fileExtension;
    else
        $extension='.php';
    if(strpos($viewName,'.')) // a path alias
        $viewFile=Yii::getPathOfAlias($viewName);
    else
    {
        $viewFile=$this->getViewPath(true).DIRECTORY_SEPARATOR.$viewName;
        if(is_file($viewFile.$extension))
            return Yii::app()->findLocalizedFile($viewFile.$extension);
        else if($extension!=='.php' && is_file($viewFile.'.php'))
            return Yii::app()->findLocalizedFile($viewFile.'.php');
        $viewFile=$this->getViewPath(false).DIRECTORY_SEPARATOR.$viewName;
    }

    if(is_file($viewFile.$extension))
        return Yii::app()->findLocalizedFile($viewFile.$extension);
    else if($extension!=='.php' && is_file($viewFile.'.php'))
        return Yii::app()->findLocalizedFile($viewFile.'.php');
    else
        return false;
}

根据视图名查找视图文件。 此方法在此微件的viewPath下查找 名为“ViewName.php”的文件。如果需要国际化支持，将返 回一个本地化的视图文件。参见CApplication::findLocalizedFile 以了解更多细节。 如果视图名包含“.”符号，它指向的是一个路径别名。

参见

  • CApplication::findLocalizedFile
getViewPath() 方法
public string getViewPath(boolean $checkTheme=false)
$checkTheme boolean 是否检测此微件包含主题与否。
{return} string 包含此微件的视图文件的目录。 

public function getViewPath($checkTheme=false)
{
    $className=get_class($this);
    if(isset(self::$_viewPaths[$className]))
        return self::$_viewPaths[$className];
    else
    {
        if($checkTheme && ($theme=Yii::app()->getTheme())!==null)
        {
            $path=$theme->getViewPath().DIRECTORY_SEPARATOR;
            if(strpos($className,'\\')!==false) // namespaced class
                $path.=str_replace('\\','_',ltrim($className,'\\'));
            else
                $path.=$className;
            if(is_dir($path))
                return self::$_viewPaths[$className]=$path;
        }

        $class=new ReflectionClass($className);
        return self::$_viewPaths[$className]=dirname($class->getFileName()).DIRECTORY_SEPARATOR.'views';
    }
}

返回包含此微件所需的视图文件的路径。 默认情况下返回此微件类文件所在目录的“views”子目录， 如果$checkTheme设置为true, 将返回“ThemeID/views/ClassName”目录。

init() 方法
public void init()

public function init()
{
}

初始化此微件。 在此微件的属性被初始化后，此方法将被CBaseController::createWidget 和CBaseController::beginWidget 调用。

render() 方法
public string render(string $view, array $data=NULL, boolean $return=false)
$view string 被渲染的视图的名称。参见getViewFile以了解视图文件 解析的细节。
$data array 将作为PHP变量被导出，从而可以在视图文件中被使用的数据。
$return boolean 渲染结果作为字符串返回，而不是在屏幕上显示。
{return} string 渲染结果。如果不需要返回结果，则返回Null。 

public function render($view,$data=null,$return=false)
{
    if(($viewFile=$this->getViewFile($view))!==false)
        return $this->renderFile($viewFile,$data,$return);
    else
        throw new CException(Yii::t('yii','{widget} cannot find the view "{view}".',
            array('{widget}'=>get_class($this), '{view}'=>$view)));
}

渲染一个视图。

指定的视图指向一个PHP文件（通过getViewFile解析）， 该文件包括在此方法中。如果$data是一个关联数组， 它将作为PHP变量被导出，从而可以在视图文件中被使用。

参见

  • getViewFile
run() 方法
public void run()

public function run()
{
}

运行此微件。 这个方法被CBaseController::endWidget调用。

setId() 方法
public void setId(string $value)
$value string 此微件的ID。 

public function setId($value)
{
    $this->_id=$value;
}

设置此微件的ID。

上一篇：
下一篇：