amp-bind

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

데이터 결합 및 식과 함께 맞춤형 상호작용을 추가합니다.

개요

amp-bind 구성요소를 사용하면 데이터 결합 및 JS와 유사한 식을 통해 AMP 페이지에 맞춤형 스테이트풀(stateful) 상호작용을 추가할 수 있습니다.

간단한 예

이 예에서는 버튼을 누르면 <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. 식: 상태 를 참조할 수 있는 자바스크립트 같은 식입니다. 위의 예에는 단일 식인 '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 + '.'">이것은 개입니다.</p>
<!-- [class]를 사용하여 CSS 클래스를 추가 또는 제거할 수도 있습니다. -->
<p class="greenBackground" [class]="myAnimals[currentAnimal].style">
  각 동물의 배경색이 다릅니다.
</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')">'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-bind의 상태는 amp-state 구성요소로 초기화할 수 있습니다.

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

식은 도트 구문을 통해 상태 변수를 참조할 수 있습니다. 이 예에서 myState.foo는 "bar"로 평가됩니다.

• <amp-state> 요소의 하위 JSON은 최대 크기가 100KB입니다.
• <amp-state> 요소는 하위 JSON 스크립트 대신 CORS URL을 지정할 수도 있습니다. 자세한 내용은 부록을 참조하세요.

상태 새로 고침

refresh 작업은 이 구성요소에서 지원되며 상태의 내용을 새로 고치는 데 사용할 수 있습니다.

<amp-state id="amp-state" ...></amp-state>
<!-- 버튼을 클릭하면 amp-state의 json에 대한 새로고침 및 다시 가져오기가 수행됩니다. -->
<button on="tap:amp-state.refresh"></button>

AMP.setState()로 상태 업데이트

AMP.setState() 작업은 개체 리터럴을 상태로 병합합니다. 예를 들어, 아래의 버튼을 누르면 AMP.setState()는 개체 리터럴을 상태와 심층 병합합니다.

<!-- 자바스크립트와 마찬가지로 개체 리터럴
      값에서 기존 변수를 참조할 수 있습니다. -->
 <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()`로 기록 수정 <a name="modifying-history-with-amppushstate"></a>

브라우저 기록 스택에 새 항목을 푸시한다는 점을 제외하면 [`AMP.pushState()`](../../../documentation/guides-and-tutorials/learn/amp-actions-and-events.md#target-amp) 작업은 `AMP.setState()`와 유사합니다. 이 기록 항목을 표시하면(예: 뒤로 이동) `AMP.pushState()`에 의해 설정된 변수의 이전 값이 복원됩니다.

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

• 버튼을 누르면 변수 foo가 123으로 설정되고 새로운 기록 항목이 푸시됩니다.
• 뒤로 이동하면 foo가 이전 값인 'bar'로 복원됩니다(AMP.setState({foo: 'bar'} 호출과 동일).

식

식은 자바스크립트와 비슷하지만 몇 가지 중요한 차이점이 있습니다.

자바스크립트와의 차이점

• 식은 포함 문서의 상태에만 액세스할 수 있습니다.
• 식은 window 또는 document와 같은 전역에 액세스하지 않습니다.
• 화이트리스트에 있는 함수 및 연산자만 사용할 수 있습니다.
• 맞춤형 함수, 클래스 및 루프는 일반적으로 허용되지 않습니다. 화살표 함수는 매개변수로서 허용됩니다(예: Array.prototype.map).
• 정의되지 않은 변수 및 범위를 벗어난 배열-색인은 undefined 대신 null을 반환하거나 오류를 일으킵니다.
• 성능을 위해 현재 단일 식의 피연산자는 50개로 제한됩니다. 이 개수가 사용 사례로 불충분한 경우 Google에 문의하세요.

식 문법과 구현의 전체 내용은 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()는 제자리에서 연산되는 대신 수정된 사본을 반환합니다.

²상태 함수에는 네임스페이스가 없습니다. 예를 들어 Math.abs(-1) 대신 abs(-1)을 사용하세요.

amp-bind-macro로 매크로 정의

amp-bind-macro를 정의하면 amp-bind 식의 부분들을 재사용할 수 있습니다. amp-bind-macro 요소를 사용하면 0개 이상의 인수를 사용하고 현재 상태를 참조하는 식을 정의할 수 있습니다. 문서의 어디서나 id 속성 값을 참조하여 매크로를 함수처럼 호출할 수 있습니다.

<amp-bind-macro id="circleArea" arguments="radius" expression="3.14 * radius * radius"></amp-bind-macro>

<div>
  원의 면적은 <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를 통해 속성을 작성할 때 문제가 될 수 있습니다. 이 경우 [x]="foo" 대신 대체 구문 data-amp-bind-x="foo"를 사용하세요.

요소별 속성

다음 구성요소 및 속성에 대한 결합만 허용됩니다.

^*결합할 수 없는 대상이 없는 결합 가능한 속성을 나타냅니다.

디버깅

개발 중 경고 및 오류를 강조 표시하고 특수 디버깅 기능에 액세스하려면 개발 모드(URL에 #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">일부 자리표시자 텍스트.</p>

오류

amp-bind로 작업할 때 발생할 수 있는 몇 가지 유형의 런타임 오류가 있습니다.

디버깅 상태

현재 상태를 콘솔에 인쇄하려면 AMP.printState()를 사용합니다.

부록

<amp-state> 사양

amp-state에는 하위 <script> 요소 또는 원격 JSON 엔드포인트에 대한 CORS URL을 포함하는 src 속성을 포함할 수 있지만, 둘을 모두 포함할 수는 없습니다.

<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 페이지에서 여러 소비자(예: 여러 amp-state 요소)에 대해 데이터 소스로 단일 JSON 데이터 요청을 사용할 수 있습니다. 예를 들어 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