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

APL Text

The Text component displays text in either a single line or multiple lines. See Alexa Design Guide–Text for guidance on using text for a good user experience in Alexa skills.

Properties

The Text component has the following properties in addition to the Component properties. See the meaning of the columns here.

Property Type Default Styled Dynamic Description
color Color depends on the theme Yes Yes The color of the text.
fontFamily String sans-serif Yes No Font family (such as "Amazon Ember Display").
fontSize Absolute Dimension 40dp Yes No The size of the text.
fontStyle normal, italic normal Yes No The font style to display.
fontWeight normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900 normal Yes No The font weight to display.
letterSpacing Absolute Dimension 0 Yes No Additional space to add between letters.
lineHeight Number (percentage) 125% Yes No Line-height multiplier.
maxLines Integer 0 Yes No The maximum number of lines of text to display. The text will be truncated with an ellipsis if not all text is visible.
text String "" No Yes The markup to display in this text box. If this value is set to null or an empty string "", no content appears.
textAlign auto, left, right, center auto Yes No Alignment of text within a paragraph.
textAlignVertical auto, top, bottom, center auto Yes No Vertical alignment of text.

Most of these properties have default values specified by the current text style. Refer to Resources for a discussion of styles.

A Text component does not scroll unless it is placed within a ScrollView.

When the Text component is the target of an event, event.target reports the following values:

"event": {
    "target": {
      "color": String,     // Text color
      "disabled": Boolean, // True if the component is disabled
      "id": ID,            // ID of the component
      "uid": UID,          // Runtime-generated unique ID of the component
      "height": Number,    // Height of the component, in dp (includes the padding)
      "opacity": Number,   // Opacity of the component [0-1]
      "text": String,      // Displayed text
      "width": Number      // Width of the component, in dp (includes the padding)
    }
}

color

The color of the text. If the theme is light, the default is #1E2222. If the theme is dark, the default is #FAFAFA.

fontFamily

Specifies the font for the text. The fontFamily property can take a single font name or a string containing a comma-separated list of font names. The APL runtime searches the list for the first named font that is installed on the device. If no valid font is found, the runtime defaults to the sans-serif font.

Font names may contain spaces. Two types of font names are supported:

  • The specific name of an installed font such as "amazon-ember", "times", "times new roman".
  • A generic name - either "serif" or "sans-serif".

Alexa devices are not guaranteed to have any specific font installed, so always end your fontFamily list with either "serif" or "sans-serif" to ensure that a valid font will be found. For example:

{
"type": "Text",
"fontFamily", "times new roman, times, georgia, serif"
}

On many Alexa devices, "sans-serif" defaults to "Amazon Ember Display" and "serif" defaults to "Bookerly". In certain Asian markets they default to "Noto Sans CJK".

Styles for fonts are available in the alexa-styles package. See Styles –FontFamily.

fontSize

The size of the font, normally expressed in dp. The default is 40dp.

fontStyle

The style of the font, either normal or italic. Defaults to normal.

fontWeight

The weight of the font. Defaults to normal. The normal and bold values are assigned at runtime. The integer values 100 through 900 correspond to progressively darker variations of the font. Most fonts don't support this many variations. For example, Amazon Ember Display has five weights (Thin, Light, Regular, Medium, Bold) which are assigned 100, 300, 500, 700, and 900 respectively.

Note that fontWeight is processed as an enumerated set, not as an integer or a string. For example, the value 750 is invalid and will not set the font to a weight between 700 and 800. When assigning a fontWeight in a resource, it is recommended that you use a string resource.

letterSpacing

Additional space to add between letters. Defaults to 0.

lineHeight

Line-height multiplier. Defaults to 125%.

The leading of the font is the fontSize multiplied by the lineHeight. For example, on a 320 dpi display with 100dp fontSize and 120% lineHeight, the font size is 200 pixels and the leading is 240 pixels. Setting the lineHeight to less than 100% can cause characters to overlap.

maxLines

The maximum number of lines of text to display. Defaults to 0, which indicates no maximum. Set to a positive integer to clip the text to the specified number of lines and insert an ellipsis to show that the text is truncated.

text

Text string to display in the text block. If set to an empty string, no text is displayed. Setting to null is equivalent to an empty string ("").

Text blocks support simple markup. Supported tags include:

Tag Description Example Display
<br> Insert a line break. Line breaks may be repeated. Line 1<br>Line 2 Line 1
Line 2
<strong>, <b> Bold a span of text. <b>Large</b> dogs are friendly. Large dogs are friendly.
<em>, <i> Italic a span of text. Read <em>Emma</em> for homework. Read Emma for homework.
<strike> Strikethrough a span of text The document is <strike>fine</strike> pretty good. The document is fine pretty good.
<u> Underline a span of text I just <u>loved</u> the chocolate! I just loved the chocolate!
<tt>, <code> Monospace a span of text.

The <code>main</code> function is the entry point.

The main function is the entry point.
<sup>, <sub> Superscript and subscript a span of text. See Gibson<sup>1<> for the H<sub>2<>O formula. See Gibson1 for the H2O formula.

Markup elements may be nested. Improperly nested markup gives undefined behavior. <b>Once upon a time <u>a small dog</b> ate a grasshopper and felt ill.</u>. The rendering of the above is undefined because the <b> and <u> elements do not nest correctly.

Markup characters in text must be replaced with character entity references.

Entity Character Description
& \& Ampersand
< < Less-than
> > Greater-than
&#nn; Any Decimal Unicode code-point. "nn" is a valid integer.
&#xnn; Hexadecimal Unicode code-point. "nn" is a valid hexadecimal number

Numeric entity references can be in decimal or hexadecimal. For example, © can be written © or ©.

textAlign

Controls the positioning of lines of text: left, center, right, auto. The default is auto, which uses the default font direction (for example, left for English).

textAlignVertical

Positions the text within the text box. Only used if the text box is taller than the text content. Defaults to top.

Sample Text

{
 "type": "Text",
 "width": "100%",
 "textAlign": "center",
 "style": "textStylePrimary2",
 "text": "<b>Hello!</b> This is your <i>Alexa</i> assistant speaking!",
 "maxLines": 2
}