Merci de votre visite. Cette page est disponible en anglais uniquement.

APL Base Component Properties

A component is a primitive element that displays on the viewport.

In APL, components are primitive visual components rendered by the client. Although you can add the definition of new templates by creating APL files and importing them into other APL, new low-level components would require updates to the clients to be able to recognize and convert them to native user interface controls on devices.

Properties

All components support the following properties. See below the table for more information about the meaning of the columns.

Property Type Default Styled Dynamic Description Version added
accessibilityLabel String "" No No Voice-over will read this string when the user selects this component 1.1
bind Array of Binding [] No No Expressions to add to the data binding context 1.0
description String "" No No Optional description of this component 1.0
checked Boolean false No Yes If true, this component has the checked state set. 1.1
disabled Boolean false No Yes If true, this component does not respond to touch or focus. 1.1
display String (invisible, none, normal) normal Yes Yes Determines whether the component is displayed on the screen. 1.1
entity (entities) Array of Entities [] No No Opaque data used to clarify references in Alexa 1.0
height Dimension auto No No The requested height of the component. 1.0
id String "" No No Reference name of the component, used for navigation and events. 1.0
inheritParentState Boolean false No No When true, use the parent's state. 1.0
maxHeight Dimension <none> No No The maximum allowed height of this component. 1.0
maxWidth Dimension <none> No No The maximum allowed width of this component. 1.0
minHeight Dimension 0 No No The minimum allowed height of this component. 1.0
minWidth Dimension 0 No No The minimum allowed width of this component. 1.0
onMount Array of command [] No No Command to execute when the component is first displayed. 1.1
onCursorEnter Array of command [] No No Command(s) to execute when a cursor (mouse pointer) enters the component's active region. 1.2
onCursorExit Array of command [] No No Command(s) to execute when a cursor (mouse pointer) exits the component's active region. 1.2
opacity Number 1.0 Yes Yes Opacity of this component and children. 1.0
paddingBottom Absolute Dimension 0 No No Space to add to the bottom of this component. 1.0
paddingLeft Absolute Dimension 0 No No Space to add to the left of this component. 1.0
paddingRight Absolute Dimension 0 No No Space to add to the right of this component. 1.0
paddingTop Absolute Dimension 0 No No Space to add to the top of this component. 1.0
shadowColor Color transparent Yes No Shadow color 1.2
shadowHorizontalOffset Absolute Dimension 0 Yes No Horizontal offset of the shadow 1.2
shadowRadius Absolute Dimension 0 Yes No Shadow blur radius 1.2
shadowVerticalOffset Absolute Dimension 0 Yes No Vertical offset of the shadow 1.2
speech Opaque <none> No No Transformed speech information for audio playback 1.0
style Style "" No No Named style or styles to apply. 1.0
transform Array of transform [] No Yes Array of transformations. 1.1
type String REQUIRED No No The type of the component. 1.0
when Boolean true No No If it evaluates to false, this component does not inflate. 1.0
width Dimension auto No No The requested width of this component. 1.0

The Default column lists the default values of properties. All REQUIRED properties must be set or the component will not inflate. A value of <none> means the property does not have a default value. The interpretation of <none> is property-dependent. For example, not setting the speech property prevents a component from executing the SpeakItem command. Not setting maxHeight allows the component to grow arbitrarily tall, which is equivalent to setting maxHeight to a very large number.

The Styled column identifies properties that you can set from a style. Directly specifying a component property overrides any style-defined values. In the following example the Text component always has an opacity of 0.5 regardless of what might be defined in myTextStyle:

    {
      "type": "Text",
      "opacity": 0.5,
      "style": "myTextStyle"
    }

The Dynamic column identifies properties that you can change dynamically with the SetValue command. Setting a dynamic property with SetValue overrides any style values. There is no mechanism to unset a dynamic property.

When the component is the target of an event, the following values are reported in event.target:

{
    "event": {
        "target": {
            "disabled": Boolean,
            "height": Number,   
            "id": ID,           
            "uid": UID,         
            "opacity": Number,  
            "width": Number     
        }
    }
}

Component-specific values are added to event.target.

accessibilityLabel

A text string used by a screen reader in accessibility mode.

bind

The bind property of a component extends the data-binding context for the component and its children. The bind property also specifies an ordered set of data-bindings that extend the current context. Bindings are ordered, and later bindings may use previous definitions.

bind properties

Each binding object in the binding array contains the following properties

Property Type Default Description
name String REQUIRED Name to use for this binding. Must be a valid name.
value Any REQUIRED Value to assign to this binding. If a string, data-binding will occur on the contents of the string.
type Type any Property type.

bind evaluation

The bind property evaluates after the when property and before any other properties. Bindings are added to the data-binding context in array order; later bindings may use the results from earlier bindings. For example:

