AMP
AR
English Deutsch Français Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

الإجراءات والأحداث

Important: this documentation is not applicable to your currently selected format email!

تغطي هذه الوثائق الإجراءات والأحداث الخاصة بمواقع الويب والقصص والإعلانات الخاصة بـ AMP. اقرأ الإجراءات والأحداث في بريد AMP الإلكتروني لتنسيق البريد الإلكتروني الخاص بـ AMP.

يتم استخدام السمة on لتثبيت معالجات الحدث في العناصر. إذ تعتمد الأحداث المدعومة على العنصر.

القيمة لبناء الجملة عبارة عن لغة بسيطة محددة بالمجال خاصة بالنموذج:

eventName:targetId[.methodName[(arg1=value, arg2=value)]]

راجع الجدول أدناه لتوصيفات كل جزء من بناء الجملة.

بناء الجملة مطلوب؟ الوصف
eventName نعم اسم الحدث الذي يظهره العنصر.
targetId نعم هذا هو معرّف نموذج كائن المستند للعنصر، أو هدف خاص محدد مسبقًا تريد تنفيذ إجراء عليه ردًا على الحدث. في المثال التالي، targetId هو معرف نموذج كائن المستند للهدف amp-lightbox،photo-slides. 
<amp-lightbox id = "photo-slides"> </amp-lightbox>
<button on = "tap: photo-slides">Show Images</button>
methodName لا هذا للعناصر التي تتضمن إجراءات افتراضية.

وهذه هي الطريقة التي يقوم بها العنصر الهدف (مشار إليه من قبل targetId) بإظهاره وترغب في تنفيذه عند تشغيل الحدث.

وتتضمن AMP مفهومًا للإجراء الافتراضي الذي يمكن للعناصر تنفيذه. لذا عند حذف methodName سيقوم AMP بتنفيذ الطريقة الافتراضية.
arg=value لا قد تقبل بعض الإجراءات الوسيطات، إذا كانت موثَّقة. ويتم تحديد الوسيطات بين هلالين في ترقيم key=value. وتكون القيم المقبولة عبارة عن:
  • سلاسل بسيطة من دون قوسين: simple-value
  • سلاسل بين قوسين: "string value" أو 'string value'
  • قيم ثنائية: true أو false
  • أرقام: 11 أو 1.1
  • إشارة بناء الجملة بنقطة إلى بيانات الحدث: event.someDataVariableName

معالجة أحداث متعددة

يمكنك الاستماع إلى أحداث متعددة في عنصر من خلال فصل الأحداث بفاصلة منقوطة ;.

مثال: on="submit-success:lightbox1;submit-error:lightbox2"

إجراءات متعددة لحدث واحد

يمكنك تنفيذ الإجراءات بتسلسل للحدث نفسه من خلال فصل الإجراءات بفاصلة "،".

مثال: on="tap:target1.actionA,target2.actionB"

الأحداث والإجراءات المحددة عالميًا

يحدد AMP حدث tap عالميًا بحيث يمكنك الاستماع إلى أحد عناصر HTML (بما في ذلك عناصر AMP).

كما أن AMP يحدد أيضًا إجراءات hide، وshow وtoggleVisibility عالميًا التي يمكنك تشغيلها في أي عنصر HTML.

يمكن إظهار عنصر إذا كان مخفيًا مسبقًا عن طريق الإجراء hide أو toggleVisibility أو من خلال استخدام سمة hidden. حيث إن إجراء show لا يدعم العناصر المخفية عن طريق CSS display:none أو layout=nodisplay الخاصة بـ AMP.

على سبيل المثال، ما يلي ممكن في AMP:

<div id="warning-message">Warning...</div>

<button on="tap:warning-message.hide">Cool, thanks!</button>

الأحداث المحددة بالعنصر

* - كل العناصر

الحدث الوصف
tap التشغيل عند النقر فوق/الضغط على العنصر.

عناصر الإدخال

الحدث الوصف العناصر البيانات
change التشغيل عند تغيير قيمة العنصر وتنفيذها.

وتعكس خصائص البيانات تلك الأشياء في HTMLInputElement وHTMLSelectElement.

 input 
event.min
event.max
event.value
event.valueAsNumber
input[type="radio"],
input[type="checkbox"] 		event.checked
select 
event.min
event.max
event.value
input-debounced التشغيل عند تغيير قيمة العنصر. وهذا مماثل لحدث change القياسي، لكنه يقوم بعملية التشغيل فقط عند مرور 300 مللي ثانية بعد توقف تغيير قيمة الإدخال. العناصر التي تشغِّل حدث input. مماثل لبيانات حدث change.
input-throttled التشغيل عند تغيير قيمة العنصر. وهذا مماثل لحدث change القياسي، لكن تتم عملية التقييد من أجل التشغيل مرة واحدة على الأكثر كل 100 مللي ثانية أثناء تغيير قيمة الإدخال. العناصر التي تشغِّل حدث input. مماثل لبيانات حدث change.

