Flex Metadata tags 元数据标签

1.[Alternative] 【可替换】

标明此类可以被参数中的类替换，版本号说明发生替换的版本。

[Alternative]和[Deprecated] 不同。如果是【不建议使用】的类，以后的版本可能不可用。 而带有【Alternative】标签的类在以后的版本中仍然可用，只是标明有别的类可以用来替换。

例如MX Button就被标记了[Alternative]。

[Alternative(replacement="packageAndClassName", since="versionNum")] 这段代码需要放在类的定义之前。

2.[ArrayElementType] 数组元素类型限定

要使得Flex MXML 编译器对数组元素进行类型检查，需要使用[ArrayElementType]标签来确定该数组许可的类型。

[ArrayElementType("String")]

public var newStringProperty:Array;

注意：MXML 编译器检查MXML 代码中数组的正确使用情况，而不检查AS代码中数组的使用情况。如果用户在标签中输入的是字符串，那么编译器会报语法错误。 参数可以是AS的任意数据类型，例如 String，Number，class或interface。但是必须使用全名，包括package

package
{
    import mx.containers.VBox;

    //定义一个类，该类继承自VBox
    public class MyTypedArrayComponent
    {
        //定义一个数组，并且指定数组中只能存储String数据类型
        [ArrayElementType("String")]
        public var strProperty:Array;

        //定义一个数组，并且指定数组中只能存储Number数据类型
        [ArrayElementType("Number")]
        public var numProperty:Array;

        public function MyTypedArrayComponent()
        {
        }
    }
}

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
               xmlns:s="library://ns.adobe.com/flex/spark"
               xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600"
               xmlns:local="*">
    <fx:Declarations>
        <!-- 将非可视元素（例如服务、值对象）放在此处 -->
        <local:MyTypedArrayComponent>
            <local:strProperty>
                <fx:String>存储String数据类型</fx:String>
            </local:strProperty>
            <local:numProperty>
                <fx:Number>12</fx:Number>
            </local:numProperty>
        </local:MyTypedArrayComponent>
    </fx:Declarations>
</s:Application>

3.[Bindable] 数组绑定

如果某个属性是某个数据绑定表达式的源时，Flex会在源属性变化时自动复制源属性的值到目标属性。

为了让Flex进行这 种复制操作，必须使用[Bindable]元数据标签，并且源属性需要派发事件。

例1：

[Bindable]
public var minFontSize:Number = 5;

例2：

[Bindable("textChanged")]
public function get text():String
{
     return myText;
}

例3：

public function set text(t : String):void
{
     myText = t;
     dispatchEvent( new Event( "textChanged" ) );
} 

如果你省略了事件名，Flex会自动创建"propertyChange"事件。 如果你把某个属性作为数据绑定源，那么Flex不止监视该属性的变化，还监视导向该属性的属性链的变化。

整个属性链（包含链中最终的目标属性）被称为“绑定属性链”。

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

这个例子中，属性链包含firstName和其text属性。

你应该在该属性链中的任何有名称的属性变化时派发事件。如果该属性被标记为[Bindable]，Flex编译器会代你派发。

在某些情况下，绑定不会像预期的那样自动执行：

1.当改变一个dataProvider属性中的整个项时。 dataProvider[i] = newItem

2.当某个带有绑定标签的属性的子属性改变时。

[Bindable]
var temp; // Binding is triggered:
temp = new Object(); // Binding is not triggered, because label not a bindable property // of Object:
temp.label = foo;

在这个例子中，绑定遇到的问题是temp是个Object。有三种方式可以解决这个问题。

a，Preinitialize the Object。 预初始化对象。

b，为temp分配一个ObjectProxy；ObjectProxy的所有属性都是可绑定的。

c，使temp成为带有label可绑定属性的强类型对象。

3.当绑定的属性是Flash Player自动刷新的属性时，例如mouseX 。

如果绑定的目标是UIComponent类，它的executeBindings()方法执行所有绑定。 所有的container和control，包括Repeater组件，都扩展了UIComponent类。

它们的executeChildBindings()方法会同样的执行类型为UIComponent的子项的绑定。所有的容器都继承自Container类。 绑定没有按预期执行时，你可以使用这个方法。

当某个不会触发绑定的改变发生时，在代码中加上一句，例如executeChildBindings()这个方法，就可以更新用户界面。

然而，你应该只在绑定确实不会自动触发时，才使用executeBindings()方法。

http://www.adobe.com/devnet/flex/articles/databinding_pitfalls.html 这篇文章对绑定讲解的很细致。

4.[DefaultProperty] 默认的属性

定义组件在MXML文件中使用时的默认属性名称。

例如： 这样定义后

// Define the default property.
 [DefaultProperty("defaultText")]
