自定义组件中的元数据标签

下表是可以用在ActionScript类中的元数据标签：

标签	描述
[ArrayElementType]	指定数组中每个元素的数据类型。
[Bindable]	把一个属性标记为可以用作数据绑定表达式的源。
[DefaultProperty]	当把组件用在MXML文件中时，定义这个组件的默认属性的名字。
[Deprecated]	把一个类或类元素标记为不赞成使用的。这样当应用程序中使用了它时，编译器能识别出来，并给出一个警告。
[Effect]	定义效果的MXML属性名称。
[Embed]	在编译时导入JPEG、GIF、PNG、SVG及SWF文件。也能从SWC中导入图片。它跟MXML语法@Embed的作用一样。
[Event]	为一个事件定义MXML属性，并定义这个组件发出的事件对象的数据类型。
[Exclude]	在Flex Builder标签检查器中忽略掉类的元素。用法如：[Exclude(name="label",kind="property")]
[ExcludeClass]	在Flex Builder 标签检查器中忽略掉这个类。它等同于在ASDoc中的@private
[IconFile]	指定用在Flex Builder插入面板中的表示组件的图标文件的名称。
[Inspectable]	定义在Flex Builder 属性提示和标签检查器中显示给组件使用者的属性。
[InstanceType]	指定IDeferredInstance类型的属性的数据类型。
[NonCommittingChangeEvent]	把一个事件指定为临时触发器。
[RemoteClass]	把ActionScript对象映射为一个Java对象。
[Style]	定义组件的MXML样式属性。
[Transient]	指定当用[RemoteClass]把ActionScript对象映射到Java对象，把这个对象传输到服务器上时应该忽略掉的属性数据。

 

ArrayElementType 元数据标签

当你使用ActionScript定义一个Array变量时，你把这个变量的数据类型指定为Array，但是你却不能指定Array中每个元素的数据类型。要想让Flex编译器检查数组的元素的数据类型，你可以像下面这样，使用[ArrayElementType]指定数组元素允许的数据类型：

ACTIONSCRIPT3  show/hide

1 2 3 4 5 6 7 8 9

public class MyTypedArrayComponent extends VBox {   [ArrayElementType("String")] public var newStringProperty:Array;   [ArrayElementType("Number")] public var newNumberProperty:Array; ... }

注意：MXML编译器只检查MXML代码中Array的正确性；它不检查ActionScript代码中的用法是否正确。

在这个例子中，数组元素允许的数据类型为String。如果尝试把非String类型的元素添加到这个数组中，编译器会报语法错误：
<MyComp:MyTypedArrayComponent>
    <MyComp:newStringProperty>
        <mx:Number>94062</mx:Number>
        <mx:Number>14850</mx:Number>
        <mx:Number>53402</mx:Number>
    </MyComp:newStringProperty>
</MyComp:MyTypedArrayComponent>
在这个例子中，你尝试用Number对象初始化这个数组，因此编译器会给出错误提示。
也可以使用标签属性指定Array属性，而不是使用子标签，如下：

<MyComp:MyTypedArrayComponent newNumberProperty=”[abc,def]“/>
这段MXML代码会报错，因为Flex无法把字符串”abc”和”def”转换成数字。

[ArrayElementType]元数据标签应该插入到变量定义之前，该标签用法如下：

ACTIONSCRIPT3  show/hide

1	[ArrayElementType("elementType")]

下面的表格描述了[ArrayElementType]元数据标签的属性：

属性 类型 描述

elementType	String	指定数组元素的数据类型，可以是任何一种ActionScript数据类型，比如String,Number,class或interface.你必须使用完整限定类名指定这个类型，包括包名。

Bindable元数据类型

如果一个属性是数据绑定表达式的源，当源数据改变时，Flex自动把数据拷贝给所有目标属性。要想让Flex执行这个拷贝动作，你必须使用[Bindable]元数据标签，向Flex注册属性，并且源属性必须广播一个事件。

[Bindable]元数据标签用法如下：

ACTIONSCRIPT3  show/hide

1 2	[Bindable] [Bindable(event="eventname")]

如果你省略了事件名称，Flex自动创建一个名为PropertyChange的事件。

更多关于数据绑定和该元数据标签的信息，参见绑定数据。

使用可绑定的属性链

当你把一个属性指定为数据绑定源时，Flex不但监听这个发生改变的属性，而且监听关联它的整个链。这整个属性链，包括目标属性，称为可绑定的属性链。在下面的例子中，firstName.text是一个包含firstName对象和它的text属性的绑定的属性链：

<first>{firstName.text}</first>

当链中任何属性发生改变时，你都应该生成一个事件。如果这个属性使用[Bindable]元数据标签标记了，那么Flex为为你生成这个事件。