amp-accordion > قسم

الحدث الوصف البيانات
expand التشغيل عن تمديد قسم أكورديون. لا يوجد.
collapse التشغيل عند طي قسم أكوروديون. لا يوجد.

amp-carousel[type="slides"]

الحدث الوصف البيانات
slideChange التشغيل عند تغيير شريحة المكتبة الحالية. 
// Slide number.
event.index

amp-lightbox

الحدث الوصف البيانات
lightboxOpen التشغيل عندما يكون lightbox مرئيًا بالكامل. لا يوجد
lightboxClose التشغيل عدما يكون lightbox مغلقًا بالكامل. لا يوجد

amp-list

الحدث الوصف البيانات
changeToLayoutContainer تحديث تخطيط amp-list إلى layout="CONTAINTER" للسماح بتغيير الحجم الديناميكي.
fetch-error(انخفاض مستوى الثقة) التشغيل عند فشل إحضار البيانات. لا يوجد

amp-selector

الحدث الوصف البيانات
select التشغيل عند تحديد أو إلغاء تحديد خيار. 
// Target element's "option" attribute value.
event.targetOption
// Array of "option" attribute values of all selected elements.
event.selectedOptions

amp-sidebar

الحدث الوصف البيانات
sidebarOpen التشغيل عندما يكون الشريط الجانبي مفتوح بالكامل بعد انتهاء النقل. لا يوجد
sidebarClose التشغيل عندما يكون الشريط الجانبي مغلق بالكامل بعد انتهاء النقل. لا يوجد

amp-state

الحدث الوصف البيانات
fetch-error(انخفاض مستوى الثقة) التشغيل عند فشل إحضار البيانات. لا يوجد

amp-video, amp-youtube

الحدث الوصف البيانات
firstPlay(منخفض الثقة) التشغيل في المرة الأولى التي يتم فيها تشغيل الفيديو. في مقاطع الفيديو التي يتم تشغيلها تلقائيًا، يتم تشغيله بمجرد تفاعل المستخدم مع الفيديو. وهذا الحدث منخفض الثقة مما يعني عدم إمكانية تشغيل معظم الإجراءات؛ يمكن فقط تشغيل الإجراءات منخفضة الثقة مثل إجراءات amp-animation.
timeUpdate(منخفضة الثقة) التشغيل عند تغيير موضع تشغيل مقطع الفيديو. ويتم التحكم في تردد الحدث بواسطة AMP ويتم ضبطه حاليًا على فترات زمنية تبلغ 1 ثانية. وهذا الحدث منخفض الثقة مما يعني عدم إمكانية تشغيل معظم الإجراءات؛ يمكن فقط تشغيل الإجراءات منخفضة الثقة مثل إجراءات amp-animation. يشير {time, percent}time إلى الوقت الحالي بالثواني، أما percent عبارة عن رقم بين 0 و1 ويشير إلى الموضع الحالي كنسبة للوقت الإجمالي.

النموذج

الحدث الوصف البيانات
submit التشغيل عند إرسال النموذج.
submit-success Fired when the form submission response is success. 
// Response JSON.
event.response
submit-error التشغيل عند وجود خطأ في استجابة إرسال النموذج. 
// Response JSON.
event.response
valid التشغيل عندما يكون النموذج صالحًا.
invalid التشغيل عندما يكون النموذج غير صالح.

الإجراءات المحددة بالعنصر

* (كل العناصر)

الإجراء الوصف
hide إخفاء العنصر الهدف.
show إظهار العنصر الهدف، إذا أصبح عنصر autofocus مرئيًا كنتيجة لذلك، فإنه يكتسب التركيز.
toggleVisibility تبديل رؤية العنص الهدف. إذا أصبح عنصر autofocus مرئيًا كنتيجة لذلك، فإنه يكتسب التركيز.
toggleClass(class=STRING, force=BOOLEAN) تبديل فئة العنصر الهدف. حيث إن force اختياري، وفي حالة التحديد؛ يضمن إضافة الفئة فقط لكن من دون إزالتها في حالة التعيين إلى true، والإزالة فقط من دون إضافة في حالة التعيين إلى false.
scrollTo(duration=INTEGER, position=STRING) لتمرير عنصر للعرض باستخدام حركة سلسة.
duration اختياري. يحدد طول الحركة بالمللي ثانية. إذا لم يتم تحديد ذلك، فسيتم استخدام مبلغ متعلق بفرق التمرير أقل أو يساوي 500 مللي ثانية.
position اختياري. أحد top، center أو bottom (افتراضي top). لتحديد موضع العنصر بالنسبة إلى منفذ العرض بعد التمرير.
كأفضل ممارسة لإمكانية الوصول، قم بإقران هذا باستدعاء focus() للتركيز على العنصر الذي يتم التمرير إليه.
focus التسبب في إكساب العنصر الهدف للتركيز. لخسارة التركيز focus على عنصر آخر (عنصر أصل). إننا ننصح بشدة بعدفقدان التركيز على body/documentElement لأسباب تتعلق بإمكانية الوصول.

