zk组件开发指南(2)

2. 句柄Handle
     句柄是运行在服务器端可以被应用程序访问的java对象。从应用的角度看，它是组件的全部。因此，在应用开发过程中，我们通常叫它组件，而不是区分展现层和句柄的概念。
     句柄必须实现两个接口：org.zkoss.zk.ui.Component 和org.zkoss.zk.ui.sys.ComonentCtrl.
Component 是应用程序可访问的APIs的集合，而ComponentCtrl 是只有zk和开发组件才能访问的API的集合。同样，你不需要重头实现它们，你可以选择其中的一个主要实现或存在的组件满足你的需要，然后扩展它们。下面一节将描述主要实现方法中的每一个。
2.1 主要的实现（Skeletal Implementations）
     Zk提供了几个主要实现来最小程度缩减开发组件的效率。
2.1.1 org.zkoss.zk.ui.AbstractComponent 类
      AbstractComponent是最基本的主要实现类。如果你实现的组件只是为没有HTML片段的客户端（象移动设备）实现的，你可以继承这个接口。
      AbstractComponent接口实现了redraw方法，它支持molds、 annotations、ID
Space、page association、parent-children relationship、 event listener registration,
Serialization、 clone、 和 所有组件的 APIs.
      使用AbstractComponent组件很直接：只需实现你自己的方法，根本没有抽象方法去实现。例如

public class MyComp extends org.zkoss.zk.ui.AbstractComponent { 
private Object _value; 
public Object getValue() { 
return _value; 
} 
public void setValue(Object value) { 
_value = value; 
} 
} 

 
     除了Component和ComponentCtrl接口，AbstractComponent还提供了一系列的应用方法集合来最大缩减实现的工作量。
与客户端交互的方法集（Utilities to Communicate with the Client）
       AbstractComponent提供了三种与客户端交互的方法：invalidates, smart updates 和 AU responses.
Invalidates方法通知zk引擎该组件需要完全重画； Smart updates 通知 ZK 引擎该组件的一个属性已经改变了。 AU responses 允许一个句柄访问展现层去做它想做的任何事情，象改变焦点, 启动定时器, 执行一段javascript代码等等。 
   

public class MyComp extends org.zkoss.zk.ui.AbstractComponent { 
private String _label = ""; 
public String getLabel() { 
return _label; 
} 
public void setLabel(String label) { 
if (!label.equals(_label)) { 
_label = label; 
smartUpdate("label", _label); 
} 
} 
public void updateContent(Object value) { 
//whatever... 
invalidate(); 
} 
} 

 

     展现层和句柄的交互是最重要的话题之一，我们在后面会详细讨论。
生成展现层的方法（Utilities to Generate the View）

 

额外控制（Extra Controls）
      为了封装那些只为开发组件才用到的API，我们介绍一个叫extra controls (aka., extra interfaces)的概念。如果一个组件想提供一些只为组件开发才能用到的额外接口，它可以重写newExtraCtrl 方法去实例化一个带额外接口的实例。例如，Slider 组件允许客户端改变它的位置，那么它就必须实现org.zkoss.zk.ui.ext.client.Scrollable接口。正如下面描述的一样，Slider 首先执行ExtraCtrl 类去实现Scrollable 接口，然后Slider 重写newExtraCtrl 去实例化一个ExtraCtrl 实例。

public class Slider extends org.zkoss.zk.ui.HtmlBasedComponent { 
private int _curpos; 
protected Object newExtraCtrl() { 
return new ExtraCtrl(); 
} 
protected class ExtraCtrl extends HtmlBasedComponent.ExtraCtrl implements Scrollable { 
public final void setCurposByClient(int curpos) { 
_curpos = curpos; 
} 
} 
} 

 
      注意你一般扩展基本类的extra controls，因此它继承了所有的extra controls，在上面的例子中，它是从HtmlBasedComponent.ExtraCtrl类扩展的。
2.1.2 org.zkoss.zk.ui.HtmlBasedComponent 类
      你如果实现一个基于HTML浏览器的组件，你可能考虑从HtmlBasedComponent扩展，HtmlBasedComponent继承了AbstractComponent类并提供更多的HTML特性，例如CSS style, CSS class, width, height, drag-and-drop, tooltip text等等。通过从HtmlBasedComponent扩展，你的组件无偿继承了HTML的特性——无需进行特殊的初始化，实现或调用。除此之外，它还提供了一些生成展现层的方法。
生成页面的方法Utilities to Generate the View

