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-前缀

导致 <amp-render> 在解析之前从获取的 JSON 中删除前缀。这对于包含 安全前缀（如 )]}）的 API 很有用，有助于防止跨站点脚本攻击。

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

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

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

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

键

定义用于查找要在响应中呈现的子对象的表达式。例如，假设我们有一个返回此响应的 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 规则。