CTreeView - system.web.widgets - [ Yii中文参考手册 ]

所有包 | 属性 | 方法

包	system.web.widgets
继承	class CTreeView » CWidget » CBaseController » CComponent
源自	1.0
版本	$Id: CTreeView.php 3144 2011-03-30 07:03:48Z mdomba $
源码

CTreeView 显示分层数据的树形图。

这个类封装了jQuery的一个优秀的树形图插件 (http://bassistance.de/jquery-plugins/jquery-plugin-treeview/).

要使用CTreeView，只需要简单地将data设置为你所需要表现的数据即可。

CTreeView也支持通过AJAX动态地加载数据。要完成此目的，设置 url为可以根据请求提供树形图所需数据的URL。

公共属性

属性	类型	描述	定义在
actionPrefix	string	actions的ID的前缀。当微件在CController::actions中声明了动作提供者，可以为其动作的ID指定前缀以区别于别的微件或控制器。当微件用于控制器的视图中时，必须配置同样的前缀。	CWidget
animated	string\|integer	动画速度。这个值可以是三个预定义的速度之一 ("slow", "normal", or "fast")或以毫秒为单位的数值（例如 1000）。如果没有设置，将不会使用动画效果。	CTreeView
collapsed	boolean	树形图是否随着所有分支收起而开始。默认值是false。	CTreeView
control	string	一个树形控件的容器，允许用户通过一次点击完成展开、收起和开关所有分支。在此容器中，点击第一个超链接将收起树形图；第二个超链接展开树形图；第三个超链接用于开关树形图。这个属性是一个有效的jQuery选择器（例如，“#treecontrol”。这儿“treecontrol”是包含有这些超链接的“DIV”元素的ID）。	CTreeView
controller	CController	返回此微件所属的控制器。	CWidget
cookieId	string	通过"cookie"进行持久化时使用的cookie的名字。默认值为“treeview”。	CTreeView
cssFile	mixed	此微件使用的CSS文件。默认为null，表示使用此微件包含的默认CSS文件。如果设置为false，则不使用CSS文件。其他情况下，指定的CSS文件将被包含在此微件中。	CTreeView
data	array	用于生成树形图内容的数据。每个数据元素按以下格式对应于一个树形图节点： text: string, required, 与此节点关联的HTML文本。 expanded: boolean, optional, 此节点是否为已展开状态。 id: string, optional, 识别此节点的ID。用于动态加载树形图（参见url）。 hasChildren: boolean, optional, 默认值为false，点击此节点是否触发从服务器动态加态更多树形图节点。必须设置url属性以使此选项生效。 children: array, optional, 此节点的子节点。 htmlOptions: array, 附加的HTML属性（参见CHtml::tag）。此选项从1.	CTreeView
htmlOptions	array	需要在UL标签中进行渲染的附加HTML属性。树形图预定义了下列CSS类，可以直接使用它们： treeview-black treeview-gray treeview-red treeview-famfamfam filetree	CTreeView
id	string	返回此微件的ID。如果需要的话，将生产一个新的ID并将其返回。	CWidget
options	array	传递给树形图的JavaScript对象的构造器的附加选项。	CTreeView
owner	CBaseController	返回此微件的所有者或创建者。	CWidget
persist	string	将树的状态持久化到cookies中或页面位置中。如果设置为“location”，寻找匹配“location.	CTreeView
prerendered	boolean	此属性设置为真时将不对点击区DIV标签和CSS类渲染，假设服务器端已完成此工作。默认值是false。	CTreeView
skin	mixed	微件使用的皮肤的名称。默认为“default”。如果此属性设置为false，微件将不会有皮肤被使用。	CWidget
toggle	string	开关一个分支时调用的回调函数。参数：“this”指向UL表明是显示或隐藏	CTreeView
unique	boolean	设置此属性可以实现在同一层次仅可展开一个分支（在展开时将关闭兄弟分支）。默认值是false。	CTreeView
url	string\|array	用于树形图动态加载的URL（使用AJAX）。参见CHtml::normalizeUrl以了解可用的URL格式。设置此属性将使树形图的动态加载可用。当页面显示后，浏览器将使用一个名为“root”，值为“source”的 GET参数请求这个URL。服务器脚本将根据树形图的根生成所需的树形图数据（参见saveDataAsJson）。如果一个节点有CSS类“hasChildren”，那么展开这个节点将导致对它的子节点的动态加载。在这种情况下，GET参数“root”的值是此节点的ID属性值。	CTreeView
viewPath	string	返回包含此微件所需的视图文件的路径。	CWidget

受保护属性

属性	类型	描述	定义在
clientOptions	array	返回JavaScript选项。	CTreeView

公共方法

方法	描述	定义在
__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()	初始化此微件。	CTreeView
raiseEvent()	发起一个事件。	CComponent
render()	渲染一个视图。	CWidget
renderFile()	Renders a view file.	CBaseController
renderInternal()	Renders a view file.	CBaseController
run()	结束此微件的运行。	CTreeView
saveDataAsHtml()	根据数组中的数据，在HTML页面生成树形图的节点。	CTreeView
saveDataAsJson()	将树形图数据保存为JSON格式。	CTreeView
setId()	设置此微件的ID。	CWidget
widget()	Creates a widget and executes it.	CBaseController

受保护方法

方法	描述	定义在
getClientOptions()	返回返回JavaScript选项。	CTreeView

属性详细

animated 属性

public string|integer $animated;

动画速度。这个值可以是三个预定义的速度之一 ("slow", "normal", or "fast")或以毫秒为单位的数值（例如 1000）。如果没有设置，将不会使用动画效果。

clientOptions 属性只读

protected array getClientOptions()

返回JavaScript选项。

collapsed 属性

public boolean $collapsed;

树形图是否随着所有分支收起而开始。默认值是false。

control 属性

public string $control;

一个树形控件的容器，允许用户通过一次点击完成展开、收起和开关所有分支。在此容器中，点击第一个超链接将收起树形图；第二个超链接展开树形图；第三个超链接用于开关树形图。这个属性是一个有效的jQuery选择器（例如，“#treecontrol”。这儿“treecontrol”是包含有这些超链接的“DIV”元素的ID）。

cookieId 属性

public string $cookieId;

通过"cookie"进行持久化时使用的cookie的名字。默认值为“treeview”。

cssFile 属性

public mixed $cssFile;

此微件使用的CSS文件。默认为null，表示使用此微件包含的默认CSS文件。如果设置为false，则不使用CSS文件。其他情况下，指定的CSS文件将被包含在此微件中。

data 属性

public array $data;

用于生成树形图内容的数据。每个数据元素按以下格式对应于一个树形图节点：

text: string, required, 与此节点关联的HTML文本。
expanded: boolean, optional, 此节点是否为已展开状态。
id: string, optional, 识别此节点的ID。用于动态加载树形图（参见url）。
hasChildren: boolean, optional, 默认值为false，点击此节点是否触发从服务器动态加态更多树形图节点。必须设置url属性以使此选项生效。
children: array, optional, 此节点的子节点。
htmlOptions: array, 附加的HTML属性（参见CHtml::tag）。此选项从1.1.7版开始可用。

注意：包含在“beginWidget”和“endWidget”这两个调用之间的任何内容也将作为树形图的内容看待，被添加到这个属性生成的内容之后。

htmlOptions 属性

public array $htmlOptions;

需要在UL标签中进行渲染的附加HTML属性。树形图预定义了下列CSS类，可以直接使用它们：

treeview-black
treeview-gray
treeview-red
treeview-famfamfam
filetree

options 属性

public array $options;

传递给树形图的JavaScript对象的构造器的附加选项。

persist 属性

public string $persist;

将树的状态持久化到cookies中或页面位置中。如果设置为“location”，寻找匹配“location.href”的锚并激活它在树形图中的部分。常用于基于超链接的状态保存。如果设置为“cookie”，在每次点击后会将树的状态保存到一个cookie中，然后在页面加载时恢复它。

prerendered 属性

public boolean $prerendered;

此属性设置为真时将不对点击区DIV标签和CSS类渲染，假设服务器端已完成此工作。默认值是false。

toggle 属性

public string $toggle;

开关一个分支时调用的回调函数。参数：“this”指向UL表明是显示或隐藏

unique 属性

public boolean $unique;

设置此属性可以实现在同一层次仅可展开一个分支（在展开时将关闭兄弟分支）。默认值是false。

url 属性

public string|array $url;

用于树形图动态加载的URL（使用AJAX）。参见CHtml::normalizeUrl以了解可用的URL格式。设置此属性将使树形图的动态加载可用。当页面显示后，浏览器将使用一个名为“root”，值为“source”的 GET参数请求这个URL。服务器脚本将根据树形图的根生成所需的树形图数据（参见saveDataAsJson）。如果一个节点有CSS类“hasChildren”，那么展开这个节点将导致对它的子节点的动态加载。在这种情况下，GET参数“root”的值是此节点的ID属性值。

方法详细

getClientOptions() 方法

protected array getClientOptions()
{return}	array	返回JavaScript选项。


protected function getClientOptions()
{
    $options=$this->options;
    foreach(array('url','animated','collapsed','control','unique','toggle','persist','cookieId','prerendered') as $name)
    {
        if($this->$name!==null)
            $options[$name]=$this->$name;
    }
    return $options;
}

init() 方法

public void init()


public function init()
{
    if(isset($this->htmlOptions['id']))
        $id=$this->htmlOptions['id'];
    else
        $id=$this->htmlOptions['id']=$this->getId();
    if($this->url!==null)
        $this->url=CHtml::normalizeUrl($this->url);
    $cs=Yii::app()->getClientScript();
    $cs->registerCoreScript('treeview');
    $options=$this->getClientOptions();
    $options=$options===array()?'{}' : CJavaScript::encode($options);
    $cs->registerScript('Yii.CTreeView#'.$id,"jQuery(\"#{$id}\").treeview($options);");
    if($this->cssFile===null)
        $cs->registerCssFile($cs->getCoreScriptUrl().'/treeview/jquery.treeview.css');
    else if($this->cssFile!==false)
        $cs->registerCssFile($this->cssFile);

    echo CHtml::tag('ul',$this->htmlOptions,false,false)."\n";
    echo self::saveDataAsHtml($this->data);
}

初始化此微件。此方法注册所有必须的客户端脚本然后渲染树形图的内容。

run() 方法

public void run()


public function run()
{
    echo "</ul>";
}

结束此微件的运行。

saveDataAsHtml() 方法

public static string saveDataAsHtml(array $data)
$data	array	树形图所用的数据（参见data了解可用的数据结构）。
{return}	string	生成的树形图的HTML代码。


public static function saveDataAsHtml($data)
{
    $html='';
    if(is_array($data))
    {
        foreach($data as $node)
        {
            if(!isset($node['text']))
                continue;

            if(isset($node['expanded']))
                $css=$node['expanded'] ? 'open' : 'closed';
            else
                $css='';

            if(isset($node['hasChildren']) && $node['hasChildren'])
            {
                if($css!=='')
                    $css.=' ';
                $css.='hasChildren';
            }

            $options=isset($node['htmlOptions']) ? $node['htmlOptions'] : array();
            if($css!=='')
            {
                if(isset($options['class']))
                    $options['class'].=' '.$css;
                else
                    $options['class']=$css;
            }

            if(isset($node['id']))
                $options['id']=$node['id'];

            $html.=CHtml::tag('li',$options,$node['text'],false);
            if(!empty($node['children']))
            {
                $html.="\n<ul>\n";
                $html.=self::saveDataAsHtml($node['children']);
                $html.="</ul>\n";
            }
            $html.=CHtml::closeTag('li')."\n";
        }
    }
    return $html;
}

根据数组中的数据，在HTML页面生成树形图的节点。

saveDataAsJson() 方法

public static string saveDataAsJson(array $data)
$data	array	树形图所用的数据（参见data了解可用的数据结构）。
{return}	string	以JSON格式表示的数据


public static function saveDataAsJson($data)
{
    if(empty($data))
        return '[]';
    else
        return CJavaScript::jsonEncode($data);
}

将树形图数据保存为JSON格式。通常在当服务器端代码需要将树形图数据发送到客户端时使用此方法。