amp-audio

الإجراء الوصف
play يشغل الصوت. وهو عبارة عن تعليمة غير فعالة إذا كان العنصر <amp-audio> تابعًا لـ <amp-story>.
pause يوقف الصوت مؤقتًا. وهو عبارة عن تعليمة غير فعالة إذا كان العنصر <amp-audio> تابعًا لـ <amp-story>.

amp-bodymovin-animation

الإجراء الوصف
play تشغيل الرسوم المتحركة.
pause إيقاف تشغيل الرسوم المتحركة مؤقتًا.
stop إيقاف الرسوم المتحركة.
seekTo(time=INTEGER) تعيين الوقت الحالي للرسوم المتحركة على القيمة المحددة وإيقاف الرسوم المتحركة مؤقتًا.
seekTo(percent=[0,1]) استخدام قيمة النسبة المئوية المحددة لتحديد الوقت الحالي للرسوم المتحركة إلى القيمة المحددة وإيقاف الحركة مؤقتًا.

amp-accordion

الإجراء الوصف
toggle(section=STRING) تبديل الحالات expanded وcollapsed الخاصة بالأقسام amp-accordion. عند الاستدعاء من دون وسيطات، يقوم بتدبيل كل الأقسام القابلة للطي. قم بتشغيل قسم معين من خلال توفير معرِّف القسم: on="tap:myAccordion.toggle(section='section-id')".
expand(section=STRING) توسيع الأقسام الخاصة بالأكورديون. إذا تم توسيع القسم بالفعل، فسيظل موسعًا. وعندما يتم استدعاؤه بدون وسيطات، فإنه يقوم بتوسيع كل أقسام الأكورديون. قم بتشغيل قسم معين من خلال توفير معرِّف القسم: on="tap:myAccordion.expand(section='section-id')".
collapse(section=STRING) طي أقسام الأكورديون. إذا كان القسم مطويًا بالفعل، فإنه يظل مطويًا. وعندما يتم استدعاؤه بدون وسيطات، فإنه يقوم بطي كل أقسام الأكورديون. قم بتشغيل قسم معين من خلال توفير معرِّف القسم: on="tap:myAccordion.collapse(section='section-id')".

amp-carousel[type="slides"]

الإجراء الوصف
goToSlide(index=INTEGER) تقدم المكتبة إلى فهرس شرائح محدد.
toggleAutoplay(toggleOn=true|false) تبديل حالة التشغيل التلقائي للمكتبة. toggleOn اختياري.

amp-image-lightbox

الإجراء الوصف
open (default) فتح lightbox للصورة مع كون الصورة المصدر هي التي أدت إلى تشغيل الإجراء.

amp-lightbox

الإجراء الوصف
open (default) فتح lightbox.
close إغلاق lightbox.
الإجراء الوصف
open فتح معرض Lightbox. إذ يمكن تشغيله عن طريق النقر فوق عنصر آخر، إذا قمت بتحديد معرِّف الصورة: `on="tap:amp-lightbox-gallery.open(id='image-id')"`.

amp-list

الإجراء الوصف
refresh تحديث البيانات من src وإعادة عرض القائمة.

amp-live-list

الإجراء الوصف
update (default) تحديث عناصر DOM لعرض المحتوى المحدَّث.

amp-selector

الإجراء الوصف
clear إزالة كل التحديدات من amp-selector محددة.
selectUp(delta=INTEGER) لنقل التحديد إلى أعلى حسب قيمة "دلتا". إذ يتم تعيين قيمة "دلتا" الافتراضية إلى -1. إذا لم يتم تحديد أي خيارات، فإن الحالة المحددة ستصبح قيمة الخيار الأخير.
selectDown(delta=INTEGER) لنقل التحديد إلى أسفل حسب قيمة "دلتا". إذ يتم تعيين قيمة "دلتا" الافتراضية إلى 1. إذا لم يتم تحديد أي خيارات، فإن الحالة المحددة ستصبح قيمة الخيار الأول.
toggle(index=INTEGER, value=BOOLEAN) تبديل التطبيق الخاص "بالمحدد". إذا كانت سمة التحديد غير موجودة، فإن هذا الإجراء يضيفها. وإذا كانت سمة التحديد موجودة، فإن هذا الإجراء يزيلها. ويمكنك فرض إضافة أو إزالة والاحتفاظ بها عن طريق تضمين قيمة منطقية في وسيطة "القيمة". وستفرض قيمة "صحيح" إضافة السمة "المحددة" وعدم إزالتها إذا كانت موجودة بالفعل. وستؤدي القيمة "خطأ" إلى إزالة السمة، ولكن لن تضيفها في حالة عدم وجودها.

