经过数个版本的迭代后, JQueryElement 3.3.0 版本中的 Repeater 基本上已经完善, 这里将分功能的总结讲解一下 Repeater 的使用方法.

本文更新:

2011-12-12: 去掉 ParameterList.

由于精力有限, 不能在多个博客中保证文章的同步, 可在如下地址查看最新内容, 请谅解:

请到 的 JQueryElement 示例下载一节下载示例代码

本文中所包含的内容如下:

  * 准备

  * 主要功能

    * 绑定字段

      * 字段表达式

    * 绑定属性

      * 属性表达式

    * 基本设置

    * 设置分页

    * 设置字段

    * 设置调用的服务端方法

    * 请求/返回数据的格式

      * 填充/搜索

      * 更新

      * 删除

      * 新建

    * 行状态说明

    * 排序状态说明

    * 设置模板

      * ItemTemplate

      * UpdatedItemTemplate/InsertedItemTemplate

      * RemovedItemTemplate

      * EditItemTemplate

      * FilterTemplate/NewItemTemplate

      * HeaderTemplate/FooterTemplate/EmptyTemplate

    * 特殊绑定

      * je-id

      * je-<javascript 事件名>

      * je-class

      * je-checked/selected/readonly

      * je-value

      * je-<jQueryUI 插件名>

      * je-template

    * 子视图

    * 数据分组

    * 处理控件

    * 消息提示

    * 检索数据

    * 排序

    * 事件

    * 客户端方法

Repeater 示例图片:

准备

请确保已经在 中下载 JQueryElement 最新的版本.

请使用指令引用如下的命名空间:

<%@ Register Assembly="zoyobar.shared.panzer.JQueryElement"     Namespace="zoyobar.shared.panzer.ui.jqueryui"     TagPrefix="je"%> <%@ Register Assembly="zoyobar.shared.panzer.JQueryElement"     Namespace="zoyobar.shared.panzer.web.jqueryui"     TagPrefix="je"%>

除了命名空间, 还需要引用 jQueryUI 的脚本和样式, 在 下载的压缩包中包含了一个自定义样式的 jQueryUI, 如果需要更多样式, 可以在  下载:

主要功能

绑定字段

在行模板中, 可以使用 #{<字段名>} 的形式来绑定字段, 比如:

      
      #{id} 
      #{realname} 
      #{age} 
     

字段也可以被绑定在标签的属性中, 比如:

      
      #{id} 
      #{realname} 
      #{age} 
     

字段表达式

当需要根据字段的值显示不同内容时, 可以使用字段表达式, 在表达式中 # 将表示字段本身, 示例:

      #{age,convertAge(#)} 

在上面的例子中, #{age,convertAge(#)} 并不会直接输出 age 字段的值, 而是将 age 字段传递给 convertAge 函数, 然后将函数执行的结果输出.

除了调用函数外, 也可以直接书写 javascript 代码, 比如: #{age,# <= 0 ? '不可能吧' : #.toString()}.

绑定属性

在所有的模板中都可以绑定属性, 语法为 @{<属性名>}, 比如:

     
           第 @{pageindex}/@{pagecount} 页, @{itemcount} 条 
     

属性表达式

属性表达式和上面的字段表达式是类似的, 可以输出转换后的属性, 示例:

     第 @{pageindex}/@{pagecount,@ <= 0 ? '-' : @} 页, @{itemcount,@ <= 0 ? '-' : @} 条 

我们判断属性 pagecount 和 itemcount 如果小于等于 0, 则显示连接线.

基本设置

Repeater 的 Selector 属性是一个 javascript 表达式, 它将作为一个选择器, 写法可以参照 , 选择器对应的元素将作为页面上最终的 repeater 来呈现, 示例:

      
     
           /* ... */ 
     

设置 IsVariable 属性为 True, 则将在客户端生成与 ClientID 同名的 javascript 变量, 示例:

由于在此页面中 ClientID 与 ID 相同, 因此通过 studentRepeater 就可以访问 repeater. 此外, 也可以通过 JQueryScript 控件并使用内嵌语法 [%id:studentRepeater%] 来确保 ClientID 与 ID 不相同的页面也能访问 repeater 变量.

设置分页