下面的例子把[Bindable]用在变量和getter属性上。这个例子同样展示了如何调用dispatchEvent()函数：

ACTIONSCRIPT3  show/hide

1 2 3 4 5 6 7 8 9 10 11

[Bindable] public var minFontSize:Number = 5;   [Bindable("textChanged")] public function get text():String { return myText; }   public function set text(t : String):void { myText = t; dispatchEvent( new Event( "textChanged" ) );}

如果你省略了[Bindable]中事件的名称，Flex编译器会自动生成并广播名为propertyChange的事件，以便这个属性可以用作数据绑定表达式的源。

你应该把对象的确切信息提供给编译器，也就是说应该把对象转换成已知的类型。在下面的例子中，myList列表控件，包含Customer对象，因此selectedItem属性转换成Customer对象：

<mx:Model id=”selectedCustomer”>
    <customer>
        <name>{Customer(myList.selectedItem).name}</name>
        <address>{Customer(myList.selectedItem).address}</address>
        …
    </customer>
</mx:Model>

在某些情形下，绑定不会如预想的那样自动运行。比如，当你改变一个dataProvider属性的一个元素时：

dataProvider[i] = newItem

当源数据的子属性发生改变时，绑定也不会自动执行，如下：

ACTIONSCRIPT3  show/hide

1 2 3 4 5 6 7 8

... [Bindable] var temp; // 会触发绑定 temp = new Object(); // 不会触发绑定，因为label不是一个可绑定的属性 temp.label = foo; ...

在这个例子中,{temp.label}的问题出在temp是一个Object。可以用下面中的一种解决这个问题：

* 预先初始化这个对象

* 把一个ObjectProxy赋值给temp；ObjectProxy的所有属性都是可绑定的

* 把temp制作成包含可绑定属性label的强类型对象

当绑定到FlashPlayer自动刷新的属性上（比如mouseX）时，绑定也不会起作用。

UIComponent的executeBindings()方法执行所有的目标为该UIComponent对象的绑定。所有的容器、控件，包括Repeater组件，都扩展自UIComponent。Container和Repeater类的executeChildBindings()执行容器和Repeater的子UIComponent是绑定目标的绑定。所有的容器都扩展自Container类。

这些方法给你提供了一种当绑定没有如预想的执行时，你可以的选择。通过添加一行代码，比如调用executeChildBindings()方法，你可以在做了更改而没有执行绑定时更新用户界面。但是，如果你明确知道绑定不会自动执行时，就不应该调用executeBindings()。

DefaultProperty元数据标签

当你在MXML文件中使用组件时，[DefaultProperty]元数据标签指定该组件的默认属性。

[DefaultProperty]标签的用法如下：

ACTIONSCRIPT3  show/hide

1	[DefaultProperty("propertyName")]

propertyName指定默认的属性名称。

你可以使用[DefaultProperty]标签在你的ActionScript组件中定义一个唯一的默认属性。更多信息及示例，参见创建一个默认属性。

Deprecated元数据标签

标记为deprecated的类或类元素就意味着过时的，在当前版本中不赞成使用的。如果坚持使用它，编译器会给出警告。

mxmlc命令行编译器有一个show-deprecated-warning编译选项，如果设成true，那么当你的应用程序使用了不赞成使用的类或类元素时，编译器会生成警告。默认值是true。

[Deprecated]标签插入到属性、方法或类定义前面，以便把这些元素标记为不赞成使用的。[Deprecated]标签有如下用法：

[Deprecated("string_describing_deprecation")]
[Deprecated(message="string_describing_deprecation")]
[Deprecated(replacement="string_specifying_replacement")]
[Deprecated(replacement="string_specifying_replacement", since="version_of_replacement")]

下面的代码使用[Deprecated]标签把dataProvider属性标记为过时的：

ACTIONSCRIPT3  show/hide

1 2 3 4 5

[Deprecated(replacement="MenuBarItem.data")] public function set dataProvider(value:Object):void { ... }

[Event]，[Effect]和[Style]标签中也有不支持使用选项：

ACTIONSCRIPT3  show/hide

1 2 3

[Event(... , deprecatedMessage="string_describing_deprecation")] [Event(... , deprecatedReplacement="change2")] [Event(... , deprecatedReplacement="string_specifying_replacement", deprecatedSince="version_of_replacement")]

这些标签支持DeprecatedReplacement和DeprecatedSince属性来把事件、效果、样式标记为不赞成使用的。

Effect元数据标签

[Effect]元数据标签定义你想要赋值给组件的效果名字，和触发效果的事件。如果你定义了一个自定义效果，你可以使用[Effect]标签把它指定给Flex编译器。

