amp-bind

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

Menambahkan interaktivitas kustom dengan data binding dan ekspresi.

Ringkasan

Komponen amp-bind memungkinkan Anda untuk menambahkan interaktivitas stateful kustom ke halaman AMP melalui data binding dan ekspresi yang mirip JS.

Contoh sederhana

Pada contoh berikut, menge-tap tombol akan mengubah teks elemen <p> dari "Hello World" menjadi "Hello amp-bind".

<p [text]="'Hello ' + foo">Hello World</p>

<button on="tap:AMP.setState({foo: 'amp-bind'})">Say "Hello amp-bind"</button>

Bagaimana cara kerjanya?

amp-bind memiliki tiga komponen utama:

1. Status: Status JSON lingkup dokumen yang dapat berubah. Pada contoh di atas, status masih kosong sebelum tombol di-tap. Setelah tombol di-tap, statusnya menjadi {foo: 'amp-bind'}.
2. Ekspresi: Merupakan ekspresi mirip JavaScript yang dapat merujuk ke state. Contoh di atas memiliki ekspresi tunggal, 'Hello ' + foo, yang menggabungkan literal string 'Hello 'dan variabel status foo. Ada batas 100 operand yang dapat digunakan dalam sebuah ekspresi.
3. Binding: Merupakan atribut khusus dari bentuk [properti] yang menautkan properti elemen ke sebuah expression. Contoh di atas memiliki binding tunggal, [text], yang akan mengubah <p> teks elemen setiap kali nilai ekspresi berubah.

amp-bind memerlukan penanganan khusus untuk memastikan kecepatan, keamanan, dan performa di halaman AMP.

Contoh yang sedikit lebih rumit

<!-- Store complex nested JSON data in <amp-state> elements. -->
<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>

<!-- CSS classes can also be added or removed with [class]. -->
<p class="greenBackground" [class]="myAnimals[currentAnimal].style">
  Each animal has a different background color.
</p>

<!-- Or change an image's src with the [src] binding. -->
<amp-img width="300" height="200" src="/img/dog.jpg" [src]="myAnimals[currentAnimal].imageUrl">
</amp-img>

<p><button on="tap:AMP.setState({currentAnimal: &#39;cat&#39;})">Set to Cat</button>

Ketika tombol ditekan:

1. Status diubah dengan currentAnimal yang ditetapkan ke 'cat'.

2. Ekspresi yang bergantung pada currentAnimal dievaluasi:

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

3. Binding yang bergantung pada ekspresi yang telah diubah akan diubah:

   • Teks elemen <p> pertama akan berbunyi "This is a cat.".
   • Atribut class elemen <p> kedua akan menjadi "redBackground".
   • Elemen amp-img akan menampilkan gambar seekor kucing.

Detail

Status

Setiap dokumen AMP yang menggunakan amp-bind memiliki data JSON lingkup dokumen yang dapat diubah, atau status.

Menginisialisasi status dengan amp-state

Status amp-bind dapat diinisialisasi dengan komponen amp-state:

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

Ekspresi dapat merujuk variabel status melalui sintaks titik. Dalam contoh ini, myState.foo akan mengevaluasi "bar".

• JSON turunan elemen <amp-state> memiliki ukuran maksimal 100 KB.
• Elemen <amp-state> juga dapat menentukan URL CORS, bukan skrip JSON turunan. Lihat Apendiks untuk mengetahui detailnya.

Me-refresh status

Tindakan refresh didukung oleh komponen ini dan dapat digunakan untuk me-refresh konten status.

<amp-state id="amp-state" ...></amp-state>
<!-- Clicking the button will refresh and refetch the json in amp-state. -->
<button on="tap:amp-state.refresh"></button>

Mengubah status dengan AMP.setState()

Tindakan AMP.setState() menggabungkan literal objek ke dalam status. Misalnya, saat tombol di bawah ditekan, AMP.setState() akan menggabungkan secara mendalam literal objek dengan status.

<!-- Like JavaScript, you can reference existing
      variables in the values of the  object literal. -->
<button on="tap:AMP.setState({foo: 'bar', baz: myAmpState.someVariable})"></button>

Secara umum, objek bertingkat akan digabungkan hingga kedalaman maksimal 10. Semua variabel, termasuk yang diperkenalkan oleh amp-state, dapat diganti.

