Flex 3 metadata tags

 

     Flex引入了元数据标签的概念，它告诉编译器如何编译这段Flex 或actionscript代码。大多数人都使用过[Bindable]标签，元数据标签是一种 特殊的标签，它在代码中的作用就是向编译器提供如何编译程序的信息。实际上，这些标签并没有被编译到生成的SWF文件中，而只是 告诉编译器如何生成SWF 文件。 这篇Post结合网上相关的 资料 以及Adobe的 help resource center的相关材料 介绍了16个元数据标签。

[ArrayElementType]

实际上，定义一个数组通常来说是一件很平常的事情，因为数组中的元素可以是任何类型的。不过，使用ArrayElementType元数据标签可以让你定义数组元素的数据类型。下面的例子展示了如何使用[ArrayElementType]：

[ArrayElementType(”String”)]
public var arrayOfStrings:Array;

[ArrayElementType(”Number”)]
public var arrayOfNumbers:Array;

[ArrayElementType(”mx.core.UIComponent”)]
public var arrayOfUIComponents:Array;

[Bindable]

Bindable元数据标签是最经常用到的一个元数据标签，因为它使程序组件之间的数据同步变得很容易。Bindable可以用来绑定简单数据类型、类、复杂数据类型以及函数。绑定数据的时候，你必须先使用元数据标签定义一下数据。Bindable也可以用来绑定到事件。

[DefaultProperty]

DefaultProperty元数据标签用来将一个单一属性设定为某个类的默认属性。它允许在一个容器标签内设定属性，而不用定义属性的名字。一个简单的例子就是一个自定义Button类。 Listing 3 展示了一个简单的Button类，它将label属性设定为了DefaultProperty。 Listing 4 展示了label属性是如何在自定义Button标签中作为一个字符串定义的。

[Deprecated]

A class or class elements marked as deprecated is one which is considered obsolete, and whose use is discouraged in the current release. While the class or class element still works, its use can generate compiler warnings.

[Embed]

Embed元数据标签用来导入图片到程序。可以通过两种方式使用Embed。你可以将图片嵌入到ActionScript中并将其指派给一个变量（如同下面代码中的第一个例子），或者你也可以将图片直接指派给组件的属性（使用下面代码中的第二个例子所示的语法规则）。

例1：

[Embed(source=”myIcon.gif”)]
[Bindable]
public var myIcon:Class;<mx:Button label=”Icon Button 1″ icon=”{myIcon}”/>
<mx:Button label=”Icon Button 2″ icon=”{myIcon}”/>

例2：

<mx:Button label=”Icon Button 1″ icon=”@Embed(source=myIcon.gif’)”/><mx:Button label=”Icon Button 2″ icon=”@Embed(source=myIcon.gif’)”/>

上面这两个例子产生的结果是一样的。创建myIcon类的好处是，它在一个类中只定义一次并可以绑定到程序中的多个组件。

[Event]

Event元数据标签用来声明那些被自定义类分派的事件。将这个元数据标签添加到类定义中之后，你就可以在MXML标签中添加事件处理函数来初始化该自定义类。

[Effect]

Effect元数据标签用来定义一个自定义效果，当某个事件发生的时候该效果会被分派。

[IconFile]

IconFile 是用来定义一个jpg，gif或者png文件的文件名的，它在你的自定义类中作为图标来使用。[Embed]元数据标签可以用来嵌入图片、SWF文件、音 乐文件以及视频文件等，而IconFile则只是用来嵌入用来作为自定义类图标的文件。下面是一个IconFile的例子：

[IconFile(”icon.png”)]
public class CustomButton extends Button
{}

[Inspectable]

在使用Flex Builder 2的时候，你可能会希望某些自定义组件的属性在代码提示和属性检查器（property inspector）中显示，Inspectable元数据标签就是用来定义那些属性的。

[InstanceType]

当在一个模板对象中声明一个像IDeferredInstance这样的变量时，InstanceType元数据标签就用来声明对象的类型。下面是InstanceType的用法：

[InstanceType(”package.className”)]

[NonCommittingChangeEvent]

NonCommittingChangeEvent元数据标签在某个特定事件发生的时候可以防止变量在事件发生的过程中被更改。

