Flex中的元数据标签Metadata tags

http://livedocs.adobe.com/flex/3/html/help.html?content=metadata_3.html

The following table describes the metadata tags that you can use in ActionScript class files:

Tag	Description
[ArrayElementType]	Defines the allowed data type of each element of an Array. For more information, seeArrayElementType metadata tag.
[Bindable]	Identifies a property that you can use as the source of a data binding expression. For more information, see Bindable metadata tag.
[DefaultProperty]	Defines the name of the default property of the component when you use the component in an MXML file. For more information, see DefaultProperty metadata tag.
[Deprecated]	Marks a class or class element as deprecated so that the compiler can recognize it and issue a warning when the element is used in an application. For more information, see Deprecated metadata tag.
[Effect]	Defines the MXML property name for the effect. For more information, see Effect metadata tag.
[Embed]	Imports JPEG, GIF, PNG, SVG, and SWF files at compile time. Also imports image assets from SWC files. This is functionally equivalent to the MXML @Embed syntax, as described in Embedding Assets.
[Event]	Defines the MXML property for an event and the data type of the event object that a component emits. For more information, see Event metadata tag.
[Exclude]	Omits the class element from the Flex Builder tag inspector. The syntax is as follows: [Exclude(name="label", kind="property")]
[ExcludeClass]	Omits the class from the Flex Builder tag inspector. This is equivalent to the @private tag in ASDoc when applied to a class.
[IconFile]	Identifies the filename for the icon that represents the component in the Insert bar of Adobe Flex Builder. For more information, see IconFile metadata tag.
[Inspectable]	Defines an attribute exposed to component users in the attribute hints and Tag inspector of Flex Builder. Also limits allowable values of the property. For more information, see Inspectable metadata tag.
[InstanceType]	Specifies the allowed data type of a property of type IDeferredInstance. For more information, seeInstanceType metadata tag.
[NonCommittingChangeEvent]	Identifies an event as an interim trigger. For more information, see NonCommittingChangeEvent metadata tag.
[RemoteClass]	Maps the ActionScript object to a Java object. For more information on using the[RemoteClass] metadata tag, see RemoteClass metadata tag.
[Style]	Defines the MXML property for a style property for the component. For more information on using the [Style] metadata tag, see Style metadata tag.
[Transient]	Identifies a property that should be omitted from data that is sent to the server when an ActionScript object is mapped to a Java object using [RemoteClass]. For more information, see Transient metadata tag.

ArrayElementType metadata tag

When you define an Array variable in ActionScript, you specify Array as the data type of the variable. However, you cannot specify the data type of the elements of the Array.

To allow the Flex MXML compiler to perform type checking on Array elements, you can use the [ArrayElementType] metadata tag to specify the allowed data type of the Array elements, as the following example shows:

public class MyTypedArrayComponent extends VBox {

    [ArrayElementType("String")] 
    public var newStringProperty:Array;

    [ArrayElementType("Number")] 
    public var newNumberProperty:Array;
    ...
} 

 

Note: The MXML compiler checks for proper usage of the Array only in MXML code; it does not check Array usage in ActionScript code.

 

In this example, you specify String as the allowed data type of the Array elements. If a user attempts to assign elements of a data type other than String to the Array in an MXML file, the compiler issues a syntax error, as the following example shows:

<MyComp:MyTypedArrayComponent>
    <MyComp:newStringProperty>
        <mx:Number>94062</mx:Number>
        <mx:Number>14850</mx:Number>
        <mx:Number>53402</mx:Number>
    </MyComp:newStringProperty>
</MyComp:MyTypedArrayComponent>

In this example, you try to use Number objects to initialize the Array, so the compiler issues an error.

You can also specify Array properties as tag attributes, rather than using child tags, as the following example shows:

<MyComp:MyTypedArrayComponent newNumberProperty="[abc,def]"/>

This MXML code generates an error because Flex cannot convert the Strings "abc" and "def" to a Number.

You insert the [ArrayElementType] metadata tag before the variable definition. The tag has the following syntax:

[ArrayElementType("elementType")]

The following table describes the property of the [ArrayElementType] metadata tag:

Property	Type	Description
elementType	String	Specifies the data type of the Array elements, and can be one of the ActionScript data types, such as String, Number, class, or interface. You must specify the type as a fully qualified class name, including the package.

Bindable metadata tag

When a property is the source of a data binding expression, Flex automatically copies the value of the source property to any destination property when the source property changes. To signal to Flex to perform the copy, you must use the [Bindable] metadata tag to register the property with Flex, and the source property must dispatch an event.