通过 Repeater 的 PageSize 属性设置每页包含多少条数据, PageIndex 属性设置初始的页码, PageIndex 默认为 1.

设置字段

Repeater 的 Field 属性表示参与绑定的字段, 其形式为一个 javascript 字符串数组, 比如: ['id', 'realname', 'age'], 如果不设置 Field 属性, 则由第一次填充的数据来确定, 但这将导致在没有数据的情况下无法新建.

FilterField 表示用于搜索的字段, 也是一个 javascript 字符串数组. FilterFieldDefault 为搜索字段的值为 null 或者 '' 时的默认值, 示例: ['', '', 0].

SortField 表示参与排序的字段, 比如: ['id'].

FieldMask 表示用于验证字段的正则表达式, 在更新或新建时起效, 一般格式为: {<字段名>: { reg: <正则表达式>, tip: '<错误提示信息>', type: '<字段类型, 可以是 number, boolean, date>'} }.

设置调用的服务端方法

可以通过 Async 来设置如何调用服务器端方法, 如果是调用 WebService, 则需要设置 MethodName, 如果是普通的 ashx 这样的一般处理程序, 则忽略 MethodName, 示例:

     
           /* ... */ 
      
     
           /* ... */ 
     

如果, 你需要为方法传递更多的参数, 则可以采用下面的形式:

      
       
        
         
                 /* ... */ 
        
       
      
      
       
        
         
                 /* ... */ 
        
       
     

通过添加 Parameter, 可以传递更多的参数, Name 为参数名, Type 为 Expression 时, 则 Value 中包含的是一个 javascript 表达式, 示例中的 Value="website" 表示取 javascript 变量 website 的值, 当然也可以设置为常量, 比如: Value="'www.google.com'" 或者 Value="100", 当 Type 为 Selector 时, 则 Value 中的 javascript 表达式将作为选择器, 选择器的写法可以参照 , 选择器对应的元素的值将作为参数的值. Default 中是默认值的 javascript 表达式, 当参数的值为 null 或者 '' 时, 将采用 Default 中的值.

请求/返回数据的格式

填充/搜索

对于填充或者搜索操作, 以 WebService 为例, 服务端将接收如下参数, pageindex 页码, pagesize 每页中包含数据条数, 还可以接收与字段同名的参数或者通过 Parameter 增加的参数作为搜索条件, 或者接收形式为 __order 的用于排序的参数, 参数的值类似于 name asc, age desc, __group 形式的参数则用于接收分组的条件:

[WebMethod ( )] publicstaticobject
     <方法名称>
       ( int pageindex, int pagesize     [, 
      <类型n, 如: string>
       <用于搜索的字段或条件名称n>
        ]     [, string__order][, string __group] ) {
    } [WebMethod ( )] publicstaticobject Fill ( int pageindex, int pagesize     , string realname, int age     , string __order ) {
    }
       
      
     

服务器还应返回如下格式的 json 数据作为填充数据, 其中 __success 默认为 true, itemcount 可以省略, 但将无法计算 pagecount 页码.

{
    "__success": 
     <表示是否成功的布尔值, 为 true 或者 false>
      , "rows": 
      <当前页包含行数据的 javascript 数组>
       , "itemcount": 
       <总行数>
             [, "custom": 
        
         ] } {
    "__success": true, "rows":     [         { "id": 1, "realname": "jack", "age": 20 },         { "id": 2, "realname": "tom", "age": 21 }     ], "itemcount": 120 }
        
       
      
     

在 .NET 4.0 中可以使用匿名类型来返回 json, 比如:

