amp-bind

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

通过数据绑定和表达式添加自定义互动方式。

概述

借助 amp-bind 组件，您可以通过数据绑定以及类似于 JS 的表达式，为 AMP 网页添加自定义的有状态互动方式。

一个简单示例

在下面的示例中，点按相应按钮可将 <p> 元素的文本从“Hello World”更改为“Hello amp-bind”。

<p [text]="'Hello ' + foo">Hello World</p> <button on="tap:AMP.setState({foo: 'amp-bind'})">Say "Hello amp-bind"</button> 

运作方式

amp-bind 包含三个主要组件：

1. 状态：涵盖整个文档的可变 JSON 状态。在上面的示例中，在点按相应按钮之前，状态为空。在点按相应按钮之后，状态为 {foo: 'amp-bind'}。
2. 表达式：类似于 JavaScript 的表达式，可引用状态。上面的示例中包含单个表达式，即 'Hello ' + foo，该表达式用于将字符串字面量 'Hello ' 和状态变量 foo 连接在一起。一个表达式中最多可以使用 100 个操作数。
3. 绑定：一些采用 [property] 形式的特殊属性，用于将元素的属性关联到表达式。上面的示例中包含单个绑定，即 [text]，该绑定用于在表达式的值每次发生更改时更新 <p> 元素的文本。

amp-bind 会特别注意确保在 AMP 网页上实现出色的速度、安全性和性能。

一个稍微复杂的示例

<!-- 将复杂的嵌套 JSON 数据存储在 <amp-state> 元素中。--> <amp-state id="myAnimals"> <script type="application/json"> { "dog": { "imageUrl": "/img/dog.jpg", "style": "greenBackground" }, "cat": { "imageUrl": "/img/cat.jpg", "style": "redBackground" } } </script> </amp-state> <p [text]="'This is a ' + currentAnimal + '.'">This is a dog.</p> <!-- 也可以使用 [class] 添加或移除 CSS 类。 --> <p class="greenBackground" [class]="myAnimals[currentAnimal].style"> Each animal has a different background color. </p> <!-- 或通过 [src] 绑定更改图片的 src。--> <amp-img width="300" height="200" src="/img/dog.jpg" [src]="myAnimals[currentAnimal].imageUrl"> </amp-img> <button on="tap:AMP.setState({currentAnimal: 'cat'})">Set to Cat</button> 

按下相应按钮后：

1. 系统会根据定义为 'cat' 的 currentAnimal 对状态进行更新。

2. 系统会对依赖于 currentAnimal 的表达式进行求值：

   • 'This is a ' + currentAnimal + '.' => 'This is a cat.'
   • myAnimals[currentAnimal].style => 'redBackground'
   • myAnimals[currentAnimal].imageUrl => /img/cat.jpg

3. 系统会对依赖于更改后的表达式的绑定进行更新：

   • 第一个 <p> 元素的文本将显示为“This is a cat.”
   • 第二个 <p> 元素的 class 属性将为“redBackground”。
   • amp-img 元素将显示一只猫的图片。

详细说明

状态

每个使用 amp-bind 的 AMP 文档都包含涵盖整个文档的可变 JSON 数据（即状态）。

通过 amp-state 对状态进行初始化

可通过 amp-state 组件对 amp-bind 的状态进行初始化：

<amp-state id="myState"> <script type="application/json"> { "foo": "bar" } </script> </amp-state> 

表达式可通过点语法引用状态变量。在此示例中，myState.foo 的求解结果为 "bar"。

• <amp-state> 元素的子级 JSON 不能超过 100KB。
• <amp-state> 元素还可以指定 CORS 网址，而不是子级 JSON 脚本。有关详情，请参阅附录。

刷新状态

此组件支持 refresh 操作，该操作可用于刷新状态内容。

<amp-state id="amp-state" ...></amp-state> <!-- 点击该按钮将刷新并重新获取 amp-state 中的 json。 --> <button on="tap:amp-state.refresh"></button> 

通过 AMP.setState() 更新状态

AMP.setState() 操作可将对象字面量合并到状态中。例如，当用户按下方的按钮后，AMP.setState() 会将对象字面量与状态进行深度合并。

<!-- 与 JavaScript 类似，您可以在  对象字面量的值中引用现有变量。 --> <button on="tap:AMP.setState({foo: 'bar', baz: myAmpState.someVariable})"></button> 

一般来说，嵌套对象的合并深度上限为 10。所有变量（包括由 amp-state 引入的变量）都可以被覆盖。

被特定事件触发后，AMP.setState() 还可以访问 event 属性的事件相关数据。