The [Bindable] metadata tag has the following syntax:

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

If you omit the event name, Flex automatically creates an event named propertyChange.

For more information on data binding and on this metadata tag, see Binding Data.

Working with bindable property chains

When you specify a property as the source of a data binding, Flex monitors not only that property for changes, but also the chain of properties leading up to it. The entire chain of properties, including the destination property, is called a bindable property chain. In the following example,firstName.text is a bindable property chain that includes both a firstName object and its text property:

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

You should raise an event when any named property in a bindable property chain changes. If the property is marked with the [Bindable] metadata tag, the Flex compiler generates the event for you.

The following example uses the [Bindable] metadata tag for a variable and a getter property. The example also shows how to call thedispatchEvent() function.

[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" ) );}

If you omit the event name in the [Bindable] metadata tag, the Flex compiler automatically generates and dispatches an event namedpropertyChange so that the property can be used as the source of a data binding expression.

You should also provide the compiler with specific information about an object by casting the object to a known type. In the following example, themyList List control contains Customer objects, so the selectedItem property is cast to a Customer object:

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

There are some situations in which binding does not execute automatically as expected. Binding does not execute automatically when you change an entire item of a dataProvider property, as the following example shows:

dataProvider[i] = newItem

Binding also does not execute automatically for subproperties of properties that have [Bindable] metadata, as the following example shows:

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

In this code example, the problem with {temp.label} is that temp is an Object. You can solve this problem in one of the following ways:

• Preinitialize the Object.
• Assign an ObjectProxy to temp; all of an ObjectProxy's properties are bindable.
• Make temp a strongly typed object with a label property that is bindable.

Binding also does not execute automatically when you are binding data to a property that Flash Player updates automatically, such as the mouseXproperty.

The executeBindings() method of the UIComponent class executes all the bindings for which a UIComponent object is the destination. All containers and controls, as well as the Repeater component, extend the UIComponent class. The executeChildBindings() method of the Container and Repeater classes executes all of the bindings for which the child UIComponent components of a Container or Repeater class are destinations. All containers extend the Container class.

These methods give you a way to execute bindings that do not occur as expected. By adding one line of code, such as a call toexecuteChildBindings() method, you can update the user interface after making a change that does not cause bindings to execute. However, you should only use the executeBindings() method when you are sure that bindings do not execute automatically.

DefaultProperty metadata tag

The [DefaultProperty] metadata tag defines the name of the default property of the component when you use the component in an MXML file.

The [DefaultProperty] metadata tag has the following syntax:

[DefaultProperty("propertyName")]

The propertyName property specifies the name of the default property.

You can use the [DefaultProperty] metadata tag in your ActionScript component to define a single default property. For more information and an example, see Creating a default property.

Deprecated metadata tag

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.

The mxmlc command-line compiler supports the show-deprecation-warnings compiler option, which, when true, configures the compiler to issue deprecation warnings when your application uses deprecated elements. The default value is true.

Insert the [Deprecated] metadata tag before a property, method, or class definition to mark that element as deprecated. The [Deprecated]metadata tag has the following options for its syntax when used with a class, property or method:

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

The following uses the [Deprecated] metadata tag to mark the dataProvider property as obsolete:

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

The [Event], [Effect] and [Style] metadata tags also support deprecation. These tags support the following options for syntax:

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

These metadata tags support the deprecatedReplacement and deprecatedSince attributes to mark the event, effect, or style as deprecated.

Effect metadata tag

The [Effect] metadata tag defines the name of the MXML property that you use to assign an effect to a component and the event that triggers the effect. If you define a custom effect, you can use the [Effect] metadata tag to specify that property to the Flex compiler.

For more information on defining custom effects, see Effects.

An effect is paired with a trigger that invokes the effect. A trigger is an event, such as a mouse click on a component, a component getting focus, or a component becoming visible. An effect is a visible or audible change to the component that occurs over a period of time.

You insert the [Effect] metadata tag before the class definition in an ActionScript file or in the <mx:Metadata> block in an MXML file. The[Effect] metadata tag has the following syntax:

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

The following table describes the properties of the [Effect] metadata tag:

Property	Type	Description
eventNameEffect	String	Specifies the name of the effect.
eventName	String	Specifies the name of the event that triggers the effect.

The [Effect] metadata tag is often paired with an [Event] metadata tag, where the [Event] metadata tag defines the event corresponding to the effect's trigger. By convention, the name of the effect is the event name with the suffix Effect, as the following example of an ActionScript file shows:

// 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 {
    ...
}

In an MXML file, you can define the event and effect in an <mx:Metadata> block, as the following example shows:

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