[WebMethod ( )] publicstaticobject Fill ( /* 参数 */ ) {
    // ...     List

更新

删除

新建

以上 3 项由于篇幅原因无法全部列出, 如有需要请参考:

行状态说明

在客户端的 javascript 脚本中, 行状态有 4 种, 分别是 unchanged 未改变, updated 更新过, inserted 新建后的行, removed 删除后的行.

排序状态说明

在客户端的 javascript 脚本中, 排序状态有 3 种, 分别是 none 无排序或按照默认排序, asc 升序, desc 降序.

设置模板

在 Repeater 的各种模板中, 可以设置 Repeater 最终显示的 html 代码, 这些 html 代码应该是完整的, 合法的, 否则可能导致最终显示的不正常.

ItemTemplate

ItemTemplate 为行模板中的一种, 可以显示处于 unchanged 状态的行, 如果没有设置 UpdatedItemTemplate 或者 InsertedItemTemplate, 那么 updated, inserted 状态的行也显示在 ItemTemplate 中, 示例:

                    #{id}               #{realname}               #{age}               /* 编辑和删除按钮 */   
     

UpdatedItemTemplate/InsertedItemTemplate

与 ItemTemplate 不同的是, UpdatedItemTemplate 和 InsertedItemTemplate 分别用于显示状态为 updated 和 inserted 的行, 主要用于采用不同样式来显示不同状态的行, 但也可以使用更简便的 je-class 来完成同样的效果, 示例:

                    #{id}               #{realname}               #{age}   
      
                    #{id}               #{realname}               #{age}   
     

RemovedItemTemplate

EditItemTemplate

FilterTemplate/NewItemTemplate

HeaderTemplate/FooterTemplate/EmptyTemplate

以上 4 项由于篇幅原因无法全部列出, 如有需要请参考:

特殊绑定

je-id

使用 je-id="<字段名>" 可以绑定特殊的 id, 可以使用在行模板或者 FilterTemplate, NewItemTemplate 中的 input 元素中. 在 EditItemTemplate 中, 被指定 je-id 的 input 将包含此字段的新值. 在 FilterTemplate 中, 指定 je-id 的 input 包含了用于搜索的字段的值, 这些字段应该包含在 FilterField 属性中. 在 NewItemTemplate 中, 指定 je-id 的 input 包含了用于新建的字段的值.

je-<javascript 事件名>

使用 je-<javascript 事件名>="<行为名>" 可以为事件绑定特殊的操作. 可以使用在各个模板中, 常用的行为有: beginedit 开始编辑, endedit 取消编辑, update 保存更新, remove 删除, toggleselect 切换选中状态, insert 新建, filter 搜索, togglesort 切换排序. 其中, 前 5 者只能用在行模板中, insert 可用在 NewItemTemplate 中, filter 可用在 FilterTemplate 中, togglesort 可用在 HeaderTemplate 中, 示例:

                    #{id}               #{realname}               #{age}   
      编辑 
      删除   
      
                    #{id}   
         
         
      取消 
      保存   
     

需要说明的是, togglesort 还需要指定一个参数, 表示切换排序的字段, 这个字段已经在 SortField 中设置, 比如: je-οnclick="togglesort,'realname'".

如果绑定多个行为则, 可以使用 ; 号分隔, 比如 je-οnclick="setgroup,'realname';fill".

je-class

使用 je-class="<样式>" 可以为元素绑定特殊的样式. 可以在各个模板中使用 je-class, 常用的样式有: {header} 表示 ui-widget-header, {active} 表示 ui-state-active, {highlight} 表示 ui-state-highlight, {disabled} 表示 ui-state-disabled, {error} 表示 ui-state-error, {default} 表示 ui-state-default, {state} 表示行状态, {sort} 表示排序状态, 示例:

         
                        序号              /* ... */   
      
               /* ... */  
     

这里需要说明 {state} 和 {sort} 的语法, 分别为 {state[,<未改变行样式>[,<新建行样式>[,<修改行样式>[,<删除行样式>]]]]}, {sort,<排序字段>[,<无排序样式>[,<升序样式>[,<降序样式>]]]}. 对于 {state} 而言, 如果没有指定某种状态的样式, 则将使用行的状态名称来代替样式名称, 比如: {state,,new-item}, 由于没有指定未改变行的样式, 因此如果行的状态为 unchanged, 那么将返回 unchanged. 对于 {sort} 而言, 如果没有指定某种排序的样式, 将采用排序的状态来代替样式名称.

je-checked/selected/readonly

在 ItemTemplate 中使用 je-checked="selected" 配合 je-οnclick="toggleselect"来表示行是否处于选中的状态, je-selected 则可用于 EditItemTemplate 中的 select 元素, 示例:

        
       #{id}   
     

在 FilterTemplate 中可以使用 je-selected="<布尔值, 可以是绑定字段或者一个表达式>" 来初始化处于选中状态的 option, 示例:

        
       正常 高 低    
     

je-value

在 FilterTemplate 中使用 je-value="<搜索字段名>" 来绑定初始化的搜索条件.

je-<jQueryUI 插件名>

可以在任何模板中使用 je-<jQueryUI 插件名>="<属性名n>=<属性值n>;", 来生成一个 jQueryUI 的插件, 但目前仅支持 je-button 和 je-datepicker, 示例:

        
       #{id}   
         
         
         
        
          
     

属性的设置是和 jQueryUI 插件的属性一致的, 可以参考 .

je-template

使用 je-template="<模板名>" 可以标记将作为模板的元素, 除了可以通过上面所讲的各种 Template, 也可以使用这种方法来设置模板, 示例:

子视图

在 Repeater 中, 可以通过 shiftview, collapseview, expandview 三个函数来切换, 关闭, 打开子视图, 比如:

1 
     
        3  4 
       5  6 
     
        7         
      
         8             
       
          9             切换子视图 10             
       
 11             
       
         12             
       
 13         
       14 
      15 16 
     
       18     
      
        19         
       
         20             
        #{url} 21             
        
 22             
        
 23             #{picture} 24         
       
 25     
       26 
      27 28 
     
       29     
      
        30         
       
         31             
        
          34             
        
 35             
        
          36             
        
 37         
        38     
       39 
     

更多使用方法和说明请参考 .

数据分组

可以通过 Repeater 的 GroupField 或者 setgroup 函数来设置分组的字段, 通过 GroupTemplate 来设置分组的模板, 在设置分组后调用 fill 函数重新获取数据即可:

1 
     
        5     
      
         6  7           9             发送人 10          11 12     
       13     
      
        14 15          16             @{groupfield}: @{groupname} 17          18     19     
       20     
      
        21 22          23             #{sender} #{displaydate} 24          25 26     
       27 
     

更多使用方法和说明请参考 .

处理控件

除了上面所说的绑定 jQueryUI 插件, 对于一些 html 元素, 也有很多的处理方式:

 计算机 工商管理 汉语   

更多使用方法和说明请参考 .

消息提示

如果需要为用户显示 repeater 当前的操作或者结果, 则可以使用 showtip 函数或者设置 FieldMask 属性, 详细内容请参考 , 这里不再说明.

检索数据

在多数情况下, 都会使用到数据检索的功能, 通过 Repeater 的 FilterTemplate 和 FilterField 等属性即可实现数据检索, 详细内容请参考 .

排序

使用 togglesort 函数就可以完成对字段的排序, 再配合 je-class 在不同排序状态下显示不同样式, 详细内容请参考 .

事件

在 Repeater 所有的事件中都有具有 pe 和 e 两个参数, pe.option 中包含了 repeater 中的选项, pe.jquery 表示当前 repeater, e 则包含了事件的相关数据.

PreUpdate, Updated 更新前后的事件, PreRemove, Removed 删除前后的事件, PreInsert, Inserted 新建前后的事件. e.row 表示当前参与相关操作的行, e.index 表示行的索引, 而 Updated, Removed, Inserted 中 e.issuccess, 表示是否执行成功, 示例:

PreFill, Filled 填充前后的事件, PreExecute, Executed 执行任何操作前后的事件, PreCustom, Customed 执行自定义操作前后的事件, 参数 e 包含 command 属性表示自定义操作的名称, PreSubStep, SubStepped 执行分布操作前后的事件, 参数 e 包含 count 属性表示总的条数, completed 属性表示已经处理完成的行数.

Navigable 当导航可用性变化时, 参数 e 包含 prev 属性表示是否有上一页, next 属性表示是否有下一页. Blocked 当有操作被阻塞时的事件.

客户端方法

此项由于篇幅原因无法全部列出, 如有需要请参考: .

JQueryElement 是开源共享的代码, 可以在 页面下载 dll 或者是源代码.

实际过程演示: , 建议全屏观看.

修订历史

2011-11-17: 增加相关内容和一个对 Repeater 验证功能介绍的链接.

2011-11-19: 增加 Repeater 消息提示介绍的链接.

2011-11-22: 增加 Repeater 检索功能介绍的链接.

2011-11-25: 增加 Repeater 排序功能介绍的链接.

2011-11-26: 修改关于引用 jQueryUI 的介绍.