[RemoteClass]

RemoteClass 可以用来将一个ActionScript类绑定到一个Java类或一个ColdFusion CFC。这样做可以自动转换数据类型。下面的例子将包com.mydomain中的名为MyClass的ActionScript类绑定到了同一个包中名 为MyClass的Java类：

package com.mydomain {
[Bindable]
[RemoteClass(alias=”com.mydomain.MyClass”)]
public class MyClass {
public var id:int; public var myText:String;

}
}

[Style]

Style元数据标签用来为组件定义自定义样式属性的。只需要简单地将Sytle元数据标签添加到类的定义当然，然后就可以使用getSytle方法获取它的值了。

标签	描述
[ArrayElementType]	在数组中定义所有允许的数据类型。
[Bindable]	声明一个属性可以在代码中使用数据绑定表达式。
[DefaultProperty]	定义组件在MXML中使用时的默认属性的名称。
[Deprecated]	标识一个类或类的元素是不推荐使用的，这样编译器能认出他并在被调用时给出一个警告信息。
[Effect]	定义MXML的特效属性名称。
[Embed]	在编译时导入 JPED,PNG,SVG 或 SWF文件。也会导入SWC文件的图片资源。他的功能等同于MXML中的 @Embe 语法。
[Event]	定义MXML的事件属性的名称和类型。
[Exclude]	使 Flex Builder 的标签检查器忽略类元素。语法类似 [Exclude(name=”label”, kind=”property”)]
[ExcludeClass]	是 Flex Builder 标签检查器忽略类。这相当于ASDoc中的 @private 标签。
[IconFile]	定义一个图标文件，使组件在Adobe Flex Builder的插入面板中以该图标显示。
[Inspectable]	定义一个属性的列表，供组件使用者在 Flex Builder 的的属性提示和标签检查中使用。同时也定义了属性的可用值。
[InstanceType]	指定了 IDeferredInstance 中的，属性接受的数据类型。
[NonCommittingChangeEvent]	定义一个事件过渡触发器。
[RemoteClass]	把一个ActionScript对象映射到Java对象。
[Style]	为组件的样式属性定义一个MXML标签属性。
[Transient]	当一个 ActionScript 对象被映射到Java对象后，被该标签标识的属性，会从发送到服务端的数据中忽略掉。

 

thanks :    http://www.geoinformatics.cn/?p=899

 

 

English help document:

 

About metadata tags

Metadata tags provide information to the Flex compiler that describes how your components are used in a Flex application. For example, you might create a component that defines a new event. To make that event known to the Flex compiler so that you can reference it in MXML, you insert the [Event] metadata tag into your component, as the following ActionScript class definition shows:

[Event(name="enableChanged", type="flash.events.Event")]
class ModalText extends TextArea {
    ...
}

 

In this example, the [Event] metadata tag specifies the event name and the class that defines the type of the event object dispatched by the event. After you identify the event to the Flex compiler, you can reference it in MXML, as the following example shows:

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="*">

    <mx:Script>
        <![CDATA[
            function handleEnableChangeEvent(eventObj:Event):void { 
                ...
            } 
        ]]>
    </mx:Script>

    <MyComp:ModalText enableChanged="handleEnableChangeEvent(event);"/> 
    
</mx:Application>

 

If you omit the [Event] metadata tag from your class definition, Flex issues a syntax error when it compiles your MXML file. The error message indicates that Flex does not recognize the enableChanged property.

The Flex compiler recognizes component metadata statements in your ActionScript class files and MXML files. The metadata tags define component attributes, data binding properties, events, and other properties of the component. Flex interprets these statements during compilation; they are never interpreted during run time. 

Metadata statements are associated with a class declaration, an individual data field, or a method. They are bound to the next line in the file. When you define a component property or method, add the metadata tag on the line before the property or method declaration. 

Metadata tags in ActionScript

In an ActionScript file, when you define component events or other aspects of a component that affect more than a single property, you add the metadata tag outside the class definition so that the metadata is bound to the entire class, as the following example shows: 

// Add the [Event] metadata tag outside of the class file. 
[Event(name="enableChange", type="flash.events.Event")] 
public class ModalText extends TextArea {

    ...

