amp-bind

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

Veri bağlama ve ifadelerle özel etkileşim özelliği ekler.

Genel Bakış

amp-bind bileşeni, veri bağlama ve JS benzeri ifadeler aracılığıyla AMP sayfalarınıza özel durum bilgili etkileşim özelliği eklemenize olanak tanır.

Basit bir örnek

Aşağıdaki örnekte düğmeye dokunduğunuzda, <p> öğesinin "Hello World" olan metni "Hello amp-bind" olarak değişir.

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

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

İşleyiş şekli

amp-bind üç ana bileşene sahiptir:

1. State: Bir dokümanın kapsamı, değişebilir JSON durumu. Yukarıdaki örnekte, düğmeye dokunmadan önce durum boştur. Düğmeye dokunulduktan sonra, durum {foo: 'amp-bind'} olur.
2. Expressions: Bunlar, state başvurusunda bulunabilen JavaScript benzeri ifadelerdir. Yukarıdaki örnekte, dize değişmez değerini ('Hello ') ve durum değişkenini (foo) birbirine bağlayan tek bir 'Hello ' + foo ifadesi bulunmaktadır. Bir ifade içinde 100 işlenen kullanma sınırı vardır.
3. Bindings: Bunlar, bir öğenin özelliğini bir expression öğesine bağlayan [property] formunun özel özellikleridir. Yukarıdaki örnekte, <p> öğesinin metnini ifade değeri her değiştiğinde güncelleyen tek bir bağlama ([text]) bulunmaktadır.

amp-bind, AMP sayfalarında hız, güvenlik ve performansı sağlamaya özel önem verir.

Biraz daha karmaşık bir örnek

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

<button on="tap:AMP.setState({currentAnimal: 'cat'})">Set to Cat</button>

Düğmeye basıldığında:

1. Durum, 'cat' olarak tanımlanan currentAnimal ile güncellenir.

2. currentAnimal öğesine bağlı ifadeler değerlendirilir:

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

3. Değiştirilen ifadelere bağlı olan bağlamalar güncellenir:

   • İlk <p> öğesinin metni, "This is a cat" olur.
   • İkinci <p> öğesinin class özelliği "redBackground" olur.
   • amp-img öğesi bir kedinin resmini gösterir.

Ayrıntılar

Durum

amp-bind kullanan her AMP dokümanı, doküman kapsamı değişebilir JSON verilerine veya durum bilgisine sahiptir.

amp-state ile başlangıç durumu

amp-bind durumu, amp-state bileşeni ile başlatılabilir:

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

İfadeler, durum değişkenlerine nokta söz dizimi aracılığıyla başvurabilir. Bu örnekte, myState.foo, "bar" olarak değerlendirilir.

• Bir <amp-state> öğesinin alt JSON'ı en fazla 100 KB olur.
• Bir <amp-state> öğesi, alt JSON komut dosyası yerine bir CORS URL'si de belirtebilir. Ayrıntılar için Ek bölümüne bakın.

Durumu yenileme

refresh işlemi bu bileşen tarafından desteklenir ve durum içeriğini yenilemek için kullanılabilir.

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

Durumu AMP.setState() ile güncelleme

AMP.setState() işlemi, bir nesne değişmez değerini durumla birleştirir. Örneğin, aşağıdaki düğmeye basıldığında AMP.setState() öğesi, nesne değişmez değerini durum ile derinden birleştirir.

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

Genel olarak, iç içe yerleştirilmiş nesneler en fazla 10 derinlikte birleştirilir. amp-state tarafından sunulanlar da dahil olmak üzere tüm değişkenler geçersiz kılınabilir.

Belirli etkinlikler tarafından tetiklendiğinde, AMP.setState(), event özelliğindeki etkinlikle ilgili verilere de erişebilir.

<!-- 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})">

AMP.pushState() ile geçmişi değiştirme

