amp-list
Description
Dynamically downloads data and creates list items using a template.
Required Scripts
<script async custom-element="amp-list" src="https://cdn.ampproject.org/v0/amp-list-1.0.js"></script>
Supported Layouts
Usage
The amp-list
component fetches dynamic content from a CORS JSON endpoint.
The response from the endpoint contains data, which is rendered in the specified
template.
You can specify a template in one of two ways:
- a
template
attribute that references an ID of an existing templating element. - a templating element nested directly inside the
amp-list
element.
<amp-list>
in tandem with another templating AMP component, such as <amp-form>
, note that templates may not nest in valid AMP documents. In this case a valid workaround is to provide the template by id
via the template
attribute. Learn more about nested templates in <amp-mustache>
. For more details on templates, see AMP HTML Templates.
Displaying a dynamic list
In the following example, we retrieve JSON data that contains URLs and titles, and render the content in a nested amp-mustache template.
<amp-list width="auto" height="100" layout="fixed-height" src="/static/inline-examples/data/amp-list-urls.json" > <template type="amp-mustache"> <div class="url-entry"> <a href="{{url}}">{{title}}</a> </div> </template> </amp-list>
Here is the JSON file that we used:
{ "items": [ { "title": "AMP YouTube Channel", "url": "https://www.youtube.com/channel/UCXPBsjgKKG2HqsKBhWA4uQw" }, { "title": "AMPproject.org", "url": "https://www.ampproject.org/" }, { "title": "AMP", "url": "https://amp.dev/" }, { "title": "AMP Start", "url": "https://ampstart.com/" } ] }
Here is how we styled the content fetched:
amp-list div[role='list'] { display: grid; grid-gap: 0.5em; }
The request is always made from the client, even if the document was served from the AMP Cache. Loading is triggered using normal AMP rules depending on how far the element is from the current viewport.
If <amp-list>
needs more space after loading, it requests the AMP runtime to update its height using the normal AMP flow. If the AMP runtime cannot satisfy the request for the new height, it will display the overflow
element when available. Notice however, that the typical placement of <amp-list>
elements at the bottom of the document almost always guarantees that the AMP runtime can resize them.
Accessibility considerations for amp-list
By default, <amp-list>
adds a list
ARIA role to the list element and a listitem
role to item elements rendered via the template. If the list element or any of its children are not "tabbable" (accessible by keyboard keys such as the a
and button
elements or any elements with a positive tabindex
), a tabindex
of 0
will be added by default to the list item. This behaviour is arguably not always appropriate - generally, only interactive controls/content should be focusable. If you want to suppress this behaviour, make sure to include tabindex="-1"
as part of the outermost element of your template.
aria-live="polite"
), meaning that any change to the content of the list results in the entire list being read out/announced by assistive technologies (such as screen readers). Due to the way lists are initially rendered, this can also result in lists being announced in their entirety when a page is loaded. To work around this issue for now, you can add aria-live="off"
to <amp-list>
, which will override the addition of aria-live="polite"
.
<template type="amp-mustache"> <div class="item">{{item}}</div> <div class="price">{{price}}</div> </template>
Would most predictably be applied and rendered if instead provided as follows:
<template type="amp-mustache"> <div> <div class="item">{{item}}</div> <div class="price">{{price}}</div> </div> </template>
XHR batching
AMP batches XMLHttpRequests (XHRs) to JSON endpoints, that is, you can use a single JSON data request as a data source for multiple consumers (e.g., multiple <amp-list>
elements) on an AMP page. For example, if your <amp-list>
makes an XHR to an endpoint, while the XHR is in flight, all subsequent XHRs to the same endpoint won't trigger and will instead return the results from the first XHR.
In <amp-list>
, you can use the items
attribute to render a subset of the JSON response, allowing you to have multiple <amp-list>
elements rendering different content but sharing a single XHR.
Specifying an overflow
Optionally, the <amp-list>
component can contain an element with the overflow
attribute. AMP will display this element if all of the following conditions are met:
- The contents rendered into the
amp-list
exceed its specified size. - The bottom of
amp-list
is within the viewport. - The bottom of
amp-list
is not near the bottom of the page (defined as the minimum of either the bottom 15% of the document or the bottom 1000px)
If amp-list
is outside the viewport, it will be automatically expanded.
Example: Displaying an overflow when the list needs more space
In the following example, we display a list of images and titles. Because the <amp-list>
content requires more space than available, the AMP framework displays the overflow element.
<amp-list width="auto" height="140" layout="fixed-height" src="/static/inline-examples/data/amp-list-data.json" > <template type="amp-mustache"> <div class="image-entry"> <amp-img src="{{imageUrl}}" width="100" height="75"></amp-img> <span class="image-title">{{title}}</span> </div> </template> <div overflow class="list-overflow" style="background-color:red;"> See more </div> </amp-list>
AMP applies the following CSS to elements with the overflow
attribute:
.list-overflow[overflow] { position: absolute; bottom: 0; left: 0; right: 0; }
Placeholder and fallback
Optionally, <amp-list>
supports a placeholder and/or fallback.
- A placeholder is a child element with the
placeholder
attribute. This element is shown until the<amp-list>
loads successfully. If a fallback is also provided, the placeholder is hidden when the<amp-list>
fails to load. - A fallback is a child element with the
fallback
attribute. This element is shown if the<amp-list>
fails to load.
Learn more in Placeholders & Fallbacks. Note that a child element cannot be both a placeholder and a fallback.
<amp-list src="https://foo.com/list.json"> <div placeholder>Loading ...</div> <div fallback>Failed to load data.</div> </amp-list>
Refreshing data
The <amp-list>
element exposes a refresh
action that other elements can reference in on="tap:..."
attributes.
<button on="tap:myList.refresh">Refresh List</button> <amp-list id="myList" src="https://foo.com/list.json"> <template type="amp-mustache"> <div>{{title}}</div> </template> </amp-list>
Dynamic resizing
In several cases, we may need the <amp-list>
to resize on user interaction. For example, when the <amp-list>
contains an amp-accordion that a user may tap on, when the contents of the <amp-list>
change size due to bound CSS classes. The changeToLayoutContainer
action handles this by changing the amp list to layout="CONTAINER"
when triggering this action. See the following example:
<button on="tap:list.changeToLayoutContainer()">Show Grid</button> <amp-list id="list" width="396" height="80" layout="responsive" src="/test/manual/amp-list-data.json?RANDOM" > <template type="amp-mustache"> {{title}} </template> </amp-list>
Attributes
src
(required)
The URL of the remote endpoint that returns the JSON for amp-list to render. This must refer to a CORS HTTP service and Insecure HTTP is not supported.
If fetching the data at the src
URL fails, the <amp-list>
triggers a low-trust fetch-error
event.
items
Defines the expression to locate the array to be rendered within the response. This is a dot-notated expression that navigates via fields of the JSON response.
By defaut <amp-list>
expects an array, the single-item
attribute may be used to load data from an object.
- The default value is
"items"
. The expected response:{items: [...]}
. - If the response itself is the desired array, use the value of
"."
. The expected response is:[...]
. - Nested navigation is permitted (e.g.,
"field1.field2"
). The expected response is:{field1: {field2: [...]}}
.
When items="items"
is specified (which, is the default) the response must be a JSON object that contains an array property called "items"
:
{ "items": [...] }
max-items
An integer value specifying the maximum length of the items array to be rendered.
The items
array will be truncated to max-items
entries if the returned value exceeds max-items
.
single-item
Causes <amp-list>
to treat the returned result as if it were a single element array. An object response will be wrapped in an array so
{items: {...}}
will behave as if it were {items: [{...}]}
.
binding
For pages using <amp-list>
that also use amp-bind
, controls whether or not to block render on the evaluation of bindings (e.g. [text]
) in rendered children.
We recommend using binding="no"
or binding="refresh"
for faster performance.
binding="no"
: Never block render (fastest).binding="refresh"
: Don't block render on initial load (faster).binding="always"
: Always block render (slow).
If binding
attribute is not provided, default is always
.
Common attributes
This element includes common attributes extended to AMP components.
Invalid AMP email attributes
The AMP for Email spec disallows the use of the following attributes on the AMP email format.
[src]
[state]
[is-layout-container]
auto-resize
credentials
data-amp-bind-src
load-more
load-more-bookmark
reset-on-refresh
xssi-prefix
Validation
See amp-list rules in the AMP validator specification.
Você já leu este documento várias vezes, mas ainda ficou com dúvidas sem respostas? Talvez outras pessoas pensem da mesma forma. Procure entrar em contato com elas no Stack Overflow.
Ir para o Stack Overflow Encontrou um bug ou sente falta de um recurso?O projeto AMP incentiva fortemente sua participação e contribuições! Esperamos que você se torne um participante assíduo de nossa comunidade de código aberto, mas também agradecemos contribuições pontuais para problemas que você tenha particular interesse.
Ir para o GitHub