amp-sidebar

الإجراء الوصف
open (default) فتح الشريط الجانبي.
close إغلاق الشريط الجانبي.
toggle تبديل حالة الشريط الجانبي.

amp-state

الإجراء الوصف
refresh تحديث البيانات عند السمة `src` أثناء تجاهل ذاكرة التخزين المؤقت للمتصفح.

amp-user-notification

الإجراء الوصف
dismiss (default) إخفاء عنصر إشعار المستخدم المشار إليه.

عناصر الفيديو

يتم دعم الإجراءات أدناه في عناصر فيديو AMP التالية: amp-video، amp-youtube، amp-3q-player، amp-brid-player، amp-dailymotion، amp-delight-player، amp-ima-video.

الإجراء الوصف
play تشغيل الفيديو.
pause إيقاف تشغيل الفيديو مؤقتًا.
mute كتم صوت الفيديو.
unmute إلغاء كتم صوت الفيديو.
fullscreencenter تشغيل الفيديو في وضع ملء الشاشة.

النموذج

الإجراء الوصف
clear إزالة كل القيم في إدخالات النموذج.
submit إرسال النموذج.

الأهداف الخاصة

فيما يلي أهداف يوفرها نظام AMP لها متطلبات خاصة:

الهدف: AMP

يتم توفير هدف AMP عن طريق وقت تشغيل AMP وإجراءات تنفيذ عالية المستوى من شأنها تطبيق المستند بأكمله.

الإجراء الوصف
navigateTo(url=STRING, target=STRING, opener=BOOLEAN)

نقل النافذة الحالية إلى عنوان URL محدد، وذلك إلى الهدف المحدد الاختياري إذا تم توفيره (حاليًا يدعم _top و_blank فقط). ويمكن تحديد معلمة opener الاختيارية باستخدام هدف _blank للسماح للصفحات المفتوحة حديثًا بالوصول إلى window.opener. يدعم استبدالات URL القياسية.

تحذير: يوصى باستخدام روابط <a> العادية حيثما كان ذلك ممكنًا نظرًا لأن AMP.navigateTo{/ code2} لا تتعرف عليها برامج زحف الويب.
closeOrNavigateTo(url=STRING, target=STRING, opener=BOOLEAN)

محاولة إغلاق النافذة إذا كان مسموحًا، وخلاف ذلك يقوم بنقل المماثل إلى الإجراء navigateTo. مفيد لحالات الاستخدام حيث قد يحتاج زر "رجوع" إلى إغلاق النافذة إذا تم فتحه في نافذة جديدة من الصفحة السابقة أو التنقل إذا لم يتم فتحه.

تحذير: يوصى باستخدام روابط <a> العادية حيثما كان ذلك ممكنًا نظرًا لأن AMP.closeOrNavigateTo لم تتعرف عليها برامج زحف الويب.
goBack التنقل رجوعًا في السجل.
print فتح مربع حوار الطباعة من أجل طباعة الصفحة الحالية.
scrollTo(id=STRING, duration=INTEGER, position=STRING) للتمرير إلى معرف العنصر المقدم في الصفحة الحالية.
optoutOfCid رفض إنشاء معرِّف العميل لجميع النطاقات.
setState({foo: 'bar'})1

يتطلب amp-bind.

دمج ثابت كائن في الحالة القابلة للربط.
pushState({foo: 'bar'})1

يتطلب amp-bind.

دمج ثابت كائن في الحالة القابلة للربط ودفع إدخال جديد إلى مكدس سجل المتصفح. وسيؤدي عرض الإدخال إلى استعادة القيم السابقة للمتغيرات (في هذا المثال، foo).

1عند الاستخدام مع إجراءات متعددة، ستنتظر الإجراءات اللاحقة حتى اكتمال setState() أو pushState() قبل الطلب. ويسمح فقط بـ setState() أو pushState() لكل حدث.

Target: amp-access

يتم توفير الهدف amp-access عن طريق المكون amp-access.

يكون الهدف amp-access خاصًا للأسباب التالية:

  1. لا يمكنك تقديم معرِّف عشوائي لهذا الهدف. فالهدف دائمًا amp-access.
  2. تعتمد الإجراءات لـ amp-access ديناميكيًا على تكوين وصول AMP.

راجع التفاصيل حول استخدام الهدف amp-access.