一个特效包含触发它的触发器。触发器就是一个事件，比如组件的鼠标点击事件，一个组件获得了焦点，或一个组件变得可见了。一个特效就是发生在组件上的可见的或可听到的会持续一段时间的变化。

把[Effect]标签插入到ActionScript文件的类定义之前或MXML文件中的<mx:Metadata>块内。[Effect]标签的用法如下：

ACTIONSCRIPT3  show/hide

1	[Effect(name="eventNameEffect", event="eventName")]

下表描述了[Effect]标签的属性：

属性 类型 描述

eventNameEffect	String	指定特效名称。
eventName	String	指定触发特效的事件名称。

[Effect]标签经常同[Event]标签成对出现，[Event]标签定义对应[Effect]触发器的事件。习惯上，特效的名称就是事件名，加上后缀Effect。如下面ActionScript文件中的例子：

ACTIONSCRIPT3  show/hide

1 2 3 4 5 6 7

// Define event corresponding to the effect trigger. [Event(name="darken", type="flash.events.Event")] // Define the effect. [Effect(name="darkenEffect", event="darken")] class ModalText extends TextArea { ... }

在MXML文件中，你可以像下面这样在<mx:Metadata>块内定义[Effect]和[Event]:

<mx:Metadata>
    [Event(name="darken", type="flash.events.Event")]
    [Effect(name="darkenEffect", event="darken")]
</mx:Metadata>

Event元数据标签

使用[Event]标签定义MXML中的事件属性及组件生成的事件对象的类型。[Event]标签插入到ActionScript文件的类定义前，或者MXML文件的<mx:Metadata>块内。

[Event]元数据标签用法如下：

ACTIONSCRIPT3  show/hide

1	[Event(name="eventName", type="package.eventType")]

下面的表格描述了[Event]标签的属性：

属性 类型 描述

eventName	String	指定事件名称，包括包名。
eventType	String	指定定义事件对象的数据类型的类。类名可以是事件基类，Events或者Events的子类。必须包含包名。

下面的例子指定组件可广播的事件为myClickEvent：

ACTIONSCRIPT3  show/hide

1	[Event(name="myClickEvent", type="flash.events.Event")]

如果没在类文件中使用[Event]标签指定事件，而却在MXML文件中使用事件时编译器会报错。任何组件都可以在ActionScript中使用addEventListener()方法注册事件监听，即使没有[Event]标签。

下面的例子指定myClickEvent为ActionScript组件可以广播的事件：

ACTIONSCRIPT3  show/hide

1 2 3 4 5

[Event(name="myEnableEvent", type="flash.events.Event")] public class MyComponent extends UIComponent { ... }

下面的例子展示了在MXML文件中在<mx:Metadata>标签内使用[Event]标签：

<?xml version=”1.0″?>
<!– TextAreaEnabled.mxml –>
<mx:TextArea xmlns:mx=”http://www.adobe.com/2006/mxml”>

    <mx:Metadata>
        [Event(name="myEnableEvent", type="flash.events.Event")]
    </mx:Metadata>

    ….

</mx:TextArea>

IconFile元数据标签

使用[IconFile]指定Flex Builder插入面板中组件显示外观的文件名。

[IconFile]的用法如下：

ACTIONSCRIPT3  show/hide

1	[IconFile("fileName")]

fileName属性指定包含图标的PNG，GIF或JPEG文件，如下面例子：

ACTIONSCRIPT3  show/hide

1 2 3 4 5

[IconFile("MyButton.png")] public class MyButton extends Button { ... }

Inspectable元数据标签

[Inspectable]元数据标签定义在Flex Builder 属性提示和标签检查器中显示给组件使用者的属性。[Inspectable]标签对代码提示和属性检查器而言并非必须的。下面的规则决定了Flex Builder如何显示信息：

* 组件的所有公共属性都显示在代码提示和属性检查器中。如果你想为属性添加额外的信息，比如枚举值或者说明一个字符串表示文件路径，则可使用[Inspectable]标签添加这些信息。

* 组件的代码提示和属性检查器中的信息源自相同的数据。因此，如果信息在一个地方出现了，则另一个地方也肯定会出现。

* 对于ActionScript组件，并不需要元数据才能正常工作，因此根据当前范围的不同，你总是能看到正确的代码提示。Flex Builder使用public,protected,private 和static关键字，加上当前范围，决定显示哪些ActionScript代码提示。

[Inspectable]标签必须紧贴在变量声明或者setter和getter方法之前。[Inspectable]元数据标签用法如下：

ACTIONSCRIPT3  show/hide

1 2 3 4

[Inspectable(attribute=value[,attribute=value,...])] property_declaration name:type; [Inspectable(attribute=value[,attribute=value,...])] setter_getter_declarations;

下表描述了[Inspectable]元数据标签的属性：

属性 类型 描述

