amp-render

<script async custom-element="amp-render" src="https://cdn.ampproject.org/v0/amp-render-1.0.js"></script>

用法

amp-render 组件获取 JSON 数据，然后使用模板呈现该数据。amp-render 可以使用来自 CORS JSON 端点、来自 amp-state 状态变量或来自 amp-script 的数据。

由于 amp-render 的数据可以来自 amp-script，因此您可以使用自己的 JavaScript 来过滤数据、限制其大小、创建列表功能以及自定义组件的行为和外观。如果您更喜欢使用 HTML 属性，则 amp-list 提供了更丰富的功能集。

您可以通过两种方式之一指定模板

• 一个 template 属性，它引用现有模板元素的 ID。

<template id="my-template" type="amp-mustache">
  Your personal offer: ${{price}}</template>
<amp-render template="my-template" src="https://example.com/data.json">
</amp-render>

• 一个直接嵌套在 amp-render 元素内的模板元素。

<amp-render src="https://example.com/data.json">
  <template type="amp-mustache">
    Your personal offer: ${{price}}  </template>
</amp-render>

有关模板的更多详细信息，请参阅 AMP HTML 模板。

XHR 批处理

AMP 将 XMLHttpRequests (XHR) 批量处理到 JSON 端点。这使您可以使用单个 JSON 请求作为 AMP 页面上多个元素的数据源。例如，如果您的 <amp-render> 向某个端点发出 XHR，则在 XHR 正在传输时，所有后续对同一端点的 XHR 都不会触发，而是返回来自第一个 XHR 的结果。

占位符和回退

<amp-render> 支持可选的占位符和/或回退。

• 占位符是具有 placeholder 属性的子元素。此元素会在 <amp-render> 成功加载之前显示。如果还提供了回退，则在 <amp-render> 加载失败时会隐藏占位符。
• 回退是具有 fallback 属性的子元素。如果 <amp-render> 加载失败，则会显示此元素。

在占位符和回退中了解更多信息。请注意，子元素不能同时作为占位符和回退。

<amp-render src="https://example.com/data.json">
  <div placeholder>Loading ...</div>
  <div fallback>Failed to load data.</div>
</amp-render>

刷新数据

<amp-render> 元素公开一个 refresh 操作，其他元素可以在 on="tap:..." 属性中引用该操作。

<button on="tap:my-component.refresh">Refresh</button>
<amp-render id="my-component" src="https://example.com/data.json">
  <template type="amp-mustache">
    <div>{{title}}</div>
  </template>
</amp-render>

动态调整大小

在某些情况下，我们可能需要 <amp-render> 元素在用户交互时调整大小。例如，当内容不适合使用 layout="fixed-height" 指定的 height 属性，或者指定的 height 太大而创建空白时。<amp-render 元素公开一个 resizeToContents 操作，该操作会调整高度以适合内容。请参阅以下示例

<button on="tap:my-component.resizeToContents()">Expand</button>
<amp-render
  id="my-component"
  src="https://example.com/data.json"
  layout="fixed-height"
  height="30">
    <template type="amp-mustache">
{{#cars}}        <p>{{make}} {{model}}</p>
{{/cars}}    </template>
</amp-render>

替换

<amp-render> 允许所有标准 URL 变量替换。有关更多信息，请参阅替换指南。

例如

<amp-render src="https://example.com/data.json?RANDOM"></amp-render>

可能会向类似 https://example.com/data.json?0.8390278471201 的地址发出请求，其中 RANDOM 值在每次展示时随机生成。

属性

src（必需）

远程端点的 URL，该端点返回将在此 <amp-render> 中呈现的 JSON。src 属性有三个有效的协议。

1. https：这必须引用 CORS HTTP 服务。不支持不安全的 HTTP。
2. amp-state：用于从 <amp-state> 数据进行初始化。有关更多详细信息，请参阅 amp-list 中的从 <amp-state> 初始化部分。
3. amp-script：用于使用 <amp-script> 函数作为数据源。有关更多详细信息，请参阅 amp-list 中的使用 <amp-script> 作为数据源部分。

如果存在 [src] 属性，则可以省略 src 属性。[src] 支持 URL 和非 URL 表达式值。

template

引用定义的模板元素的 ID。如果模板是 amp-render 元素的子元素，则此属性不是必需的。

credentials

定义 Fetch API 指定的 credentials 选项。

• 支持的值：omit、include
• 默认值：omit

要发送凭据，请传递 include 的值。如果设置了此值，则响应必须遵循 AMP CORS 安全指南。

下面的示例在 credentials 中使用“include”值来显示个性化内容

<amp-render
  credentials="include"
  src="<%host%>/json/product.json?clientId=CLIENT_ID(myCookieId)"
>
  <template type="amp-mustache">
    Your personal offer: ${{price}}  </template>
</amp-render>

xssi-prefix

导致 <amp-render> 在解析之前从提取的 JSON 中去除前缀。这对于包含类似 )]} 的 安全前缀 的 API 非常有用，以帮助防止跨站点脚本攻击。

例如，假设我们有一个 API 返回此响应

)]}{ "items": ["value"] }

我们可以指示 amp-render 删除安全前缀，如下所示

<amp-render xssi-prefix=")]}" src="https://example.com/data.json"></amp-render>

key

定义表达式以查找要在响应中呈现的子对象。例如，假设我们有一个 API 返回此响应

{
  "automobiles": {
    "cars": {
      "german": {
        "make": "BMW",
        "model": "M3"
      },
      "american": {
        "make": "Tesla",
        "model": "Model X"
      }
    }
  }
}

如果我们只想显示响应中的德国汽车，我们可以使用 key 属性。

<amp-render src="https://example.com/data.json" key="automobiles.cars.german">
  <template type="amp-mustache">
{{make}} {{model}}  </template>
</amp-render>

binding

控制是否阻止渲染以评估同时使用 amp-render 和 amp-bind 的页面中子元素中的绑定（例如 [text]）。

• binding="never" 或 binding="no"：永不阻止渲染 （最快）。
• binding="refresh" （默认）：不在初始加载时阻止渲染 （更快）。
• binding="always"：始终阻止渲染 （慢）。

本质上，binding="always" 是 binding="refresh"，它还会在 amp-render 的初始加载时阻止渲染以评估绑定。

常用属性

此元素包括扩展到 AMP 组件的常用属性。

无障碍

对于没有 aria-live 属性的 amp-render 实例，将添加 aria-live="polite"，以便屏幕阅读器会播报内容的任何更改。要覆盖添加 aria-live="polite"，请添加 aria-live="off"。

验证

请参阅 AMP 验证器规范中的amp-render 规则。