public class TextAreaDefaultProp extends TextArea {     } 

就可以这样使用

<MyComp:TextAreaDefaultProp>Hello</MyComp:TextAreaDefaultProp>

5.Deprecated

类或者类元素被标记为[Deprecated]标明该类或属性已被废弃并且不推荐在当前版本中使用。不过该类或类元素仍然可以 工作，但编译器会发出警告。

mxmlc命令行编译器支持show-deprecation-warnings编译选项。当为true时，如果你使用了deprecated的元素，编译器会 发出deprecation警告。默认值为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")]

[Event], [Effect] 和 [Style] 也支持deprecation：

[Event(... , deprecatedMessage="string_describing_deprecation")]

[Event(... , deprecatedReplacement="change2")]

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

6.[Effect][效果]

此标签定义了组件在MXML状态下的效果属性名称及触发该效果的事件，你可以通过这个属性给该组件分配一种动态效果。 动态效果总是伴随着触发它的事件。

该事件可能是鼠标点击事件、获得焦点事件或可见事件。动态效果是指在一段时间发 生的可视或可听的变化。 一般在类定义之前或在<fx:Metadata>标签内定义[Effect]标签。

// Define event corresponding to the effect trigger.
[Effect(name="eventNameEffect", event="eventName")]
[Event(name="darken", type="flash.events.Event")] // Define the effect.
[Effect(name="darkenEffect", event="darken")]
class ModalText extends TextArea {     ... }
<fx:Metadata>
      [Event(name="darken", type="flash.events.Event")]
      [Effect(name="darkenEffect", event="darken")]
      [Effect(name="showControlBarEffect", type="showControlBar")]
</fx:Metadata>

6.[Embed] 可以在Flex应用程序中嵌入各种元素。

被嵌入的元素将编译进SWF文件。它们不是在运行时载入的，所以不必为应用程序部署原元素。 可以嵌入的图像格式有PNG、JPEG、GIF。嵌入后可以同时使用它的多个实例。

下面的例子使用[Embed]原标签经image嵌入应用程序，并且采用绑定ActionScript类的形式。这就可以绑定Image控件的source属性到Logo类。

可以绑定Logo类到任何可以使用image的组件属性上，比如Button控件的icon属性。

 [Embed(source="assets/logo.png")]
<mx:Image id="myLogo"source="@Embed('assets/logo.png')"/>
<mx:Style>
 Button {
     upSkin: Embed("assets/box_closed.png");
     overSkin: Embed("assets/box.png");
     downSkin: Embed("assets/box_new.png");
 }
</mx:Style>
[Embed(source="assets/library.swf", symbol="BadApple")]
[Bindable]
public var BadApple:Class; 

Embed元数据标签的参数属性： 
source：必须属性，用来指定要嵌入的资源的路径地址。 
mimeType:可选的属性，用来指定嵌入资源的元数据信息。如果不填写，flex自动识别资源的元数据。可选值有： 
                 application/octet-stream 
                 application/x-font 
                 application/x-font-truetype 
                 application/x-shockwave-flash 
                 audio/mpeg 
                 image/gif 
                 image/jpeg 
                 image/png 
                 image/svg 
                 image/svg-xml 
scaleGridTop：用作Scale-9格式的图片时，指定图片上端固定尺寸的像素值 
scaleGridBottom：用作Scale-9格式的图片时，指定图片下端固定尺寸的像素值 
scaleGridLeft：用作Scale-9格式的图片时，指定图片左侧固定尺寸的像素值。 
scaleGridRight：用作Scale-9格式的图片时，指定图片右侧固定尺寸的像素值。 
symbol：指定从Flash中要导入的图片标识名。

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

如

[Event(name="myEnableEvent", type="flash.events.Event")]
public class MyComponent extends UIComponent {     ... }
或
<fx:Metadata>
         [Event(name="myEnableEvent",type="flash.events.Event")]
</fx:Metadata> 

1. 在MyButton中将[Event]标签放入Metadata标签中，则告诉编译器该空间会产生该种Event，如果此时dispatchEvent出去的Event不是该种类型 则在编译期间及会报错。

2. 在主类中

<my:MyButton id="my1" EventTest="myTa.text='got Event';" x="208" y="213">
</my:MyButton>

由于EventTest已经在Metadata做了标记，即可使用代码提示功能找到相应的Event。

EventTest="myTa.text='got Event';"

表示为EventTest 这个Event注册一个监听者，监听到信息后处理方式为    myTa.text='got Event' ， 等同于 EventTest="handleEvent(event)

例如：

