ajaxToolkit:AutoCompleteExtender 用法详解

尽管有点难以置信, 但事实确实是, 在google搜索ajaxToolkit:AutoCompleteExtender , 我的一篇文章(ajaxToolkit:AutoCompleteExtender的自定义参数（contextKey) )排在第二位, 而且网上关于这个控件的文章似乎也并不多, 于是我有了充分的理由再写一篇关于这个控件的详细介绍. 1. ajaxToolkit ajaxToolkit 是微软官方的一个ajax控件包, 里面有大概一二十个效果相当漂亮的控件, AutoCompleteExtender 就是其中之一. 这个控件包可以在http://www.asp.net/ajax/downloads/default.aspx?wwwaspnetrdirset=1 下载. 下载完成以后, 在包里可以找到一个AjaxControlToolkit.dll , 把它放进自己项目的bin目录, 然后在需要引用的页面上加上Register 指令即可. 例如, 我的示例页面的指令: <%@ Register Assembly="AjaxControlToolkit" Namespace="AjaxControlToolkit" TagPrefix="ajaxToolkit" %> 2. AutoCompleteExtender 的效果(功能) 如下图所示, 当在文本框中录入1 时, 所有包括1 的串都被显示出来, 当录入123 的时候, 包括123 的串被显示出来, 在这个下拉列表中单击选 中某一项, 则文本框的值改变为选中的项的值. (当选中某项时需要触发事件, 或想使用键值对的话, 请参阅我的另一篇文章ajaxToolkit:AutoCompleteExtender 的触发选择事件以及JSON序列化和使用键值对. 值得注意的是: 下拉列表中的项与文本框中录入的内容的关联的规则是自己定义的, 例如, 示例图中, 录入1时, 凡是包括1的串都被显示了出来, 无论1 在这个串的什么位置都可以, 但是可能你希望只显示以1 开头的串, 你只需要修改一下服务方法的实现即可, 稍后我会演示做法. 3. 使用AutoCompleteExtender 既然名为Extender, 就说明它是一个扩展控件, 它必须依赖于别人而存在-----这个别人指的是文本框. 所以, 首先要有一个宿主文本框: 这就是一个默认的文本框, 不需要任何多余的设定. 然后定义一个AutoCompleteExtender, 这里我们只设置了最基本的选项, 其它的选项后面我会说明: 这样 , 前台的工作就完成了, 然后还需要添加一个web 服务, 来向AutoCompleteExtender返回数据. 向项目中添加一个"web服务"文件. 添加以后, 会在项目中生成一个webservice.asmx 文件, 不用管它, 因为使用了代码分离, 所以它只是一个路径引用, 用记事本打开它, 会发现这个文件只有一行, 指向App_Code 下面的同名, 但是扩展名为.cs 的文件. 我们现在打开App_Code目录, 找到webservice.cs , 会看到这样的几行: [WebService(Namespace = "http://tempuri.org/")] [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)] [System.Web.Script.Services.ScriptService] public class WebService : System.Web.Services.WebService 默认情况下, 第三行属性[System.Web.Script.Services.ScriptService] 是被注释掉的, 把它打开 , 因为我们要在客户端调用. 然后就可以写入我们的方法了, 方法如下: [WebMethod] public string[] GetData(string prefixText, int count) { string[] data = new string[10000]; for (int i = 0; i < data.Length; i++) data[i] = i.ToString("0000"); return data.Where(p => p.IndexOf(prefixText) >= 0).Take(count).ToArray(); } 这个函数的第一个参数, 就是用户录入的内容, 第二个参数, 是定义中指定的下拉列表长度, 也就是要返回的项的个数, 我们在定义中没有指定长度, 它会使用一个默认长度10 . 函数的最后一句使用的是LINQ 的方法, 如果你对这个方法不熟, 也可以用自己熟悉的方式去返回数组, 总之, 我们只要在这里返回一个与输入有关的string型数组就可以了. 如果希望返回以录入开头的串, 则把p => p.IndexOf(prefixText) >= 0 改为p => p.StartWith(prefixText) 即可. 到现在为止, 我们的准备工作已经结束了, 启动页面看一下效果吧, 在文本框中录入1 , 弹出下拉列表, 包括 0001, 0011, 0012 等前十项包括1 的串. 4. AutoCompleteExtender的其它属性 虽然到现在这个程度它已经可以动起来了, 但是还有很多属性我们没有用到, 下面我们逐个了解它的其它属性. TargetControlID 这是必须指定的属性, 它指出Extender 应该寄宿到哪个控件身上, 上面的例子已经演示了它的用法, 就把目标控件的ID 赋给它即可. ServicePath 指出要使用的服务的路径, 这里指的是asmx文件的路径, 而不是cs文件, 因为这里两个文件都处于根目录, 所以直接写入了文件名, 如果两个文件不在同一目录, 还要指出该asmx文件所在的路径. 例如: ../xx.asmx . ServiceMethod 返回数据的函数, 填入目标函数名即可. MinimumPrefixLength 最少需要录入的长度, 因为我们指定了1, 所以只要敲入一个字符, 就会立即弹出下拉列表, 如果把这个值改为3, 则至少要录入3个字符, 才会弹出下拉列表. ContextKey 关于这个属性我有专门的一篇文章介绍, 请参阅ajaxToolkit:AutoCompleteExtender的自定义参数（contextKey) UseContextKey 如果指定了ContextKey参数, 这个属性会被默认置为true, 所以一般不用去管这个参数 , 不过如果因为某种原因程序出了异常-----我就遇到过这种情况, 没有指定ContextKey参数, 但它非要调用包含ContextKey 的形式-----就可以显式地指定这个参数为true 或false. CompletionInterval 它的单位是毫秒, 就是用户录入后多长时间, 程序去调用服务来获取数据 , 一般我设这个属性的值为1000. 或不设, 用它默认的值. EnableCaching 这是一个要非常小心的属性, 如果把它设为true, 允许缓存, 则, 例如, 我第一次录入1, 返回包括1 的串, 然后我修改了数据源, 再次录入1, 还是返回以前的串, 在调试模式下, 在服务那边下断点, 会看到程序根本没有进来. 也就是说, 对于同样的录入, 控件只获取一次数据, 有多数情况下, 这是有益的, 它可以减少数据访问的次数, 但是在数据源经常变化的情况下, 它就是致命的, 它会向用户提供过时的, 错误的信息. CompletionSetCount 这个属性指定一次应该返回多少项, 我们上面没有指定它, 返回了10项, 如果我们希望返回20项, 就指定它为20 即可. CompletionListCssClass, CompletionListItemCssClass 和 CompletionListHighlightedItemCssClass 背景样式, 条目样式, 和鼠标悬念时所指向的条目的样式. DelimiterCharacters 如果允许一次选中多项, 中间的分隔符 , 我个人感觉这个很容易造成混乱, 最好把它的值设成空, 也就是不允许选中多项. FirstRowSelected 是否默认选中第一项.