<!-- 此 <input> 元素的“change”事件包含  可通过“event.value”引用的“value”变量。 --> <input type="range" on="change:AMP.setState({myRangeValue: event.value})"> 

通过 AMP.pushState() 修改历史记录

AMP.pushState() 操作与 AMP.setState() 类似，只不过它还会将新条目推送到浏览记录堆栈。弹出此浏览记录条目（例如，通过执行返回操作）将会恢复由 AMP.pushState() 设置的变量的上一个值。

例如：

<button on="tap:AMP.pushState({foo: '123'})">Set 'foo' to 123</button> 

• 点按相应按钮会将变量 foo 设为 123，并推送新的历史记录条目。
• 执行返回操作会将 foo 恢复到之前的值“bar”（相当于调用 AMP.setState({foo: 'bar'})）。

表达式

表达式与 JavaScript 类似，但两者存在一些重要区别。

与 JavaScript 的区别

• 表达式只能访问所在文档的状态。
• 表达式无权访问 window 或 document 等全局属性。
• 只能使用列入白名单的函数和运算符。
• 一般不允许使用自定义函数、类和循环。允许将箭头函数用作参数，如 Array.prototype.map。
• 未定义的变量和 array-index-out-of-bound 会返回 null，而不是 undefined，也不会引发错误。
• 为了确保性能，单个表达式中目前最多可以使用 50 个操作数。如果这无法满足您的使用需求，请与我们联系。

如需查看完整的表达式语法和实现，请参阅 bind-expr-impl.jison 和 bind-expression.js。

示例

以下都是有效的表达式：

1 + '1' // 11 1 + (+'1') // 2 !0 // true null || 'default' // 'default' 

列入白名单的函数

// 返回 [1, 2, 3]。 [3, 2, 1].sort()

// 返回 [1, 3, 5]。 [1, 2, 3].map((x, i) => x + i)

// 返回 6。 [1, 2, 3].reduce((x, y) => x + y)

// 返回 3。 (3.14).toFixed()

// 返回“3.14”。 (3.14).toString()

// 返回“abcdef”。 abc'.concat('def')

// 返回 1。 abs(-1)

// 返回 ['a', 'b']。 keys({a: 1, b: 2})

// 返回 [1, 2]。 values({a: 1, b: 2}

// 返回 'Hello%20world'。 encodeURIComponent('Hello world')

¹包含单个参数的箭头函数不能包含英文括号，例如，应使用 x => x + 1，而不是 (x) =>; x + 1。此外，sort() 和 splice() 会返回修改后的副本，而不是原地操作。

²静态函数没有命名空间，例如，应使用 abs(-1)，而不是 Math.abs(-1)。

通过 amp-bind-macro 定义宏

您可以通过定义 amp-bind-macro 重复使用 amp-bind 表达式片段。借助 amp-bind-macro 元素，您可以定义一个采用零个或多个参数并引用当前状态的表达式。您可以像调用函数一样调用宏，只需从文档中的任意位置引用宏的 id 属性值即可。

<amp-bind-macro id="circleArea" arguments="radius" expression="3.14 * radius * radius"></amp-bind-macro> <div> The circle has an area of <span [text]="circleArea(myCircle.radius)">0</span>. </div> 

宏还可以调用在其之前定义的其他宏，但无法以递归方式调用自身。

绑定

绑定 是一种采用 [property] 形式的特殊属性，用于将元素的属性关联到表达式。您还可以通过 data-amp-bind-property 形式使用另一种与 XML 兼容的语法。

当状态发生变化时，系统会对表达式重新求值，并根据新的表达式结果更新绑定元素的属性。

amp-bind 支持对以下四种元素状态进行数据绑定：

关于绑定的注意事项：

• 为了安全起见，不允许绑定到 innerHTML。
• 对于不安全的值（如 javascript:），系统会对所有属性绑定进行净化处理。
• 系统会根据布尔表达式的结果切换布尔值属性。例如：<amp-video [controls]="expr"...>。当 expr 的求解结果为 true 时，<amp-video> 元素具有 controls 属性。当 expr 的求解结果为 false 时，系统会移除 controls 属性。
• 编写 XML（如 XHTML、JSX）或通过 DOM API 编写属性时，属性名称中的括号字符 [ 和 ] 可能会带来问题。在这些情况下，请使用替代语法 data-amp-bind-x="foo"，而不是 [x]="foo"。

特定于元素的属性

仅允许绑定到以下组件和属性：

<sup>*</sup>表示可绑定的属性，而且没有不可绑定的对应项。 