package event
{
      import flash.events.Event;
      public class MyEvent extends Event
      {
            public static const EVENT_TEST:String="EventTest";
            public function MyEvent(type:String, bubbles:Boolean=false, cancelable:Boolean=false)
            {
                    super(type, bubbles, cancelable);
             }
      }
} 

<?xml version="1.0" encoding="utf-8"?>
<s:Button xmlns:fx="http://ns.adobe.com/mxml/2009"       xmlns:s="library://ns.adobe.com/flex/spark"       xmlns:mx="library://ns.adobe.com/flex/halo"       click="dispatchEvent(new MyEvent(MyEvent.EVENT_TEST));">
<fx:Script>
     <![CDATA[
           import event.MyEvent;     ]]>
</fx:Script>
<fx:Metadata>
       <!--在Metadata标签下定义Event编译期间检查-->
              [Event(name ="EventTest",type ="event.MyEvent")]
</fx:Metadata>
</s:Button>
<fx:Script>
     <![CDATA[
       import event.MyEvent;
       /**
        * 定义Event的函数监听方式
        * 在my2 的 EventTest="handleEvent(event)" 相当于对于该Event注册了一个Listiner
        * 消息监听函数为handleEvent(event)
        */
       private function handleEvent(e:MyEvent):void{ trace(e); }     ]]>
</fx:Script>
   <!--可以直接定义EventTest="myTa.text='got Event';" 及在Event触发式执行myTa.text='got Event';-->
<my:MyButton id="my1" EventTest="myTa.text='got Event';" x="208" y="213">
</my:MyButton>
<my:MyButton id="my2" EventTest="handleEvent(event)" x="209" y="258">
</my:MyButton>

8.[Exclude]  让Flash Builder标签检查忽略该类元素。 [Exclude(name="label", kind="property")]

9.[ExcludeClass]  让Flash Builder标签检查忽略该类。等同于ASDoc中的@private标签。

10.[HostComponent]  用此标签确定Spark 皮肤类的宿主组件。

例如：

 <Metadata>[HostComponent("spark.components.Button")] </Metadata>

加了这个标签，Flex会为此皮肤类创建hostComponent属性。你可以通过这个属性在皮肤类内部获取宿主组件实例的公共成员。例如，在Button 皮肤内，可以得到Button样式的属性。

11.IconFile] 用此标签定义组件在Flash Builder中的Insert栏中的图标的文件名。 支持PNG, GIF, JPEG

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

12.[Inspectable] 此标签为你的组件的属性定义了编码提示信息。

规则如下：

* 组件所有的public属性都会出现在编码提示和Flash Builder属性监测器中。如果你想为该属性添加额 外的信息，例如枚举值或代表一个文件路径的String属性，就为该属性添加[Inspectalbe]标签及信息。

* 组件的编码提示和属性监测器公用同样的数据。

* AS组件的编码提示并不需要metadata，因此你总是能看到符合当前作用范围的属性提示。

Flash Builder使用public/protected/private和static这些关键字来控制属性的作用范围及可显示的编码提示。 此标签后必须紧跟属性变量声明或其set和get方法：

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

[Inspectable(attribute=value[,attribute=value,...])] setter_getter_declarations;

flex里的[Inspectable]标签用于为as类的属性定义一些可供flex代码提示等使用的信息，比如属性的类型啦合法值啦默认值啦之类的，[Inspectable]标签可以用在属性上，也可以用在getter/setter方法上，写法如下：

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

[Inspectable(attribute=value[, attribute=value, …])] setter_getter_declarations;

[Inspectable]标签有如下属性： PropertyTypeDescriptioncategoryStringenumerationString用逗号分隔指定一系列合法值，只有这些值才允许设置，例如“test1,test2,test3”，注意值与值之间不要使用空格，否则flex会认为空格是值的一部分（除非你确实想这样啦），这信息会出现在代码提示和属性检查器里formatStringtypeString设定属性的类型，如果忽略则使用属性本身的数据类型，可选值如下： Array, Boolean, Color, Font Name, List, Number, Object, String 例如下面这样的代码：

[Inspectable(type="String", enumeration="left,center,right")]
public var labelPlacement:String = LabelPlacement.LEFT; 

在flex/flashbuilder上编辑时，就会弹出如下的代码提示框，提示可选的值：

例如：

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

Property TypeDescription  