名字	描述
getInnerAttrs getOuterAttrs	HtmlBasedComponent认为展现层可能有嵌套标签----即外部和内部标签，getInnerAttrs 和getOuterAttrs用来生成相应的内部和外部标签。如果一个组件没有用嵌套标签实现，它只需将两个方法的返回值象下面一样连接起来。关于详细的信息请参考下章的展现层。 <span id="${self.uuid}"${self.outAttrs}${self.innerAttrs}> </span>
getRealSclass getRealStyle	当getOuterAttrs（）方法被调用，它会调用这样两个方法去生成类和样式属性。默认情况下，它们各自代表对getSclass（）和getStyle（）的调用。如果你需要添加CSS样式（除了用户指定的通过setStyle添加的），你可以重写getRealStyle方法。例如， protected String getRealStyle() { return super.getRealStyle() + "padding:5px;"; }
getAllOnClickAttrs	该方法用来生成onClick, onDoubleClick 和onRightClick事件的属性。如果组件支持这些事件，它应在getOuterAttrs（）方法中回调这个方法。 然后, 如果应用程序为他们注册了一个监听器，事件就会自动从客户端发送回服务器（无延迟，不需要js代码）。 public String getOuterAttrs() { String attrs = super.getOuterAttrs(); String clkattrs = getAllOnClickAttrs(); rerturn clkattrs != null ? attrs + clkattrs: attrs; }

2.1.3 org.zkoss.zul.impl.XulElement 类
      XulElement是XUL组件的主要实现。如果你想实现一个组件，该组件将添加到xul/html语言中，继承这个类是一个好的起点。XulElement是从HtmlBasedComonent扩展来的。它提供了xul特性，例如popup,
context menu, tooltip 和 client-side-action.
生成页面的方法Utilities to Generate the View
无
2.2 与客户端的交互Communication with the Client
      展现层和句柄间的交互是组件的工作，而交互对应用程序开发者是透明的。交互是一种“投—捕捉”的方式。它通常涉及展现层和句柄。在这节中，我们的重点将放在服务器端的句柄上。客户端的展现层将在下一章阐述。
2.2.1客户端的回复Response to the Client
      存在三种方式向客户端的展现层发送回复：invalidates, smart updates 和responses。invalidate （）函数导致组件整个展现层重画。smart update（）导致组件展现层的一个特殊属性改变。AU response 是 一个用于操作组件展现层的完全自定义的response
Invalidates方法
     public void invalidate();
     当invalidate（）方法被调用，组件被标识为废弃，然后在渲染解析中redraw（）方法被调用去产生整个客户端的展现层。
     invalidate()函数典型的应用是当一个改变展现层的方法调用时。

public void setLabel(String label) { 
if (!Objects.equals(_label, label)) { 
_label = label; 
invalidate(); 
} 
} 

 
      这是最简单的更新展现层的方式，因为我们不需要写任何的JavaScript代码。通过zk引擎展现层被redrawn（）方式自动更新。如果一个组件包含好多的子组件（例如grid组件）。重画整个展现页面消耗是很大的，因为它要重画所有的子组件。因此，如果改变很小，你采用smart updates 或 AU responses更新执行效率回更好些。
注意：zk引擎会在调用redraw（）方法前优化invalidate。例如，一个组件在大多数的情况下会一次性重化，尽管它本是或其父组件有多次的invalidated。
Smart Updates方法

public void smartUpdate(String attrName, String value); 
public void smartUpdate(String attrName, DeferredValue value); 
public void smartUpdate(String attrName, boolean value); 
public void smartUpdate(String attrName, int value); 

 
     smart update（）方法用于修改展现层的某个属性，不象invalidate（）方法一样，它不会导致整个组件重化。

public void setReadonly(boolean readonly) { 
if (_readonly != readonly) { 
_readonly = readonly; 
smartUpdate("readOnly", _readonly); 
} 
} 

  
      在默认的情况下，zk客户端引擎会采用指定的名字更新展现层大多数外部DOM元素的属性。例如，假设上面例子的大多数的外部DOM元素是 elem。它的作用等同于在客户端调用如下的代码：

elem.readOnly = _readonly; 

 
     Zk客户端引擎比较智能它能调用正确的方法更新。例如。elem.className代表类的属性，elem.setAttribute()代表未识别的属性等等。

      另外，如果你想在组件指定的方式中处理smart updates（），你可以在客户端提供自己的javascript代码去处理smart updates的内容。

  注意: 如果对于同一组件， smart updates 和invalidates都被调用, smart updates 会被忽略--- 毕竟整个展现层被重画. 

    AU Responses方法

public void response(String key, AuResponse response); 

      AU Response 是最低级别的回应。你可以自定义它做任何你想做的事情。但是，你很少需要直接用AU responses，因为invalidates() 和smart updates()可以做几乎你想做的所有事情。记住可以在客户端自定义自己的javaScript代码去处理smart updates()。换句话说，你可以在客户端应用 smart updates()去做一些处理，不仅仅是修改属性。和smart updates()不同，针对同一个组件，AU responses总是被发送到客户端，即使是invalidate被调用。这就是我们为某种情况应用AU responses 的原因之一。例如，假设我们要实现焦点特性，因为我们想改变组件的焦点，即使在被无效的情况下，这是AU response是唯一的选择。