{
  "type": "Text",
  "bind": [
    { "name": "FirstName", "value": "Jasmine" },
    { "name": "LastName", "value": "Smith"},
    { "name": "Title", "value": "Dr."},
    { "name": "FormalName", "value": "${Title} ${LastName}" }
  ],
  "text": "Should I call you ${FirstName} or ${FormalName}?"
}

In this example, FormalName depends upon the prior definitions of Title and LastName. The final text will be “Should I call you Jasmine or Dr. Smith?”. This example is contrived; in actual use the values of FirstName, LastName, and Title would be bound to elements provided in the raw data.

Binding values can be changed dynamically using the set_value_command. Because the set_value_command is also used to change properties of a component, it is recommended that bound properties be named starting with a capital letter so that they never conflict with intrinsic component properties. For example, use "MyCounter" or "MY_COUNTER" instead of "myCounter".

checked

The checked property sets the checked state of the component. You can use component states when you define styles.

Use the SetState command to change the checked state on a component.

Set the inheritParentState property to true on child components to inherit the checked state of the parent.

disabled

The disabled property sets the disabled state of the component. You can use component states when you define styles.

Use the SetState command to change the disabled state on a component.

Set the inheritParentState property to true on child components to inherit the disabled state of the parent.

display

The display property of a component controls whether or not it appears on the screen and how it affects the layout calculation. Set to one of the following values:

Name Description
invisible The component is not drawn, but takes up space. The component does not respond to touch events.
none Remove the component. The component is not part of the layout and does not respond to touch.
normal Draw the component normally.

Data-binding context, ordinals, and indices used when constructing components are not affected by the display property. For example, in a container with three children, if the first child is set to display=none, it is still be data-bound with index=0 and the next child has index=1.

The following table may be useful when understanding the different ways to hide and show content:

Display Disabled Opacity Visible? Occupies Space? Focusable? Touchable? Touch & hover passes through?
normal false > 0 Yes Yes Yes Yes No
normal true > 0 Yes Yes No No No
normal false 0 No Yes Yes Yes No
normal true 0 No Yes No No No
invisible any any No Yes No No Yes
none any any No No No No Yes (but it takes no space)

The Focusable? column is for accepting keyboard focus. The Touchable? column is for responding to touch events. Note that when display is set to invisible or none, the touch events pass through the component as if it was not there and are processed by the next component down in the stacking order. The normal display components do not pass touch events through, but they only respond to touch events if they are not disabled.

The descendants of a component with display==invisible are not drawn. In other words, an invisible component will not have visible descendants. Similarly, when a component has display==none, it and all of its descendants are removed from the display hierarchy and take no space on the screen.

entity

Opaque entity data. Alexa devices pass the entity data back to the skill as context.

height and width

The properties width, height, minWidth, minHeight, maxWidth, and maxHeight are dimensional properties.

Minimum width and height values default to 0, which means the component can disappear. Maximum width and height properties default to none, which indicates that the component can scale arbitrarily. If unspecified, the width and height values will revert to the component's natural size.

id

A identifier you can define for this instance of the component. This is used to locate a particular component in the view hierarchy. Although recommended, the id is not required to be unique.

inheritParentState

Replaces the component state with the state of the parent of the component. Used for components that need to visually change appearance based on the state of the parent. For example, you may want a Text component inside of a TouchWrapper to change color when the TouchWrapper is pressed. By setting inheritParentState, the Text component changes state whenever the TouchWrapper changes state.

onMount

Commands to execute when the component is first displayed. Mount commands are used for visual transitions between screens. The event.source.value is left unset during mount.

The onMount command is triggered at document load time. Component onMount commands are always executed even if the component itself is invisible or otherwise not displayed on the screen.

The event generated has the form:

{
  "event": {
    "source": {
      "type": "nameOfComponent",
      "handler": "Mount",
      "id": "id of the component",
      "uid": "Runtime-generated unique ID of the component",
      "value": null
    }
  }
}

The event type property is set to the name of the component; for example, "Frame", "Container", "TouchWrapper", etc.

onCursorEnter

Command(s) to execute when a cursor enters the component's active region.

The event.source.value is set to the standard source value for the component see: Event source property.

Components with the Disabled state set to true do not respond to changes in cursor events, and do not execute any commands assigned to the onCursorEnter event handler. If the cursor is over a disabled component and that component is enabled, an onCursorEnter event will be generated for the component.

The event generated has the form:

"event": {
  "source": {
    "source": NAME,    // The name of the component
    "handler": "CursorEnter",
    "id": ID,          // ID of the component
    "uid": UID,        // Runtime-generated unique ID of the component
    "value": Any       // Standard source value for the component
  }
}

The event source property is set to the name of the component; for example, "Image", "TouchWrapper", "Sequence", etc.

