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 表达式值。

模板

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

凭据

根据 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>

绑定

控制是否阻止呈现以评估使用 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 规则。