public void focus() { 
response("focus", new AuFocus(this)); 
} 

     这里的AuFocus是一个AU responses类在扩展AuResponse时提前定义的功能性的内置函数。
Depends
      我们说一个AU response取决去一个组件。一旦组件被移除，它就不能被发送到客户端。它是由构造函数的依赖参数控制的。在大多数情况下，AU response取决于组件。
       注意：和smart updates不同，AU response即使在该组件被invalidated时也可以被发送到客户端，除非该组件被移除。
内置AU Responses（Built-in AU Responses）
      有好多的内置AU responses，象AuAlert, AuInvoke, AuPrint等等，它们都在org.zkoss.zk.au.out包中。当你想开发自己的AU respons，请首先参考下Javadoc文档是否它们中已经存在满足你需求的AU response。
      AuInvoke和 AuScript 是 AU response中用来在客户端调用JavaScript代码的内置AU Responses. AuInoke 调用 JavaScript 方法取决于组件的类型，而AuScript 调用的是代码的片断，不管它是不是组件展现层的一部分。i

public void play() { 
response("play", new AuScript(this, "alert('Hi')")); 
} 

       在后面的章节中我们将涛刘如何开发自己的AU response，因为它需要一些JavaScript代码。
发送到客户端的请求（Request to the Server）
        在客户端为了通报发生的事情，展现层会发送一个AU request（org.zkoss.zk.au.AuRequest）到服务器。
AU request是由所谓的命令来处理的。是否跟新组件或接收一个事件都取决于该命令是如何实现的。
命令（Command）
        command (org.zkoss.zk.au.Command) 用来处理某种类型的 AU requests。当zk更新引擎接收到一个AU request,它会将其与command相关联。然后，调用command中的方法去处理它。根据需要，处理通常会更新组件的内容，然后传递一个事件来通知应用程序。例如，org.zkoss.zk.au.in.RemoveCommand命令注册用来处理所有叫remove的AU request。因此，如果一个叫remove的AU request被接收，RemoveCommand的process方法将被调用。这里是RemoveCommand代码的实现：

public class RemoveCommand extends Command { 
public RemoveCommand(String evtnm, int flags) { 
super(evtnm, flags); 
} 
protected void process(AuRequest request) { 
final Component comp = request.getComponent(); 
if (comp != null) comp.detach(); 
} 
} 

      注意：对于相同类型的AU request，zk应用相同的command实例，因此存在同时访问同一command的情况
事件（Event）
      当一个命令处理一个请求时，它可能传递一个或多个事件。例如，InputCommand将onChange事件做为org.zkoss.zk.ui.event.InputEvent的一个实例进行传递。事件会进行排队知道所有的命令被处理完。换句话说，事件是在组件被更新后由应用程序处理的。
       组件开发中存在一个共性问题：我是否在一个命令或事件监听器中更新组件的状态。一般来说，只采用事件通知应用程序，在命令中更新组件的状态是比较好的。毕竟，应用程序可能会随时中止事件的传递进程(Event.stopPropagation)。另一方面，我们可以利用stop-propagation特性允许应用程序自定义自己的某些行为。例如，listbox组件在 onSort 监听器中排序list中的各项，因此应用程序可以通过添加自己的监听器提供自己的排序功能，停止事件的传递
各式各样诸多的特性（Miscellaneous Features）
       Drag-and-Drop, Tooltip 和Context Menu 它们可以被自定义的JavaScript代码自动支持，只要你从org.zkoss.zul.impl.XulElement类中扩展你自己的组件句柄。
Click, Right Click and Double Click onClick, onRightClick 和onDoubleClick 事件是由zk引擎自动处理的。你所做的只是通过appendAsapAttr 方法产生正确的属性。

public String getOuterAttrs() { 
final StringBuffer sb = new StringBuffer(super.getOuterAttrs()); 
appendAsapAttr(sb, Events.ON_CLICK); 
appendAsapAttr(sb, Events.ON_DOUBLE_CLICK); 
appendAsapAttr(sb, Events.ON_RIGHT_CLICK); 
return sb.otString(); 
} 

 
      HtmlBasedCcomponent 提供一个叫getAllOnClickAttrs的方法来简化共做。

public String getOuterAttrs() { 
String attrs = super.getOuterAttrs(); 
String clkattrs = getAllOnClickAttrs(); 
rerturn clkattrs != null ? attrs + clkattrs: attrs; 
} 

 

 

 

方法	描述
isAsapRequired	判断指定的事件是否有非延迟的监听器注册。
appendAsapAttr	如果非延迟事件注册则销毁，如果为true就将添加一个特殊属性通知它。