Jika dipicu oleh peristiwa tertentu, AMP.setState() juga dapat mengakses data terkait peristiwa di properti event.

<!-- The "change" event of this <input> element contains
      a "value" variable that can be referenced via "event.value". -->
  <input type="range" on="change:AMP.setState({myRangeValue: event.value})">

Mengubah histori dengan AMP.pushState()

Tindakan AMP.pushState() mirip dengan AMP.setState() kecuali tindakan ini juga mendorong entri baru ke tumpukan histori browser. Memunculkan entri histori ini (misalnya dengan menavigasi mundur) akan memulihkan nilai variabel sebelumnya yang ditetapkan oleh AMP.pushState().

Misalnya:

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

• Menge-tap tombol tersebut akan menetapkan variabel foo ke 123 dan mengirimkan entri histori baru.
• Menavigasi mundur akan memulihkan foo ke nilai sebelumnya, "bar" (setara dengan memanggil AMP.setState({foo: 'bar'}).

Ekspresi

Ekspresi mirip dengan JavaScript dengan beberapa perbedaan penting.

Perbedaan dengan JavaScript

• Ekspresi hanya dapat mengakses status dokumen penampungnya.
• Ekspresi tidak memiliki akses ke elemen global seperti window atau document.
• Hanya operator dan fungsi yang diizinkan yang dapat digunakan.
• Fungsi, class, dan loop kustom secara umum tidak diizinkan. Fungsi panah diizinkan sebagai parameter, misalnya Array.prototype.map.
• Indeks array melebihi batas dan variabel yang tidak ditentukan akan menampilkan null, bukan undefined atau memunculkan error.
• Ekspresi tunggal saat ini dibatasi 50 operand untuk menjaga performa. Harap hubungi kami jika alokasi ini tidak memadai untuk kasus penggunaan Anda.

Implementasi dan tata bahasa lengkap ekspresi dapat dilihat di bind-expr-impl.jison dan bind-expression.js.

Contoh

Berikut adalah semua ekspresi yang valid:

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

Fungsi yang diizinkan

// Returns [1, 2, 3].
[3, 2, 1].sort()

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

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

// Returns 3.
      (3.14).toFixed()

// Returns '3.14'.
      (3.14).toString()

// Returns 'abcdef'.
                      abc'.concat('def')

// Returns 1.
                          abs(-1)

// Returns ['a', 'b'].
                      keys({a: 1, b: 2})

// Returns [1, 2].
                      values({a: 1, b: 2}

// Returns 'Hello%20world'.
                                encodeURIComponent('Hello world')

¹Fungsi panah parameter tunggal tidak dapat menggunakan tanda kurung, misalnya gunakan x => x + 1 bukan (x) => x + 1. Selain itu, sort() dan splice() akan menampilkan salinan termodifikasi, bukan mengoperasikan in-place. ²Fungsi statis tidak di-namespace, misalnya gunakan abs(-1), bukan Math.abs(-1).

Menentukan makro dengan amp-bind-macro

Fragmen ekspresi amp-bind dapat digunakan kembali dengan menentukan amp-bind-macro. Elemen amp-bind-macro memungkinkan Anda menentukan ekspresi yang memerlukan nol atau lebih argumen dan merujuk ke status saat ini. Makro dapat dipanggil seperti fungsi dengan merujuk nilai atribut id-nya dari mana saja dalam dokumen Anda.

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

Makro juga dapat memanggil makro lain yang ditentukan sebelum makro itu sendiri. Makro tidak dapat memanggil dirinya sendiri secara berulang.

Binding

Binding adalah atribut khusus dari bentuk [property] yang menautkan properti sebuah elemen ke sebuah ekspresi. Sintaks alternatif yang kompatibel dengan XML juga dapat digunakan dalam bentuk data-amp-bind-property.

Ketika status berubah, ekspresi dievaluasi ulang dan properti elemen terikat akan diubah dengan hasil ekspresi baru.

amp-bind mendukung data binding di empat jenis status elemen:

Catatan tentang binding:

• Demi keamanan, binding ke innerHTML tidak diizinkan.
• Semua binding atribut dibersihkan dari nilai yang tidak aman (misalnya javascript:).
• Hasil ekspresi boolean mengalihkan atribut boolean. Misalnya: <amp-video [controls]="expr"...>. Saat expr dievaluasi ke true, elemen <amp-video> memiliki atribut controls. Saat expr dievaluasi ke false, atribut controls akan dihapus.
• Karakter tanda kurung [ dan ] dalam nama atribut dapat menyulitkan saat menulis XML (misalnya XHTML, JSX) atau menulis atribut melalui DOM API. Dalam kasus ini, gunakan sintaks alternatif data-amp-bind-x="foo", bukan [x]="foo".

Atribut khusus elemen

Hanya binding ke komponen dan atribut berikut yang diizinkan:

^*Menunjukkan atribut yang dapat diikat yang tidak memiliki pasangan yang tidak dapat diikat.

Debugging

Jalankan pengujian dalam mode pengembangan (dengan fragmen URL #development=1) untuk menandai peringatan dan error selama pengembangan dan untuk mengakses fungsi debug khusus.

Peringatan

Dalam mode pengembangan, amp-bind akan mengeluarkan peringatan saat nilai default atribut terikat tidak cocok dengan hasil awal ekspresi yang terkait. Hal ini dapat membantu mencegah mutasi tak terduga yang disebabkan oleh perubahan pada variabel status lainnya. Contoh:

<!-- The element's default class value ('def') doesn't match the expression result for [class] ('abc'),
so a warning will be issued in development mode. -->

<p class="def" [class]="abc"></p>

Dalam mode pengembangan, amp-bind juga akan mengeluarkan peringatan saat menghilangkan referensi ke properti atau variabel yang tidak ditentukan. Hal ini juga dapat membantu mencegah mutasi tak terduga akibat hasil ekspresi null. Contoh:

<amp-state id="myAmpState">
  <script type="application/json">
    { "foo": 123 }
</script>
</amp-state></p>

<!-- The amp-state#myAmpState does not have a `bar` variable, so a warning
  will be issued in development mode. -->

<p [text]="myAmpState.bar">Some placeholder text.</p>

Error

Ada beberapa jenis error runtime yang mungkin ditemui ketika bekerja dengan amp-bind.

Men-debug Status

Gunakan AMP.printState() untuk mencetak status saat ini ke konsol.

Lampiran

Spesifikasi <amp-state>

Elemen amp-state dapat berisi elemen <script> turunan ATAU atribut src yang berisi URL CORS ke endpoint JSON jarak jauh, tetapi tidak keduanya.

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

Pengelompokan XHR

AMP mengelompokkan XMLHttpRequest (XHR) ke endpoint JSON, artinya, Anda dapat menggunakan satu permintaan data JSON sebagai sumber data untuk banyak konsumen (misalnya beberapa elemen <amp-list>) di sebuah halaman AMP. Sebagai contoh, jika elemen amp-list membuat XHR ke sebuah endpoint, sementara XHR sedang dalam periode tayang, semua XHR berikutnya ke endpoint yang sama tidak akan terpicu dan sebaliknya akan menampilkan hasil dari XHR pertama.

Atribut

Penggabungan mendalam dengan AMP.setState()

Ketika AMP.setState() dipanggil, amp-bind akan menggabungkan secara mendalam literal objek yang disediakan dengan status saat ini. Semua variabel dari literal objek akan ditulis ke status secara langsung kecuali untuk objek bertingkat, yang akan digabung secara berulang. Primitive dan array dalam status akan selalu ditimpa oleh variabel dengan nama yang sama dalam literal objek.

Perhatikan contoh berikut:

{
  <!-- State is empty -->
  }

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

Saat tombol pertama ditekan, status akan berubah menjadi:

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

Saat tombol kedua ditekan, amp-bind secara berulang akan menggabungkan argumen literal objek, {employee: {age: 64}}, ke dalam status yang ada.

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

employee.age telah diubah, tetapi kunci employee.name dan employee.vehicle tidak berubah.

Perhatikan bahwa amp-bind akan memunculkan error jika Anda memanggil AMP.setState() dengan literal objek yang berisi referensi melingkar.

Menghapus variabel

Hapus variabel status yang ada dengan menetapkan nilainya ke null di AMP.setState(). Dimulai dengan status dari contoh sebelumnya, menekan:

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

akan mengubah status menjadi:

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

Demikian juga menekan:

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

akan mengubah status menjadi:

{
  <!-- State is empty -->
  }

Tata bahasa ekspresi

Tata bahasa mirip BNF untuk ekspresi amp-bind:

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