AMP.pushState() işlemi, tarayıcı geçmiş yığınına yeni bir giriş de aktarması haricinde AMP.setState() işlemine benzer. Bu geçmiş girişine dönülmesi (geri gidilerek), AMP.pushState() tarafından ayarlanan değişkenlerin önceki değerini geri yükler.

Örneğin:

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

• Düğmeye dokunulduğunda foo değeri 123 olarak ayarlanır ve yeni bir geçmiş girişi aktarılır.
• Geri gidildiğinde foo önceki değeri olan "bar" değerine geri yüklenir (AMP.setState({foo: 'bar'}) işleminin çağrılmasıyla eşdeğerdir).

İfadeler

İfadeler, bazı önemli farklılıklarla birlikte JavaScript'e benzer.

JavaScript'ten farklılıklar

• İfadeler yalnızca ifadeleri içeren dokümanın durumuna erişebilir.
• İfadeler, window veya document gibi genel öğelere erişmez.
• Yalnızca beyaz listedeki işlevler ve operatörler kullanılabilir.
• Özel işlevlere, sınıflara ve döngülere genellikle izin verilmez. Ok işlevlerine parametre olarak izin verilir; ör. Array.prototype.map.
• Tanımlanmamış değişkenler ve sınırların dışındaki dizi dizini undefined değeri döndürmek veya hata bildirmek yerine null değerini döndürür.
• Performans açısından şu anda tek bir ifade 50 öğe ile sınırlanmıştır. Sizin kullanım alanınız için bu sayı yeterli değilse lütfen bize ulaşın.

Tam ifade dil bilgisi ve uygulaması, bind-expr-impl.jison ve bind-expression.js içinde bulunabilir.

Örnekler

Aşağıdaki ifadelerin tümü geçerlidir:

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

Beyaz listedeki işlevler

// 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')

¹Tek parametreli ok işlevlerinde parantez kullanılamaz; örneğin (x) => x + 1 yerine x => x + 1 kullanın. Ayrıca, sort() ve splice(), yerinde çalışma yerine değiştirilmiş kopyalar döndürür.

²Statik işlevler ad alanlı değildir; ör. Math.abs(-1) yerine abs(-1) işlevini kullanın.

Makroları amp-bind-macro ile tanımlama

amp-bind ifade parçaları bir amp-bind-macro tanımlanarak yeniden kullanılabilir. amp-bind-macro öğesi, sıfır veya daha fazla bağımsız değişken alan ve geçerli duruma başvuruda bulunan bir ifade tanımlamanıza olanak tanır. Bir makro, dokümanın herhangi bir yerinden id özelliği değerine başvuruda bulunularak bir işlev gibi çağrılabilir.

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

Bir makro, kendisinden önce tanımlanan diğer makroları da çağırabilir. Bir makro kendini yinelemeli olarak çağıramaz.

Bağlamalar

Bağlama, bir öğenin özelliğini bir ifadeye bağlayan [property] formunun özel bir özelliğidir. data-amp-bind-property alternatif, XML uyumlu bir söz dizimi de kullanılabilir.

Durum değiştiğinde, ifadeler yeniden değerlendirilir ve bağlı öğelerin özellikleri yeni ifade sonuçlarıyla güncellenir.

amp-bind, dört öğe durumu türünde veri bağlamalarını destekler:

Bağlamalar ile ilgili notlar:

• Güvenlik nedeniyle, innerHTML öğesine bağlamaya izin verilmez.
• Güvenli olmayan değerler (ör. javascript:) tüm özellik bağlamalarından temizlenir.
• Boole ifadesi sonuçları, boole özelliklerini açar/kapatır. Örneğin: <amp-video [controls]="expr"...>. expr, true olarak değerlendirildiğinde, <amp-video> öğesi controls özelliğine sahip olur. expr, false olarak değerlendirildiğinde controls özelliği kaldırılır.
• Özellik adlarındaki köşeli parantez karakterleri [ ve ] XML (ör. XHTML, JSX) veya DOM API'leri aracılığıyla özellikleri yazarken soruna yol açabilir. Bu durumlarda, [x]="foo" yerine alternatif data-amp-bind-x="foo" söz dizimini kullanın.