category	String	将属性归纳入FB用户界面的属性监测器中的子类别中。默认类别是 "Other". 可以归类为"Common","Effects","Events","Layout Constraints","Size","Styles","Text",or"Other".
defaultValue	String or Number	设置属性的初始值。默认值为属性的定义值。
enumeration	String	为属性定义一组以逗号分隔的合法值。该属性只可以取这些值。例如：item1,item2,item3. 注意中间没有空格。这些值会出现在代码提示及属性检测器中。如果你定义了Boolean类型变量，FB会自动显示true和false，不需要你自己设置。
environment	String	environment=none：可检测属性不允许出现；environment=Flash：只有Flash Builder可用；(environment=MXML：只有Flex可用，Flash Builder也不可用。
format	String	当编辑该属性值时使用的编辑器类型。 例如，对于Number类型的属性，你可以设置format="Color"来让FB在你设置属性值时打开颜色编辑器。一般的值为"Length","Color","Time","EmbeddedFile"和"File".
listOffset	Number	设定List值中的默认索引。 Specifies the default index into a List value.
name	String	设定属性的显示名称。例如，FontWidth。如果没设定，会使用属性名，例如_fontWidht.
type	String	指定类型的指定器。如果省略，会使用属性的类型。 下列值可取： Array Boolean Color Font Name List Number Object String 如果类型是Array，你必须列出Array的可用值。
variable	String	指定此参数绑定的变量。
verbose	Number	表明此属性只有在用户指明包含verbose（详细的）属性时才在FB用户界面中出现。如果未设定，则默认显示该属性。

12.[InstanceType] 主要用于创建模板组件。

 [InstanceType("mx.controls.Label")]
 public var topRow:IDeferredInstance;

13.[NonCommittingChangeEvent] 此标签定义了一种折中事件，这种事件不会引起Flex数据验证。通常用于经常变化但又不需要每次都进行数据验证的属性。

例如，你给一个TextInput组件的text属性绑定了某个验证器。text属性会在每次键盘输入事件时改变，但你只是希望在用户按下Enter键或移除焦点时进行数据验证。此类型事件可以使你分派改变事件但不出发验证。

 [NonCommittingChangeEvent("event_name")] 

下例中，组件在每次用户键盘输入时都分派change事件，但这个change事件并没有引发数据绑定或数据验证。当用户完成数据输入并点击Enter键时，组件广播valueCommit事件来出发数据绑定和数据验证。 

[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.
      }
 }

14.[RemoteClass] 用此标签将类注册到Flex，Flex会在用AMF格式序列化类实例时保留类型信息。需要在类定义之前插入此 标签。

还可以在客户端程序中用此标签代表某个服务端Java对象： [RemoteClass(alias=" ")] 这样可以创建直接映射到Java对象的AS对象。需要在alias值中赋予Java类的全名。 

15.[RichTextContent] 如果一个属性是String类型，编译器会自动试着把其MXML中的值转为String类型。

如果属性类型是*、 Object或Array，编译器在默认情况下会试图将其转换为适当的数据类型。

使用此标签可以让编译器始终 将该属性MXML中的值转为String。需要在属性定义前插入此标签。 [RichTextContent] 例如，spark.components.TextArea 和 spark.primitives.RichText类的content属性被作为Object输入 。

但如果使用了此标签，那些值就会始终被作为String类型。 数据绑定语法中的花括号{}，at符号@都对此标签有效。

16.[SkinPart] 在SkinnableComponent中，可以声明SkinPart元标签对Skin进行约束，同时在组件中提供对Skin元素的引用：

[SkinPart(required="false")]
public var labelElement:SimpleText;
[SkinPart(type="mx.core.IVisualElement"]
public var pauseButton :IFactory; 

17.[SkinState] 定义皮肤中的状态。

[SkinState("normal")]
[SkinState("compact")]
[SkinState("disabled")]
function StatefulComponent { ... }

18.[Style] 定义样式。 插入到类定义前或MXML中的<fx:Metadata>中。

[Style(name="cornerRadius", type="uint", format="Color", inherit="no")]
[Style(name="MyButtonSkin", type="class" states="down,over")]

package{
import mx.core.UIComponent;
[Style(name="myStyle",type="unit",format="Color",inherit="no")]
public class MyComponent extends UIComponent{
    override public function updateDisplayList(uwindth:Number,uHeight:Number):void{
        super.updateDisplayList(uwidth,uHeight);
        graphics.beginFill(getStyle("myStyle"),1.0);
        graphics.drawEllipse(0,0,100,100);
    }
}
}

19.[SWF] 在AS中定义main application的属性。在MXML中一般在<s:Application>标签中定义。 

20.[Transient] Flex中的Transient 元数据标签的意思和英文一样。

当你在发送对象给远程服务器时，比如你发送一个User对象给远程服务器端， 而你在Flex端新增了一个属性，比如email，这个属性在服务器端是不存在的，而你不希望这个属性被回传给服务器端， 这时你就可以使用[Transient]元数据标签了。

使用示例如下：

[Bindable]
[RemoteClass(alias="com.myflexhero.domain.User")]
public class User
{
         public var id:Number;
         public var LoginName:String;
         [Transient]
         public var email:String;
}