包 | system.web.widgets |
---|---|
继承 | class CAutoComplete » CInputWidget » CWidget » CBaseController » CComponent |
源自 | 1.0 |
版本 | $Id: CAutoComplete.php 3515 2011-12-28 12:29:24Z mdomba $ |
源码 |
CAutoComplete基于jQuery Autocomplete。
从1.1.3版开始,这个类被弃用。考虑使用CJuiAutoComplete代替。 这儿是 a good migration guide from the author of both JavaScript solutions.
公共属性
属性 | 类型 | 描述 | 定义在 |
---|---|---|---|
actionPrefix | string | actions的ID的前缀。 当微件在CController::actions中声明了 动作提供者,可以为其动作的ID指定前缀以区别 于别的微件或控制器。当微件用于控制器 的视图中时,必须配置同样的前缀。 | CWidget |
attribute | string | the 与此小物件相关联的属性。 这个名字可以包含方括号 (e. | CInputWidget |
autoFill | boolean | 在选择值的过程中,如果有更多的键盘输入或者鼠标选择, 是否自动填充内容到输入框中。默认值是false。 | CAutoComplete |
cacheLength | integer | 后台查询的结果保存在缓存中的数量。 如果设置为1(即当前结果),将不会进行缓存。此值必须大于等于1。默认值是10。 | CAutoComplete |
controller | CController | 返回此微件所属的控制器。 | CWidget |
cssFile | mixed | 此微件使用的CSS文件。默认值是null,表示 使用包含在此微件中的默认CSS文件。 如果设置为false,将不会使用CSS文件。其他情况下,指定 的CSS文件将被包含在此微件中。 | CAutoComplete |
data | array | 可以存储为客户端数据的数组,用于提供候选项。 每个数组元素可以是一个字符串或一个关联数组。 如果设置了此属性值,url属性将被忽略。 | CAutoComplete |
delay | integer | 自动输入控件在接收到一次击键后 延迟多少毫秒后被激活。默认值是400。 | CAutoComplete |
extraParams | array | 后端的额外参数。如果你指定了 array('bar'=>4),此自动输入控件将调用一个GET参数'bar=4' 调用后端程序。此参数可以是一个函数,此函数在每次 请求之前被调用来计算参数的值。 | CAutoComplete |
formatItem | string | 一个JavaScript函数,它可以对一个条目进行高级标识。 对于结果集中的每一行,此函数都将被调用。返回值将被显示结果集列表 中的一个LI元素中。自动输入控件提供了四个参数:组成结果集的行, 每一行在结果集列表中的位置(从1开始),结果集列表中条目的数量, 以及搜索关键词。 默认行为是假设一个单一的行包含一个单一的值。 | CAutoComplete |
formatMatch | string | 一个JavaScript函数,它用于限制自动完成控件将查找的 匹配数据。例如,你有一些条目希望显示给用户看到,但不希望它们被 包含在搜索出的数据中。此函数的调用参数与formatItem一致, 默认行为也与formatItem一致。 | CAutoComplete |
formatResult | string | 一个JavaScript函数,它为需要放到输入域的值提供了 格式。再次重复三个参数:数据,位置(从1开始)和数据项的总数。 默认值行为可以是用作结果集的简单数据,也可以是同样的值 提供给formatItem。 | CAutoComplete |
highlight | boolean|string | 是否、如何匹配选择框的高度。 设置为false将禁用,设置为一个Javascript函数可以进行自定义。 此函数获取此值作为第一个参数,搜索关键词作为第二个参数, 然后返回格式化后的值。默认行为是将搜索关键词以<strong>元素包装。 | CAutoComplete |
htmlOptions | array | 渲染输入标签时附加的HTML选项 | CInputWidget |
id | string | 返回此微件的ID。如果需要的话,将生产一个新的ID并将其返回。 | CWidget |
inputClass | string | 输入元素使用的CSS类。默认值是"ac_input"。 | CAutoComplete |
loadingClass | string | 从后端加载数据时使用的CSS类。默认值是"ac_loading"。 | CAutoComplete |
matchCase | boolean | 比较时是否大小写敏感。仅在你使用缓存时此属性值 才是重要的。默认值是false。 | CAutoComplete |
matchContains | boolean | 是否在结果集中进行比较(例如,是否“ba” 匹配“foo bar”)。仅当你使用缓存时此属性值才是重要的。 请别与自动填充(autofill)混淆。默认值是false。 | CAutoComplete |
matchSubset | boolean | 此自动输入控件是否可以为更多特定的查询使用 同一个缓存。可以这么理解:所有匹配"foot"的结果集,是一个 所有匹配"foo"的结果集的子集。通常此属性设置为true,通过 使用它可以降低服务器的负荷和增加性能。此属性仅在cacheLength 的设置值大于1时有用,例如10。默认值是true。 | CAutoComplete |
max | integer | 在选择框中的条目数的限制。它也将作为 "limit"传递给一个远程请求。默认值是10。 | CAutoComplete |
methodChain | string | 若干方法调用的链,将被附加到自动输入控件的构造方法的结尾部分。 例如,". | CAutoComplete |
minChars | integer | 用户至少需要输入几个字符才会 激活自动输入控件。默认值是1。 | CAutoComplete |
model | CModel | 与此小物件相关联的数据模型。 | CInputWidget |
multiple | boolean | 是否允许输入多于一个的自动完成的值。默认值是false。 | CAutoComplete |
multipleSeparator | string | 当使用多选项时插入到值之间的分隔符。默认值是“,”。 | CAutoComplete |
mustMatch | boolean | 如果设置为true,此自动输入控件将仅允许 后台提供的选项。无效值在输入框中是空白。 默认值是false。 | CAutoComplete |
name | string | 输入控件的名字。如果model没有设置,则必须设置此属性。 | CInputWidget |
options | array | 将被传递给自动完成js对象的额外选项。
它允许你覆盖现有的自动完成js类的函数(例如,parse()函数)。
如果你希望提供本地化的JavaScript代码,你需要在引号中的字符串 的前面加上“js:”前缀。 |
CAutoComplete |
owner | CBaseController | 返回此微件的所有者或创建者。 | CWidget |
resultsClass | string | 下拉列表使用的CSS类。默认值是"ac_results"。 | CAutoComplete |
scroll | boolean | 当结果集超过了scrollHeight设置的可用高度时,是否允许卷动。默认值是true。 | CAutoComplete |
scrollHeight | integer | 可卷动的自动完成控件的高度。默认值是180。 | CAutoComplete |
selectFirst | boolean | 如果设置为true,当按下tab键或回车键时, 第一个候选项将被选中,即使它没有被使用键盘或鼠标手动 选中。如果已有一个手动选中的选项(已加亮),该选项将 被优先选中。默认值是true。 | CAutoComplete |
skin | mixed | 微件使用的皮肤的名称。默认为“default”。 如果此属性设置为false,微件将不会有皮肤被使用。 | CWidget |
textArea | boolean | whether 是否使用多行文本区来显示自动输入域。默认值是false, 表示使用一个文本输入框。 | CAutoComplete |
url | string|array | 可以返回候选项的URL。 同时传递到此URL的还有一个名为“q”的GET参数,此参数包含了用户最新的输入信息。 如果此URL给定为一个数组,它将被认为是一个路由,指向一个控制器的动作,并使用 CController::createUrl来生成一个URL; 如果此URL给定为一个空字符串,则将使用当前的URL。 如果data已设置,则此属性被忽略。 | CAutoComplete |
value | string | 输入控件的值 | CInputWidget |
viewPath | string | 返回包含此微件所需的视图文件的路径。 | CWidget |
width | integer | 为选择框指定一个自定义宽度。默认值是此输入元素的宽度。 | CAutoComplete |
受保护属性
属性 | 类型 | 描述 | 定义在 |
---|---|---|---|
clientOptions | array | JavaScript的选项。 | CAutoComplete |
公共方法
受保护方法
方法 | 描述 | 定义在 |
---|---|---|
getClientOptions() | 返回JavaScript的选项。 | CAutoComplete |
hasModel() | 确定此小物件是否与一个数据模型相关联。 | CInputWidget |
resolveNameID() | CInputWidget |
属性详细
在选择值的过程中,如果有更多的键盘输入或者鼠标选择, 是否自动填充内容到输入框中。默认值是false。
后台查询的结果保存在缓存中的数量。 如果设置为1(即当前结果),将不会进行缓存。此值必须大于等于1。默认值是10。
JavaScript的选项。
此微件使用的CSS文件。默认值是null,表示 使用包含在此微件中的默认CSS文件。 如果设置为false,将不会使用CSS文件。其他情况下,指定 的CSS文件将被包含在此微件中。
可以存储为客户端数据的数组,用于提供候选项。 每个数组元素可以是一个字符串或一个关联数组。 如果设置了此属性值,url属性将被忽略。
参见
自动输入控件在接收到一次击键后 延迟多少毫秒后被激活。默认值是400。
后端的额外参数。如果你指定了 array('bar'=>4),此自动输入控件将调用一个GET参数'bar=4' 调用后端程序。此参数可以是一个函数,此函数在每次 请求之前被调用来计算参数的值。
一个JavaScript函数,它可以对一个条目进行高级标识。 对于结果集中的每一行,此函数都将被调用。返回值将被显示结果集列表 中的一个LI元素中。自动输入控件提供了四个参数:组成结果集的行, 每一行在结果集列表中的位置(从1开始),结果集列表中条目的数量, 以及搜索关键词。 默认行为是假设一个单一的行包含一个单一的值。
一个JavaScript函数,它用于限制自动完成控件将查找的 匹配数据。例如,你有一些条目希望显示给用户看到,但不希望它们被 包含在搜索出的数据中。此函数的调用参数与formatItem一致, 默认行为也与formatItem一致。
一个JavaScript函数,它为需要放到输入域的值提供了 格式。再次重复三个参数:数据,位置(从1开始)和数据项的总数。 默认值行为可以是用作结果集的简单数据,也可以是同样的值 提供给formatItem。
是否、如何匹配选择框的高度。 设置为false将禁用,设置为一个Javascript函数可以进行自定义。 此函数获取此值作为第一个参数,搜索关键词作为第二个参数, 然后返回格式化后的值。默认行为是将搜索关键词以<strong>元素包装。
输入元素使用的CSS类。默认值是"ac_input"。
从后端加载数据时使用的CSS类。默认值是"ac_loading"。
比较时是否大小写敏感。仅在你使用缓存时此属性值 才是重要的。默认值是false。
是否在结果集中进行比较(例如,是否“ba” 匹配“foo bar”)。仅当你使用缓存时此属性值才是重要的。 请别与自动填充(autofill)混淆。默认值是false。
此自动输入控件是否可以为更多特定的查询使用 同一个缓存。可以这么理解:所有匹配"foot"的结果集,是一个 所有匹配"foo"的结果集的子集。通常此属性设置为true,通过 使用它可以降低服务器的负荷和增加性能。此属性仅在cacheLength 的设置值大于1时有用,例如10。默认值是true。
在选择框中的条目数的限制。它也将作为 "limit"传递给一个远程请求。默认值是10。
若干方法调用的链,将被附加到自动输入控件的构造方法的结尾部分。 例如,".result(function(...){})" 将使得在用户选择了一个选项之后,指定的 js函数被执行。
用户至少需要输入几个字符才会 激活自动输入控件。默认值是1。
是否允许输入多于一个的自动完成的值。默认值是false。
当使用多选项时插入到值之间的分隔符。默认值是“,”。
如果设置为true,此自动输入控件将仅允许 后台提供的选项。无效值在输入框中是空白。 默认值是false。
将被传递给自动完成js对象的额外选项。
它允许你覆盖现有的自动完成js类的函数(例如,parse()函数)。
如果你希望提供本地化的JavaScript代码,你需要在引号中的字符串
的前面加上“js:”前缀。
下拉列表使用的CSS类。默认值是"ac_results"。
当结果集超过了scrollHeight设置的可用高度时,是否允许卷动。默认值是true。
可卷动的自动完成控件的高度。默认值是180。
如果设置为true,当按下tab键或回车键时, 第一个候选项将被选中,即使它没有被使用键盘或鼠标手动 选中。如果已有一个手动选中的选项(已加亮),该选项将 被优先选中。默认值是true。
whether 是否使用多行文本区来显示自动输入域。默认值是false, 表示使用一个文本输入框。
可以返回候选项的URL。 同时传递到此URL的还有一个名为“q”的GET参数,此参数包含了用户最新的输入信息。 如果此URL给定为一个数组,它将被认为是一个路由,指向一个控制器的动作,并使用 CController::createUrl来生成一个URL; 如果此URL给定为一个空字符串,则将使用当前的URL。 如果data已设置,则此属性被忽略。
参见
为选择框指定一个自定义宽度。默认值是此输入元素的宽度。
方法详细
protected array getClientOptions()
| ||
{return} | array | JavaScript的选项。 |
protected function getClientOptions()
{
static $properties=array(
'minChars', 'delay', 'cacheLength', 'matchSubset',
'matchCase', 'matchContains', 'mustMatch', 'selectFirst',
'extraParams', 'multiple', 'multipleSeparator', 'width',
'autoFill', 'max', 'scroll', 'scrollHeight', 'inputClass',
'formatItem', 'formatMatch', 'formatResult', 'highlight',
'resultsClass', 'loadingClass');
static $functions=array('formatItem', 'formatMatch', 'formatResult', 'highlight');
$options=$this->options;
foreach($properties as $property)
{
if($this->$property!==null)
$options[$property]=$this->$property;
}
foreach($functions as $func)
{
if(is_string($this->$func) && strncmp($this->$func,'js:',3))
$options[$func]='js:'.$this->$func;
}
return $options;
}
public void init()
|
public function init()
{
list($name,$id)=$this->resolveNameID();
if(isset($this->htmlOptions['id']))
$id=$this->htmlOptions['id'];
else
$this->htmlOptions['id']=$id;
if(isset($this->htmlOptions['name']))
$name=$this->htmlOptions['name'];
$this->registerClientScript();
if($this->hasModel())
{
$field=$this->textArea ? 'activeTextArea' : 'activeTextField';
echo CHtml::$field($this->model,$this->attribute,$this->htmlOptions);
}
else
{
$field=$this->textArea ? 'textArea' : 'textField';
echo CHtml::$field($name,$this->value,$this->htmlOptions);
}
}
初始化此微件。 此方法注册所有必须的客户端脚本然后渲染 自动输入控件。
public void registerClientScript()
|
public function registerClientScript()
{
$id=$this->htmlOptions['id'];
$acOptions=$this->getClientOptions();
$options=$acOptions===array()?'{}' : CJavaScript::encode($acOptions);
$cs=Yii::app()->getClientScript();
$cs->registerCoreScript('autocomplete');
if($this->data!==null)
$data=CJavaScript::encode($this->data);
else
{
$url=CHtml::normalizeUrl($this->url);
$data='"'.$url.'"';
}
$cs->registerScript('Yii.CAutoComplete#'.$id,"jQuery(\"#{$id}\").legacyautocomplete($data,{$options}){$this->methodChain};");
if($this->cssFile!==false)
self::registerCssFile($this->cssFile);
}
注册必须的CSS和JavaScript。
public static void registerCssFile(string $url=NULL)
| ||
$url | string | CSS文件的URL。如果为null,将使用默认值的CSS文件的URL。 |
public static function registerCssFile($url=null)
{
$cs=Yii::app()->getClientScript();
if($url===null)
$url=$cs->getCoreScriptUrl().'/autocomplete/jquery.autocomplete.css';
$cs->registerCssFile($url);
}
注册必须的CSS文件。