amp-bind

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

يضيف المكوِّن تفاعلاً مخصصًا باستخدام ربط البيانات والتعبيرات.

[جدول المحتويات]

نظرة عامة

يتيح لك المكوِّن amp-bind إضافة تفاعل ذي حالة مخصصة إلى صفحات 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. State: حالة JSON قابلة للتحويل على نطاق المستند. في المثال أعلاه، الحالة فارغة قبل النقر على الزر. أما بعد النقر، تصبح الحالة {foo: 'amp-bind'}.
2. Expressions: هذه تعبيرات تشبيه جافا سكريبت وتشير إلى state. يحتوي المثال أعلاه على تعبير واحد هو 'Hello ' + foo والذي يربط السلسلة الحرفية 'Hello ' مع متغير الحالة foo. يمكن استخدام ما يصل إلى 100 معامل كحد أقصى في التعبير.
3. Bindings: هذه سمات خاصة لخاصية [property] النموذج التي تربط خاصية العنصر بالتعبير expression. يحتوي المثال أعلاه على ربط واحد هو [text] والذي يعدّل نص العنصر `` كلما تغيرت قيمة التعبير.

يحتاج amp-bind إلى عناية خاصة لضمان السرعة والأمان وجودة الأداء على صفحات AMP.

مثال أكثر تعقيدًا

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

عند الضغط على الزر:

1. يتم تعديل الحالة بـ currentAnimal الذي يتم تحديده على أنه 'cat'.

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."
   • السمة class للعنصر <p> الثاني ستصبح "redBackground".
   • العنصر amp-img سيعرض صورة قطة.

التفاصيل

الحالة

كل مستند AMP يستخدم amp-bind له بيانات JSON أو حالة قابلة للتحويل على نطاق المستند.

إعداد الحالة باستخدام amp-state

يمكن إعداد حالة amp-bind باستخدام المكوِّن amp-state:

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

يمكن أن تشير التعبيرات إلى متغيرات الحالة عبر بنية النقاط. في هذا المثال، سيتم تقييم myState.foo إلى "bar".

• الحد الأقصى لحجم JSON للعنصر الثانوي للعنصر <amp-state> هو 100 كيلوبايت.
• يمكن للعنصر <amp-state> أيضًا تحديد عنوان CORS URL بدلاً من نص برمجي لعنصر JSON الثانوي. يمكن مراجعة الملحق للحصول على التفاصيل.

إعادة تحميل الحالة

يتيح هذ المكوِّن الإجراء refresh الذي يمكن استخدامه لإعادة تحميل محتوى الحالة.

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

تعديل الحالة باستخدام AMP.setState()

يُدمِج الإجراء AMP.setState() كائنًا حرفيًا في الحالة. عند الضغط على الزر أدناه مثلاً، سيعمل AMP.setState() على الدمج العميق للكائن الحرفي مع الحالة.

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

بشكل عام، سيتم دمج الكائنات المدمجة بحد أقصى للعمق يساوي 10. يمكن إلغاء كل المتغيرات، بما في ذلك المتغيرات التي قدمها amp-state.

عند تشغيل الإجراء AMP.setState() بواسطة أحداث معينة، يمكنه أيضًا الوصول إلى البيانات المتعلقة بالأحداث في الخاصية 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})">

تعديل السجلّ باستخدام 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'}).

التعبيرات

التعبيرات تشبه جافا سكريبت مع بعض الاختلافات المهمة.

الاختلافات التي تميّزها عن جافا سكريبت

• قد تصل التعبيرات فقط إلى حالة المستند الحاوية.
• ليست للتعبيرات إمكانية الوصول إلى المتغيرات العمومية مثل 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'

الدالات المدرجة في القائمة البيضاء

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

¹لا يمكن أن تحتوي الدالات السهمية ذات المعلَمة الفردية على أقواس، استخدِم مثلاً x => x + 1 بدلاً من (x) => x + 1. وتعرض أيضًا sort() وsplice() نسخًا معدّلة بدلاً العمل في مكانها.

²الدالات الثابتة لا تستخدم كمساحات أسماء، استخدِم مثلاً abs(-1) بدلاً من Math.abs(-1).

تحديد وحدات الماكرو باستخدام amp-bind-macro

يمكن إعادة استخدام أجزاء التعبير amp-bind من خلال تحديد amp-bind-macro. يتيح لك العنصر 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] للنموذج تربط خاصية العنصر بأحد التعبيرات. ويمكن أيضًا استخدام بنية متوافقة مع XML في شكل data-amp-bind-property.