Öğeye özel özellikler

Yalnızca aşağıdaki bileşenlere ve özelliklere bağlamaya izin verilir:

^*Bağlanabilir olmayan bir eşdeğeri bulunmayan bağlanabilir özellikleri belirtir.

Hata ayıklama

Geliştirme sırasında ortaya çıkan uyarıları ve hataları vurgulamak ve özel hata ayıklama işlevlerine erişmek için geliştirme modunda (#development=1 URL parçasıyla) test yapın.

Uyarılar

Geliştirme modunda, bir bağlama özelliğinin varsayılan değeri, karşılık gelen ifadenin ilk sonucuyla eşleşmediğinde amp-bind bir uyarı yayınlar. Bu, diğer durum değişkenlerindeki değişikliklerin neden olduğu istenmeyen dönüşümleri önlemeye yardımcı olabilir. Örneğin:

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

Geliştirme modunda, amp-bind, tanımlanmamış değişkenleri veya özellikleri başvurudan kaldırırken bir uyarı da yayınlar. Bu, aynı zamanda null ifade sonuçları nedeniyle istenmeyen dönüşümleri önlemeye yardımcı olabilir. Örneğin:

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

Hatalar

amp-bind ile çalışırken karşılaşabileceğiniz birkaç çalışma zamanı hatası türü vardır.

Hata Ayıklama Durumu

Geçerli durumu konsola yazdırmak için AMP.printState() kullanın.

Ek

<amp-state> spesifikasyonu

Bir amp-state öğesi, bir alt <script> öğesi VEYA uzak bir JSON uç noktasının CORS URL'sini içeren bir src özelliği içerebilir ancak bunların ikisini birden içeremez.

<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 toplu işlemesi

AMP, XMLHttpRequest öğelerini (XHR'ler) JSON uç noktalarında toplu olarak işler; diğer bir deyişle, bir AMP sayfasında birden çok tüketici (ör. birden fazla amp-state öğesi) için veri kaynağı olarak tek bir JSON veri isteğini kullanabilirsiniz. Örneğin, amp-state öğeniz bir uç noktaya XHR gönderirse XHR iletilirken aynı uç noktaya yapılacak sonraki XHR'lerin hiçbiri tetiklenmez ve bunun yerine, ilk XHR'nin sonuçları döndürülür.

Özellikler

AMP.setState() ile derin birleştirme

AMP.setState() çağrıldığında, amp-bind, sağlanan nesneyi değişmez değerini geçerli durumla derin birleştirir. Nesne değişmez değerindeki tüm değişkenler, tekrar eden bir şekilde birleştirilen iç içe yerleştirilmiş nesneler haricinde, doğrudan duruma yazılır. Nesne değişmez değerinde bulunan, temel öğeler ve dizilerle aynı ada sahip değişkenlerin değeri her zaman bunların üzerine yazılır.

Aşağıdaki örneği inceleyin:

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

İlk düğmeye basıldığında durum şu şekilde değişir:

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

İkinci düğmeye basıldığında, amp-bind nesne değişmez değeri bağımsız değişkenini ({employee: {age: 64}}) yinelenen bir şekilde mevcut durumla birleştirir.

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

employee.age güncellenmiş ancak employee.name ve employee.vehicle anahtarları değişmemiştir.

AMP.setState() işlemini döngüsel başvurular içeren bir nesne değişmez değeriyle çağırırsanız amp-bind öğesinin hata vereceğini lütfen unutmayın.

Bir değişkeni kaldırma

Mevcut bir durum değişkeninin değerini AMP.setState() işleminde null olarak ayarlayarak değişkeni kaldırın. Önceki örnekteki durumla başlayarak:

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

Düğmesine basıldığında durum şu şekilde değişir:

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

Benzer biçimde:

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

Düğmesine basıldığında durum şu şekilde değişir:

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

İfade dil bilgisi

amp-bind ifadeleri için BNF benzeri dil bilgisi:

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