onCursorExit

Command(s) to execute when a cursor exits the component's active region.

The event.source.value is set to the standard source value for the component see: Event source property.

Components with the Disabled state set to true do not respond to changes in cursor events, and do not execute any commands assigned to the onCursorExit event handler. If the cursor is over an enabled component and that component is disabled, an onCursorExit event will be generated for the component.

The event generated has the form:

"event": {
  "source": {
    "source": NAME,    // The name of the component
    "handler": "CursorExit",
    "id": ID,          // ID of the component
    "uid": UID,        // Runtime-generated unique ID of the component
    "value": Any       // Standard source value for the component
  }
}

The event source property is set to the name of the component; for example, "Image", "TouchWrapper", "Sequence", etc.

opacity

Applies a uniform opacity to this component and any child components. The opacity is a number in the range [0,1]; numbers outside of this range are clipped to the range. The actual displayed opacity of a component is the product of this value and all the ancestor opacity values. For example, if the current component's opacity is 0.5 and its parent opacity is 0.8, then the actual displayed opacity of the component is 0.4. Setting the opacity to 0 hides the component, but doesn't remove it from the component hierarchy.

paddingBottom, paddingLeft, paddingRight, and paddingTop

Padding values are dimensions that add space around a component. APL uses the border-box model for calculating the total width and height of an element. Default for each is 0.

shadowColor

The color of the shadow. This color normally contains some transparency. The overall opacity is also applied to the shadow color.

shadowHorizontalOffset

The horizontal drawing offset of the shadow. Positive numbers move the shadow to the right; negative numbers move it to the left.

shadowRadius

The blur radius of the shadow.

shadowVerticalOffset

The vertical drawing offset of the shadow. Positive numbers move the shadow down; negative numbers move it up.

speech

The speech data is opaque data received from the Alexa ssmlToSpeech transformer. This is opaque data used when speaking the contents of a component.

See Data Sources and Transformers for more about the ssmlToSpeech and textToSpeech transformers.

style

A named style to use to set properties on the component.

transform

The transformation array is an array of transformation values applied to the component. For example:

"transform": [ { "rotate": 30 }, { "scaleX": 1.5 }, { "translateX": 10 }]

Each individual transform is an object with a single property and associated value. Transformations are applied from right to left (following the web standard); in the above example the component is first shifted 10 dp to the right, scaled up by 50%, and then rotated about its center 30 degrees. Each element in the transformation array is one of the following:

Property Group Type Default Description
rotate Rotate Number 0.0 Rotation angle, in degrees. Positive angles rotate in the clockwise direction.
scale Scale Number 1.0 Uniform scaling in both X and Y.
scaleX Scale Number 1.0 Scaling in the X direction (overrides "scale" if in same group)
scaleY Scale Number 1.0 Scaling in the Y direction (overrides "scale" if in same group)
skewX Skew Number 1.0 Skew angle for the X-axis, in degrees. X-axis lines remain horizontal.
skewY Skew Number 1.0 Skew angle for the Y-axis, in degrees. Y-axis lines remain vertical.
translateX Move Dimension 0.0 Distance to translate the object to the right.
translateY Move Dimension 0.0 Distance to translate the object down.

Transformation properties from the same group may be gathered into a single object. For example, the following are equivalent:

[ { "scaleX": 3.0, "scaleY": 2.0} ]
[ { "scale": 3.0, "scaleY": 2.0 } ]
[ { "scaleX": 3.0 }, { "scaleY": 2.0 } ]
[ { "scale": 2.0 }, { "scaleX": 1.5 } ]

Note that transformations are cumulative. The final example scales the X-axis by 1.5, then scales both axes by 2.0, giving a final scaling of { "scaleX": 3.0, "scaleY": 2.0 }

The component scales and rotates about the center of the component.

The translation values support both absolute dimensions (such as "10px", "20dp") as well as relative dimensions (such as 30%). The relative dimensions are calculated in terms of the unscaled component width and height. For example, to rotate a component 45 degrees about its bottom-right corner:

"transform": [
  { "translateX": "50%", "translateY": "50%" }
  { "rotate": 45 },
  { "translateX": "-50%", "translateY": "-50%" }
]

type

Specifies the particular component to inflate. It can be one of the primitive components listed in this section or can be a named layout.

when

If the when expression is true, inflate the component. If false, ignore the component and all child components.

Shadow notes

Text components generate shadows that follow the text shape. All other types of components generate shadows that are rectangular boxes that surround the bounds of the component (including the padding). Component shadows are clipped to their parent container.

Component shadows are drawn in standard drawing order. That means that the shadow of a component later in the drawing order will overlap components drawn earlier. It is recommended that sufficient space be added around components to ensure that the component shadows don't overlap or get clipped unnecessarily.