调试

在开发模式下进行测试（使用网址片段 #development=1），以便在开发过程中发现警告和错误，并可以使用特殊的调试函数。

警告

在开发模式下，如果绑定属性的默认值与相应表达式的初始结果不一致，amp-bind 会发出警告。这有助于防止出现因其他状态变量发生变化而导致的意外变化。例如：

<!-- 该元素的默认类值 ('def') 与 [class] ('abc') 的表达式结果不一致，因此在开发模式下将发出警告。--> <p class="def" [class]="'abc'"></p> 

在开发模式下，当解除对未定义变量或属性的引用时，amp-bind 也会发出警告。这同样有助于防止出现因 null 表达式结果而导致的意外变化。例如：

<amp-state id="myAmpState"> <script type="application/json"> { "foo": 123 } </script> </amp-state></p> <!-- amp-state#myAmpState 没有 `bar` 变量，因此在开发模式下将发出警告。--> <p [text]="myAmpState.bar">Some placeholder text.</p> 

错误

使用 amp-bind 时，可能会遇到以下几种运行时错误。

调试状态

利用 AMP.printState() 将当前状态输出到控制台。

附录

<amp-state> 规范

amp-state 元素可以包含子级 <script> 元素，也可以 包含 src 属性（其中包含指向远程 JSON 端点的 CORS 网址），但不能同时包含这两者。

<amp-state id="myLocalState"> <script type="application/json"> { "foo": "bar" } </script> </amp-state> <amp-state id="myRemoteState" src="https://data.com/articles.json"> </amp-state> 

XHR 批处理

AMP 会对向 JSON 端点发出的 XMLHttpRequest (XHR) 进行批处理，也就是说，您可以在 AMP 网页上将单个 JSON 数据请求用作多个使用方（如多个 amp-state 元素）的数据源。例如，如果您的 amp-state 元素向某个端点发出 XHR，那么在该 XHR 传输期间，向同一端点发送的所有后续 XHR 都不会触发，系统将只返回第一个 XHR 的结果。

属性

通过 AMP.setState() 进行深度合并

调用 AMP.setState() 时，amp-bind 会将所提供的对象字面量与当前状态进行深度合并。除了以递归方式合并的嵌套对象之外，对象字面量的所有变量都会直接写入到状态。状态中的基元和数组始终会被对象字面量中的同名变量覆盖。

请参考以下示例：

{ <!-- 状态为空 --> } 

<button on="tap:AMP.setState({employee: {name: 'John Smith', age: 47, vehicle: 'Car'}})"...></button> <button on="tap:AMP.setState({employee: {age: 64}})"...></button> 

按下第一个按钮后，状态会更改为：

{ employee: { name: 'John Smith', age: 47, vehicle: 'Car', } } 

按下第二个按钮后，amp-bind 会以递归方式将对象字面量参数 {employee: {age: 64}} 合并到现有状态。

{ employee: { name: 'John Smith', age: 64, vehicle: 'Car', } } 

employee.age 已更新，但 employee.name 和 employee.vehicle 键未发生变化。

请注意，如果通过包含循环引用的对象字面量调用 AMP.setState()，amp-bind 会抛出错误。

移除变量

在 AMP.setState() 中将现有状态变量的值设为 null 可移除该变量。从上一个示例中的状态开始，按下：

<button on="tap:AMP.setState({employee: {vehicle: null}})"...></button> 

会将状态更改为：

{ employee: { name: 'John Smith', age: 48, } } 

同样，按下：

<button on="tap:AMP.setState({employee: null})"...></button> 

会将状态更改为：

{ <!-- 状态为空 --> } 

表达式语法

amp-bind 表达式的语法，与 BNF 语法类似：

expr: operation | invocation | member_access | '(' expr ')' | variable | literal operation: '!' expr | '-' expr | '+' expr | expr '+' expr | expr '-' expr | expr '*' expr | expr '/' expr | expr '%' expr | expr '&&' expr | expr '||' expr | expr '<=' expr | expr '<' expr | expr '>=' expr | expr '>' expr | expr '!=' expr | expr '==' expr | expr '?' expr ':' expr invocation: expr '.' NAME args args: '(' ')' | '(' array ')' ; member_access: expr member ; member: '.' NAME | '[' expr ']' variable: NAME ; literal: STRING | NUMBER | TRUE | FALSE | NULL | object_literal | array_literal array_literal: '[' ']' | '[' array ']' array: expr | array ',' expr object_literal: '{' '}' | '{' object '}' object: key_value | object ',' key_value key_value: expr ':' expr