第 10 章 宏组件

目录

使用宏组件的三个步骤
第一步. 实现
第二步 . 实现
第三步. 使用
内联宏
一个例子
常规宏
宏组件和ID空间
增设方法

有两种方式实现一个组件。一种方法是实现一个来自org.zkoss.zk.ui.AbstractComponent的类。另一种方法是使用其它组件实现它。

第一种方式更为灵活。这需要深入ZK,所以通常由组件开发人员来完成。这在Component Development Guide 中有讨论。

另外,使用其它组件来实现一个新组件更为直接。就像composition,macro expansion,或 inline replacement 一样工作。为了描述方便,我们将这类组件成为宏组件(macro components),而其它的组件称为本地组件(native components)。

[提示]:从应用程序开发人员的角度来看,宏组件与本地组件是没有区别的,除了宏组件是被实现的。

使用宏组件的三个步骤

使用宏组件需要以下三步。

  1. 通过ZUML页面实现一个宏组件。

  2. 在将要使用它的页面内声明宏组件。

  3. 使用宏组件,就像使用其它组件一样。

[提示]: 除了在页面内定义宏组件,你可以将其定义放入一个语言插件(language addon) ,这样所有的页面都可以访问此宏组件。

第一步. 实现

所有你要做的就是准备一个ZUML页面来描述宏组件的组成。也就是,宏模板。

例如,假定你想将一个label 和一个textbox包装成成一个宏组件。我们可以创建页面,例如/WEB-INF/macros/username.zul,如下。

<hbox>
   Username: <textbox/>
</hbox>

完成!

实现宏组件的页面和其它页面是一样的,所以任何页面都可以做为宏组件被使用。

第二步 . 实现

在实例化一个宏组件之前,你必须首先声明。一个简单的方式就是使用指令声明它。

<?component name="username" macroURI="/WEB-INF/macros/username.zul"?>

如上所示,你必须声明name(name属性)和页面的URI(macroURI 属性)。

其它属性

除了namemacroURIclass [56]属性,你可以指定一个初始属性的列表,用于实例化时初始一个组件。

<?component name="mycomp" macroURI="/macros/mycomp.zul"
myprop="myval" another="anotherval"?>

因此,

<mycomp/>

等价于

<mycomp myprop="myval1" another="anotherval"/>

第三步. 使用

使用宏组件与使用其它组件一样。

<window>
   <username/>
</window>

传递属性

就像一个普通的组件,当使用宏组件时你可以指定属性(properties)(亦=attributes) ,如下。

<?component name="username" macro-uri="/WEB-INF/macros/username.zul"?>
<window>
   <username who="John"/>
</window>

所有这些被指定的属性被存储在一个map中,然后通过arg变量被传递到模板(template)。然后在模板中,你可以按如下方式访问这些属性。

<hbox>
   Username: <textbox value="${arg.who}"/>
</hbox>

[注]:仅当送出(rendering)宏页面时arg是可用的。为了访问事件监听器,你必须使用getDynamicProperty代替。细节请参考增设方法一节。

arg.includer

除了指定的属性(properties)(亦=attributes),arg.includer属性也被传出用以呈现定义在宏模板中组件的父组件。

若一个常规的宏被创建,arg.includer即为宏组件本身。若创建了一个内联(inline)宏,arg.includer为父组件,若果有的话。更多信息请参考内联宏一节。

在上面的例子中,arg.includer表示常规的宏组件,<username who="John"/>,且为的父组件(定义在username.zul中)。



[56] 后面会讨论class 属性。