Event metadata tag

Use the [Event] metadata tag to define the MXML property for an event and the data type of the event object that a component emits. You insert the [Event] metadata tag before the class definition in an ActionScript file, or in the <mx:Metadata> block in an MXML file.

For more information on defining custom events, see Custom Events.

The [Event] metadata tag has the following syntax:

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

The following table describes the properties of the [Event] metadata tag:

Property	Type	Description
eventName	String	Specifies the name of the event, including its package name.
eventType	String	Specifies the class that defines the data type of the event object. The class name is either the base event class, Event, or a subclass of the Event class. You must include the package in the class name.

The following example identifies the myClickEvent event as an event that the component can dispatch:

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

If you do not identify an event in the class file with the [Event] metadata tag, the MXML compiler generates an error if you try to use the event name in MXML. Any component can register an event listener for the event in ActionScript by using the addEventListener() method, even if you omit the [Event] metadata tag.

The following example identifies the myClickEvent event as an event that an ActionScript component can dispatch:

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

The following example shows the [Event] metadata tag in the <mx:Metadata> tag in an MXML file:

<?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 metadata tag

Use the [IconFile] metadata tag to identify the filename for the icon that represents the component in the Insert bar of Flex Builder.

The [IconFile] metadata tag has the following syntax:

[IconFile("fileName")]

The fileName property specifies a PNG, GIF, or JPEG file that contains the icon, as the following example shows:

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

Inspectable metadata tag

The [Inspectable] metadata tag defines information about an attribute of your component that you expose in code hints and in the Property inspector area of Flex Builder. The [Inspectable] metadata tag is not required for either code hints or the Property inspector. The following rules determine how Flex Builder displays this information:

• All public properties in components appear in code hints and in the Flex Builder Property inspector. If you have extra information about the property that you want to add, such as enumeration values or that a String property represents a file path, add the [Inspectable]metadata tag with that information.
• Code hints for components and the information in the Property inspector come from the same data. Therefore, if the attribute appears in one, it should appear in the other.
• Code hints for ActionScript components do not require metadata to work correctly so that you always see the appropriate code hints, depending the current scope. Flex Builder uses the public, protected, private, and static keywords, plus the current scope, to determine which ActionScript code hints to show.

The [Inspectable] metadata tag must immediately precede the property's variable declaration or the setter and getter methods to be bound to that property. The [Inspectable] metadata tag has the following syntaxes:

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

The following table describes the properties of the [Inspectable] metadata tag:

Property	Type	Description
category	String	Groups the property into a specific subcategory in the Property inspector of the Flex Builder user interface. The default category is "Other". Specify a value of "Common", "Effects", "Events", "Layout Constraints", "Size", "Styles", or "Other".
defaultValue	String or  Number	Sets the initial value in the editor that appears in the Property inspector when you modify the attribute. The default value is determined from the property definition.
enumeration	String	Specifies a comma-delimited list of legal values for the property. Only these values are allowed; for example,item1,item2,item3. Notice the lack of a space character between items so that Flex Builder does not interpret a space as a part of a valid value. This information appears as code hints and in the Property inspector. If you define a Boolean variable, Flex Builder automatically shows true and false without you having to specifying them usingenumeration.
environment	String	Specifies which inspectable properties should not be allowed (environment=none), which are used only for Flex Builder (environment=Flash), and which are used only by Flex and not Flex Builder (environment=MXML).
format	String	Determines the type of editor that appears in the Property inspector when you modify the attribute. You can use this property when the data type of the attribute is not specific to its function. For example, for a property of type Number, you can specify format="Color" to cause Flex Builder to open a color editor when you modify the attribute. Common values for the format property include "Length", "Color","Time", "EmbeddedFile", and "File".
listOffset	Number	Specifies the default index into a List value.
name	String	Specifies the display name for the property; for example, Font Width. If not specified, use the property's name, such as _fontWidth.
type	String	Specifies the type specifier. If omitted, use the property's type. The following values are valid: Array Boolean Color Font Name List Number Object String If the property is an Array, you must list the valid values for the Array.
variable	String	Specifies the variable to which this parameter is bound.
verbose	Number	Indicates that this inspectable property should be displayed in the Flex Builder user interface only when the user indicates that verbose properties should be included. If this property is not specified, Flex Builder assumes that the property should be displayed.

The following example defines the myProp parameter as inspectable:

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

InstanceType metadata tag

The [InstanceType] metadata tag specifies the allowed data type of a property of type IDeferredInstance, as the following example shows:

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