    // Define class properties/methods
    private var _enableTA:Boolean;

    // Add the [Inspectable] metadata tag before the individual property. 
    [Inspectable(defaultValue="false")] 
    public function set enableTA(val:Boolean):void {
        _enableTA = val;
        this.enabled = val;
    
        // Define event object, initialize it, then dispatch it. 
        var eventObj:Event = new Event("enableChange");
        dispatchEvent(eventObj);
    }
}

 

In this example, you add the [Event] metadata tag before the class definition to indicate that the class dispatches an event named enableChanged. You also include the [Inspectable] metadata tag to indicate the default value of the property for Adobe® Flex™ Builder™. For more information on using this tag, see Inspectable metadata tag.

Metatdata tags in MXML

In an MXML file, you insert the metadata tags either in an <mx:Script> block along with your ActionScript code, or in an <mx:Metadata> block, as the following example shows:

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

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

    <mx:Script>
        <![CDATA[

            // Import Event class.
            import flash.events.Event;

            // Define class properties and methods.
            private var _enableTA:Boolean;

            // Add the [Inspectable] metadata tag before the individual property. 
            [Inspectable(defaultValue="false")] 
            public function set enableTA(val:Boolean):void {
                _enableTA = val;
                this.enabled = val;
    
                // Define event object, initialize it, then dispatch it. 
                var eventObj:Event = new Event("enableChange");
                dispatchEvent(eventObj);
            }
        ]]>
    </mx:Script>
</mx:TextArea>

 

A key difference between the <mx:Metadata> and <mx:Script> tags is that text within the <mx:Metadata> tag is inserted before the generated class declaration, but text within <mx:Script> tag is inserted in the body of the generated class declaration. Therefore, metadata tags like [Event] and [Effect] must go in an <mx:Metadata> tag, but the [Bindable] and [Embed] metadata tags must go in an <mx:Script> tag.

Listing 1 A simple use of [Bindable]

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
backgroundColor="#FFFFFF">
<mx:Script>
<![CDATA[
[Bindable]
private var me:String="Rich Tretola";
]]>
</mx:Script>
<mx:Panel title="Simple Binding" width="500" height="90"
paddingTop="10" paddingLeft="10" paddingRight="10" paddingBottom=" 10" layout="horizontal">
<mx:Label text="{me}"/>
</mx:Panel>
</mx:Application>

Listing 2 Using [Bindable] with getters and setters

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
private var _phoneNumber:String = �";
// Bind getter function to phoneNumberChanged event
[Bindable(event="phoneNumberChanged")]
public function get phoneNumber():String {
return _phoneNumber;
}
// Setter method.
public function set phoneNumber(value:String):void {
if (value.length<10) {
_phoneNumber = value;
} else {
_phoneNumber = phoneFormatter.format(value);
}
// Create and dispatch event
var eventObj:Event = new Event(�phoneNumberChanged");
dispatchEvent(eventObj);
}
]]>
</mx:Script>
<mx:PhoneFormatter id="phoneFormatter"
formatString="(###) ###-####" validPatternChars="#-()
�/>
<mx:Panel title="Bind with Getters and Setters"
width="500" height="90"
paddingTop="10" paddingLeft="10" paddingRight="10" paddingBottom=" 10" layout="horizontal">
<mx:TextInput id="ti1" change="phoneNumber=ti1.text"
maxChars="10" restrict="0-9"/>
<mx:TextInput id="ti2" text="{phoneNumber}"/>
</mx:Panel>
</mx:Application>

Listing 3 Custom Button class named MyButton