category	String	把属性归类到Flex Builder用户界面中的属性检查器的子分类中。默认的分类是”Other”。可能的值有“Common”, “Effects”, “Events”, “Layout Constraints”, “Size”, “Styles”, 或 “Other”。
defaultValue	String 或 Number	设置显示在属性检查器中的属性的初始值。默认值由属性定义决定。
enumeration	String	用以逗号分隔的列表指定该属性的合法值。只有这些值是允许使用的；比如，item1,item2,item3。注意各项之间并没有空格。这些信息会出现在代码提示和属性检查器中。如果你定义了Boolean变量，即便没有指定枚举值，Flex BuilderT也会自动显示true和false的提示。
environment	String	指定哪些属性不应该显示(enviroment=none)，哪些只能用于Flex Builder(enviroment=Flash)，哪些只能用于Flex而非Flex Builder(enviroment=MXML)。
format	String	决定属性检查器中你编辑的这个属性的值的数据类型。当属性的数据类型没有显示出它的功能时，你可以使用这个来展示。比如，对于一个Number类型的属性，你可以指定format=”Color”以便在你编辑该属性时，Flex Builder打开一个颜色编辑器。format属性的常用值包括 “Length”, “Color”, “Time”, “EmbeddedFile”, 和“File”。
listOffset	Number	指定List值的索引。
name	String	指定属性的显示名称；比如，Font Width。如果没有指定，则使用属性名，比如_fontWidth。
type	String	指定数据类型。如果省略掉，则使用属性的类型。下面是有效的值:   Array Boolean Color Font Name List Number Object String 如果是Array，你必须列出该数组的有效值。
variable	String	指定参数的约束。
verbose	Number	指定只有用户指定了verbose属性要显示才显示在Flex Builder界面上。如果没指定这个属性，Flex Builder假定属性应该显示出来。

下面的例子定义myProp参数为Inspectable：

ACTIONSCRIPT3  show/hide

1 2	[Inspectable(defaultValue=true, verbose=1, category="Other")] public var myProp:Boolean;

InstanceType元数据标签

[InstanceType]标签指定IDeferredInstance类型的属性的数据类型，如下例子所示：

ACTIONSCRIPT3  show/hide

1 2 3

// Define a deferred property for the top component. [InstanceType("mx.controls.Label")] public var topRow:IDeferredInstance;

Flex编译器会检查只有指定数据类型的值能赋给这个属性。在这个例子中，如果组件使用者把mx.controls.Label之外类型的值赋给了topRow，编译器会生成一条错误消息。

当创建模版组件时应该使用[InstanceType]元数据标签，更多信息，请阅读模版组件。

[InstanceType]元数据标签用法如下：

ACTIONSCRIPT3  show/hide

1	[InstanceType("package.className")]

你必须指定完全限定的包和类名。

NonCommittingChangeEvent元数据标签

[NonCommittingChangeEvent]元数据标签把一个事件指定为临时触发器，也就是说该事件不应该调用Flex在该属性上的数据验证。你把该标签用在可能经常改变值而又不必每次改变都要验证的属性上。

一个例子是假如你为一个TextInput控件的text属性指定了一个验证，每次按下键，text属性值都会改变，但是在用户按下Enter键之前或焦点离开该控件之前你都不想进行验证，NonCommittingChangeEvent标签允许你广播一个change事件，但它不会触发验证。

[NonCommittingChangeEvent]标签应该插入到ActionScript的属性定义或者setter/getter方法之前。其用法如下：

ACTIONSCRIPT3  show/hide

1	[NonCommittingChangeEvent("event_name")]

在下面的例子中，每次用户按键，组件都会广播一个change事件，但是这个事件并不会触发数据绑定或数据验证。当用户按下了Enter键后，组件广播一个valueCommit事件来触发数据绑定或数据验证：

ACTIONSCRIPT3  show/hide

1 2 3 4 5 6 7 8 9 10 11 12 13 14

[Event(name="change", type="flash.events.Event")] class MyText extends UIComponent { ...   [Bindable(event="valueCommit")] [NonCommittingChangeEvent("change")] function get text():String { return getText(); } function set text(t):void { setText(t); // Dispatch events. } }

RemoteClass元数据标签

使用[RemoteClass]元数据标签向Flex注册这个类，这样当使用Action Message Format(AMF)序列化该类的实例时，Flex就会保留这个类的类型信息。[RemoteClass]标签要插入到类定义之前。其用法如下：

ACTIONSCRIPT3  show/hide

1	[RemoteClass]

在客户端程序中你也可以使用该标签表示一个服务器端Java对象。你使用[RemoteClass(alias="  ")]元数据标签创建一个直接映射到Java对象的ActionScript对象。你要用alias的值

评论

1 楼 hans.org 2012-06-08  

mark it