The Flex compiler validates that users assign values only of the specified type to the property. In this example, if the component user sets thetopRow property to a value of a type other than mx.controls.Label, the compiler issues an error message.

You use the [InstanceType] metadata tag when creating template components. For more information, see Template Components.

The [InstanceType] metadata tag has the following syntax:

[InstanceType("package.className")]

You must specify a fully qualified package and class name.

NonCommittingChangeEvent metadata tag

The [NonCommittingChangeEvent] metadata tag identifies an event as an interim trigger, which means that the event should not invoke Flex data validators on the property. You use this tag for properties that might change often, but which you do not want to validate on every change.

An example of this is if you tied a validator to the text property of a TextInput control. The text property changes on every keystroke, but you do not want to validate the property until the user presses the Enter key or changes focus away from the field. The NonCommittingChangeEventtag lets you dispatch a change event, but that does not trigger validation.

You insert the [NonCommittingChangeEvent] metadata tag before an ActionScript property definition or before a setter or getter method. The [NonCommittingChangeEvent] metadata tag has the following syntax:

[NonCommittingChangeEvent("event_name")]

In the following example, the component dispatches the change event every time the user enters a keystroke, but the change event does not trigger data binding or data validators. When the user completes data entry by pressing the Enter key, the component broadcasts thevalueCommit event to trigger any data bindings and data validators:

[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 metadata tag

Use the [RemoteClass] metadata tag to register the class with Flex so that Flex preserves type information when a class instance is serialized by using Action Message Format (AMF). You insert the [RemoteClass] metadata tag before an ActionScript class definition. The [RemoteClass]metadata tag has the following syntax:

[RemoteClass]

You can also use this tag to represent a server-side Java object in a client application. You use the [RemoteClass(alias=" ")] metadata tag to create an ActionScript object that maps directly to the Java object. You specify the fully qualified class name of the Java class as the value ofalias. For more information, see Accessing Server-Side Data with Flex.

Style metadata tag

Use the [Style] metadata tag to define the MXML tag attribute for a style property for the component. You insert the [Style] metadata tag before the class definition in an ActionScript file, or in the <mx:Metadata> block in an MXML file.

The [Style] metadata tag has the following syntax:

[Style(name="style_name"[,property="value",...])]

The following table describes the properties for the [Style] metadata tag:

Option	Type	Description
name	String	(Required) Specifies the name of the style.
type	String	Specifies the data type of the value that you write to the style property. If the type is not an ActionScript type such as Number or Date, use a qualified class name in the form packageName.className.
arrayType	String	If type is Array, arrayType specifies the data type of the Array elements. If the data type is not an ActionScript type such as Number or Date, use a qualified class name in the form packageName.className.
format	String	Specifies the units of the property. For example, if you specify type as "Number", you might specifyformat="Length" if the style defines a length measured in pixels. Or, if you specify type="uint", you might set format="Color" if the style defines an RGB color.
enumeration	String	Specifies an enumerated list of possible values for the style property.
inherit	String	Specifies whether the property is inheriting. Valid values are yes and no. This property refers to CSS inheritance, not object-oriented inheritance. All subclasses automatically use object-oriented inheritance to inherit the style property definitions of their superclasses. Some style properties are inherited using CSS inheritance. If you set an inheritable style property on a parent container, its children inherit that style property. For example, if you define fontFamily as Times for a Panel container, all children of that container will also use Times for fontFamily, unless they override that property. If you set a noninheritable style, such as textDecoration, on a parent container, only the parent container and not its children use that style. For more information on inheritable style properties, see About style inheritance.
states	String	For skin properties, specifies that you can use the style to specify a stateful skin for multiple states of the component. For example, the definition of the Slider.thumbSkin style uses the following [Style]metadata tag: [Style(name="thumbSkin", type="Class", inherit="no", states="disabled, down, over, up")] This line specifies that you can use the Slider.thumbSkin style to specify a stateful skin for the disabled, down, over, and up states of the Slider control. For more information, see Creating Skins.

The following example shows the definition of the textSelectedColor style property:

[Style(name="textSelectedColor",type="Number",format="Color",inherit="yes")]

The next example shows the definition of the verticalAlign style property:

[Style(name="verticalAlign", type="String", enumeration="bottom,middle,top", inherit="no")]

For more information on the [Style] metadata tag, see Custom Style Properties.

Transient metadata tag

Use the [Transient] metadata tag to identifies a property that should be omitted from data that is sent to the server when an ActionScript object is mapped to a Java object using the [RemoteClass] metadata tag.

The [Transient] metadata tag has the following syntax:

[Transient]
public var count:Number = 5;