package
{
import mx.controls.Button;
[DefaultProperty(�label")]
public class MyButton extends Button
{
}
}

Listing 4 Using the MyButton class wih [DefaultProperty]

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:comps="*">
<comps:MyButton>
<mx:String>Test</mx:String>
</comps:MyButton>
</mx:Application>

Listing 5 Custom ButtonLabel class using [Event]

package
{
import mx.controls.Button;
import flash.events.Event;
// Define the custom event
[Event(name="labelChanged", type="flash.events.Event")]
public class ButtonLabel extends Button {
// property to hold label value
private var _myLabel:String;
// public setter method
public function set myLabel(s:String):void {
_myLabel = s;
this.label = s;
// Create and dispatch custom event
var eventObj:Event = new Event(�labelChanged");
dispatchEvent(eventObj);
}
}
}

Listing 6 Using the ButtonLabel class with the labelChanged [Event]

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:comps="*"
backgroundColor="#FFFFFF">
<mx:Script>
<![CDATA[
import mx.controls.Alert;
import flash.events.Event;
// method to handle custom event
public function labelChanged(eventObj:Event):void {
myTA.text= myTA.text + �\n"+ eventObj.target.label;
myTA.verticalScrollPosition = myTA.verticalScrollPosition +
20;
}
]]>
</mx:Script>
<mx:Panel title="Event Sample" width="500" height="275"
paddingTop="10" paddingLeft="10" paddingRight="10" paddingBottom=" 10" layout="absolute">
<mx:TextInput id="buttonLabelTI"
change="myButton.myLabel=buttonLabelTI.text" x="10" y="9"/>
<!--Instantiate custom class and define method to handle label-
Changed event-->
<comps:ButtonLabel id="myButton" labelChanged="labelChanged(event)
;"
x="10" y="39"/>
<mx:TextArea id="myTA" width="200" height="200" x="249" y="10"/>
</mx:Panel>
</mx:Application>

Listing 7 Add the Effect metadata tag

...
// Define the custom event
[Event(name="labelChanged", type="flash.events.Event")]
[Effect(name="labelChangedEffect", event="labelChanged")]
public class ButtonLabel extends Button {
...

Listing 8 Add labelChangedEffect to the Component

Instantiation MXML Tag
<comps:ButtonLabel id="myButton" labelChanged="labelChanged(event);"
labelChangedEffect="myEffect" x="10" y="39"/>

Listing 9 Custom component with [Inspectable] defined

<?xml version="1.0" encoding="utf-8"?>
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
[Inspectable(defaultValue="Visa",
enumeration="Visa,Mastercard,Discover,American Express"
category="Credit Card" type="String")]
public var ccType:String;
]]>
</mx:Script>
</mx:HBox>

Listing 10 Using [NonCommittingChangeEvent]

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
backgroundColor="#FFFFFF">
<mx:Script>
<![CDATA[
import flash.events.Event;
private var eventObj:Event;
[Bindable(event="triggerBinding")]
[NonCommittingChangeEvent(�change")]
private var s:String;
private function triggerBinding():void{
eventObj = new Event(�triggerBinding");
dispatchEvent(eventObj);
}
]]>
</mx:Script>
<mx:Panel title="NonCommittingChangeEvent Sample" width="500"
height="90"
paddingTop="10" paddingLeft="10" paddingRight="10" paddingBottom=" 10" layout="horizontal">
<mx:TextInput id="ti1" change="s=ti1.text" enter="triggerBinding()"
/>
<mx:TextInput id="ti2" text="{s}" />
</mx:Panel>
</mx:Application>

Listing 11 Custom Class CustomCircle using [Style] tags

package
{
import mx.core.UIComponent;
[Style(name="borderColor",type="uint",format="Color",inherit="no")]
[Style(name="fillColor",type="uint",format="Color",inherit="no")]
public class CustomCircle extends UIComponent {
public function CustomCircle(){
super();
}
override protected function updateDisplayList(unscaledWidth:Number,
unscaledHeight:Number):void {
super.updateDisplayList(unscaledWidth, unscaledHeight);
graphics.lineStyle(1, getStyle(�borderColor"), 1.0);
graphics.beginFill(getStyle(�fillColor"),1.0);
graphics.drawEllipse(0,0,100,100);
}
}
}

Listing 12 Using CustomCircle and assigning custom style properties

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
xmlns:comps="*"
backgroundColor="#FFFFFF">
<mx:Panel title="Style Sample" width="200" height="200"
paddingTop="10" paddingLeft="10" paddingRight="10" paddingBottom=" 10" layout="horizontal">
<comps:CustomCircle borderColor="#000000" fillColor="#FF0000" />
</mx:Panel>
</mx:Application>

 

评论

1 楼 xiejiangbo 2009-09-01  

Difficult circumstances serve as a textbook of life for people.