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 提供了更丰富的功能集。

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

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

<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（必需）

返回将在此 <amp-render> 中渲染的 JSON 的远程端点的 URL。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 规则。