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"를 사용하세요.

요소별 속성

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