عندما تتغير الحالة، يتم إعادة تقييم التعبيرات ويتم تعديل خصائص العناصر المرتبطة بنتائج التعبيرات الجديدة.

يتيح amp-bind روابط البيانات في أربعة أنواع من حالة العنصر:

ملاحظات عن عمليات الربط:

• إن الربط بـ innerHTML غير مسموح به لأسباب تتعلق بالأمان.
• يتم تصحيح جميع عمليات ربط السمات من القيم غير الآمنة (مثل javascript:).
• يؤدي التعبير المنطقي إلى تبديل السمات المنطقية على سبيل المثال: <amp-video [controls]="expr"...>. عندما يتم تقييم expr إلى true، يحتوي العنصر <amp-video> على السمة controls. عند تقييم expr إلى false، تتم إزالة السمة controls.
• يمكن أن تكون أحرف الأقواس [ and ] في أسماء السمات مشكلة عند كتابة XML (مثل XHTML وJSX) أو كتابة السمات عبر واجهات برمجة التطبيقات DOM. في هذه الحالات، استخدِم البنية البديلة data-amp-bind-x="foo" بدلاً من [x]="foo".

السمات الخاصة بالعناصر

يُسمح فقط بالربط مع المكونات والسمات التالية:

تشير إلى سمات قابلة للربط ليس لها نظير غير قابل للربط.

تصحيح الأخطاء

اختبِر في وضع مطور البرامج (باستخدام جزء عنوان URL #development=1) لإبراز التحذيرات والأخطاء أثناء التطوير والوصول إلى الوظائف الخاصة لتصحيح الأخطاء.

التحذيرات

في وضع مطور البرامج، سيصدر amp-bind تحذيرًا عندما لا تتطابق القيمة التلقائية لسمة مرتبطة مع النتيجة الأولية للتعبير المقابل. يمكن أن يساعد هذا في منع الطفرات غير المقصودة الناجمة عن التغييرات في متغيرات الحالة الأخرى. مثال:

<!-- 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]="'abc'" class="def"></p>

في وضع مطور البرامج، سيصدر amp-bind أيضًا تحذيرًا عند الوصول إلى محتوى المتغيرات أو الخصائص غير المحددة. يمكن أن يساعد هذا أيضًا في منع الطفرات غير المقصودة بسبب نتائج التعبير null. مثال:

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

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

الأخطاء

هناك عدة أنواع من أخطاء وقت التشغيل التي يمكن مواجهتها عند التعامل مع amp-bind.

حالة تصحيح الأخطاء

استخدِم AMP.printState() لطباعة الحالة الحالية إلى وحدة التحكم.

الملحق

مواصفات <amp-state>

قد يحتوي عنصر amp-state على عنصر <script> الثانوي أو سمة src التي تحتوي على عنوان CORS URL إلى نقطة نهاية JSON بعيدة، ولكن ليس على كليهما.

<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 ترسل XMLHttpRequests (XHRs) إلى نقاط نهاية JSON في دفعات، أي أنه يمكنك استخدام طلب بيانات JSON واحد كمصدر بيانات لعدة مستهلكين (عدة عناصر amp-state مثلاً) على صفحة AMP. على سبيل المثال، إذا أرسل العنصر amp-state طلب XHR إلى نقطة نهاية، وكان الطلب في رحلته، لن يتم تشغيل جميع طلبات XHR اللاحقة إلى نقطة النهاية ونفسها وسيتم عرض النتائج من طلب XHR الأول.

السمات

الدمج العميق باستخدام AMP.setState()

عندما يتم استدعاء AMP.setState()، يدمج amp-bind الكائن الحرفي المتوفر بعمق مع الحالة الحالية. تتم كتابة جميع المتغيرات من الكائن الحرفي إلى الحالة مباشرة باستثناء الكائنات المدمجة والتي يتم دمجها بشكل متكرر. يتم دائمًا إلغاء العناصر الأولية والمصفوفات في الحالة بمتغيرات تحمل الاسم نفسه في الكائن الحرفي.

راجع المثال التالي:

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

عند الضغط على الزر الأول، تتغير الحالة إلى:

{
  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-bind ستعطي خطأ إذا استدعيت AMP.setState() بكائن حرفي يحتوي على مراجع دائرية.

إزالة متغير

أزِل متغير حالة قائم عن طريق تعيين قيمته إلى القيمة null في AMP.setState(). بالبدء من الحالة في المثال السابق، سيؤدي الضغط إلى:

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

تغيير الحالة إلى:

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

بالمثل:

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

تغيير الحالة إلى:

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

قواعد التعبيرات

القواعد المشابهة لـ BNF لتعبيرات 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