ScrollToIndex Command (APL 2023.1 to 2023.2)
Scroll forward or backward through a ScrollView
, Sequence
, or GridSequence to display a particular child component.
Properties
The ScrollToIndex
command has the properties shown in the following table, in addition to the common command properties. Set the type
property to ScrollToIndex
.
In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.
Property | Type | Default | Description |
---|---|---|---|
|
|
|
The alignment of the item after scrolling. |
|
|
The parent of the child component to move into view. | |
|
Integer |
REQUIRED |
The 0-based index of the child component to display. |
For example, to scroll to show the fifth step in a recipe displayed in a
list, set index
to 4.
{
"type": "ScrollToIndex",
"componentId": "recipeSteps",
"index": 4,
"align": "center"
}
The componentId
doesn't have to be a Sequence
, ScrollView
, or GridSequence
component. The ScrollToIndex
command looks for the first Sequence
, ScrollView
, or GridSequence
at or before the componentId
and scrolls that one.
Scrolling stops if the user touches the screen. Stopping the command stops scrolling immediately.
The ScrollToIndex
command is ignored in fast mode.
align
The alignment of the item on the screen after scrolling and before speech. Alignment is an enumerated value with the following options.
Alignment | Description |
---|---|
|
The top/left side of the item is placed at the top/left side of the scrolling container. |
|
The center of the item is placed in the center of the container. |
|
The bottom/right side of the item is placed at the bottom/right side of the scrolling container. |
|
The item is moved the minimal distance necessary to bring it fully into view. |
componentId
A selector to identify the parent of the target component for the command. When not provided, defaults to :source
. The :source
selector targets the component that issued the ScrollToIndex
command.
index
The 0-based index of the child item in the parent container to scroll into view. Negative values are measured from the end of the parent container. For example, to show the second-to-last item in a list:
{
"type": "ScrollToIndex",
"index": -2,
}
The algorithm for finding the item to display can be described loosely as follows:
let itemIndex = index < 0 ? index + children.length : index;
if (itemIndex >= 0 && itemIndex < children.length) {
let child = children[itemIndex];
scrollIntoView(child);
}
ScrollToComponent and ScrollToIndex
In APL 2023.1 or later, you can use the ScrollToComponent
command with the selector syntax instead of ScrollToIndex
.
For example, the following two examples show equivalent commands. In these examples, SELECTOR
contains the ID of the scrolling component, and INDEX
contains the numerical index of the component to scroll into view.
{
"type": "ScrollToIndex",
"componentId": "SELECTOR"
"index": INDEX
}
{
"type": "ScrollToComponent",
"componentId": "SELECTOR:child(INDEX)"
}
Reinflation strategy
When the Reinflate
command runs, the ScrollToIndex
command can resume after Alexa reinflates the document. The command resumes when it runs on a sequencer
specified in the preservedSequencers
array on Reinflate
. The command saves the target scrollable component, the target index, and the alignment.
If the scrolling component isn't contained in the reinflated hierarchy, the command is ignored.
When Alexa reinflates the document, scrolling resumes and scrolls the target index into position as specified by align
.
ScrollToIndex example
The following example shows a Sequence
that displays a long list of items. The Top and Bottom buttons run ScrollToIndex
with the index
property set to 0
and -1
, respectively. The other three buttons calculate the index
based on a percentage of items in the list and use the center
option for the align
property.
Related topics
Last updated: frontmatter-missing