amp-form

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

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

السلوك

تتيح لك الإضافة amp-form إنشاء نماذج (<form>) لإرسال حقول الإدخال في مستند AMP. وتوفر الإضافة amp-form أيضًا تعويضات لبعض السلوكيات المفقودة في المتصفحات.

قبل إنشاء <form>، يجب تضمين النص البرمجي المطلوب للإضافة <amp-form>، وإلا فلن يكون المستند صالحًا. إذا كنت تستخدم علامات input لأغراض أخرى غير إرسال قيمها (مثل الإدخالات غير الموجودة في <form>)، لن تحتاج إلى تحميل الإضافة amp-form.

فيما يلي مثال لنموذج أساسي:

<form method="post"
    action-xhr="https://example.com/subscribe"  
    target="_top">
    <fieldset>
      <label>
        <span>Name:</span>
        <input type="text"
          name="name"
          required>
      </label>
      <br>
      <label>
        <span>Email:</span>
        <input type="email"
          name="email"
          required>
      </label>
      <br>
      <input type="submit"
        value="Subscribe">
    </fieldset>
    <div submit-success>
      <template type="amp-mustache">
        Subscription successful!
      </template>
    </div>
    <div submit-error>
      <template type="amp-mustache">
        Subscription failed!
      </template>
    </div>
  </form>

السمات

target

تشير إلى مكان عرض استجابة النموذج بعد إرساله. ويجب أن تكون القيمة _blank أو _top.

action

تحدد نقطة نهاية الخادم لمعالجة إدخال النموذج. يجب أن تكون القيمة عنوان URL مبدوءًا بـ https (مطلق أو نسبي) ويجب ألا تكون رابطًا إلى شبكة عرض المحتوى.

• بالنسبة إلى method=GET: استخدِم هذه السمة أو action-xhr.
• بالنسبة إلى method=POST: استخدِم السمة action-xhr.

action-xhr

تحدد نقطة نهاية الخادم لمعالجة إدخال النموذج وإرساله عبر XMLHttpRequest (XHR). طلب XHR (الذي يسمى أحيانًا طلب AJAX) هو طلب يقدمه المتصفح بدون تحميل كامل للصفحة أو فتح صفحة جديدة. سترسل المتصفحات الطلب في الخلفية باستخدام واجهة برمجة تطبيقات الجلب متى توفرت وترجع إلى استخدام واجهة برمجة تطبيقات XMLHttpRequest للمتصفحات الأقدم.

هذه السمة مطلوبة للطريقة method=POST واختيارية للطريقة method=GET.

يمكن أن تكون قيمة action-xhr هي نقطة نهاية action نفسها أو نقطة نهاية مختلفة ويكون للقيمة نفس متطلبات action أعلاه.

لمعرفة المزيد عن إعادة توجيه المستخدِم بعد إرسال النموذج بنجاح، يمكنك مراجعة القسم إعادة التوجيه بعد إرسال النموذج أدناه.

السمات الأخرى للنموذج

جميع سمات النموذج الأخرى اختيارية.

custom-validation-reporting

هذه سمة اختيارية تُستخدم لتفعيل واختيار استراتيجية مخصصة لإعداد تقارير التحقق من الصحة. وقيمها الصالحة واحدة مما يلي: show-first-on-submit أو show-all-on-submit أو as-you-go.

راجِع قسم التحقق المخصص لمعرفة المزيد من التفاصيل.

الإدخالات والحقول

المسموح بها:

• العناصر الأخرى ذات الصلة بالنموذج، بما في ذلك: <textarea> و<select> و<option> و<fieldset> و<label> و<input type=text> و<input type=submit> وما إلى ذلك
• <input type=password> و<input type=file> في <form method=POST action-xhr>
• amp-selector

غير المسموح بها:

• <input type=button> و<input type=image>
• معظم السمات المتعلقة بالنموذج في الإدخالات ومنها: form وformaction وformtarget وformmethod وغيرها

(قد يتم مستقبلاً إعادة النظر في تخفيف بعض هذه القواعد - يرجى إعلامنا إذا كنت تحتاج هذه الإدخالات أو الحقول مع تقديم حالات استخدام).

للحصول على تفاصيل حول الإدخالات والحقول الصحيحة، راجِع قواعد amp-form في مواصفات مدقق AMP.

الإجراءات

يقدم العنصر amp-form الإجراءات التالية:

الأحداث

يعرض amp-form الأحداث التالية:

يمكن استخدام هذه الأحداث عبر السمة on.

يستجيب النموذج في المثال التالي إلى أحداث submit-success وsubmit-error ويظهر عروضًا مبسطة اعتمادًا على الحدث:

<form ...="" on="submit-success:success-lightbox;submit-error:error-lightbox">
</form>

يمكن الاطّلاع على المثال بالكامل هنا.

أحداث الإدخال

تعرض AMP أحداث change وinput-debounced في عناصر <input> الثانوية. يتيح لك ذلك استخدام السمة on لتنفيذ إجراء على أي عنصر عند تغيّر قيمة الإدخال.

من بين حالات الاستخدام الشائعة مثلاً إرسال نموذج عند تغير الإدخال (تحديد زر الاختيار للإجابة على استطلاع أو اختيار اللغة من الإدخال select لترجمة الصفحة، وغير ذلك).

<form id="myform"
    method="post"
    action-xhr="https://example.com/myform"  
    target="_blank">
    <fieldset>
      <label>
        <input name="answer1"
          value="Value 1"
          type="radio"
          on="change:myform.submit">Value 1
      </label>
      <label>
        <input name="answer1"
          value="Value 2"
          type="radio"
          on="change:myform.submit">Value 2
      </label>
    </fieldset>
  </form>

يمكن الاطّلاع على المثال بالكامل هنا.

مشغلات التحليلات

تؤدي الإضافة amp-form إلى تشغيل الأحداث التالية التي يمكنك تتبعها في تهيئة amp-analytics:

يمكنك تهيئة التحليلات لإرسال هذه الأحداث كما في المثال التالي:

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "event": "https://www.example.com/analytics/event?eid=${eventId}",
        "searchEvent": "https://www.example.com/analytics/search?formId=${formId}&query=${formFields[query]}"
      },
      "triggers": {
        "formSubmit": {
          "on": "amp-form-submit",
          "request": "searchEvent"
        },
        "formSubmitSuccess": {
          "on": "amp-form-submit-success",
          "request": "event",
          "vars": {
            "eventId": "form-submit-success"
          }
        },
        "formSubmitError": {
          "on": "amp-form-submit-error",
          "request": "event",
          "vars": {
            "eventId": "form-submit-error"
          }
        }
      }
    }
  </script>
</amp-analytics>

تنشئ الأحداث الثلاثة مجموعة من المتغيرات التي تتوافق مع النموذج المحدد والحقول الواردة فيه. يمكن استخدام هذه المتغيرات للتحليلات.

يحتوي النموذج التالي مثلاً على حقل واحد:

<form id="submit_form" action-xhr="/comment" method="POST">
<input type="text" name="comment">
<input type="submit" value="تعليق">
</form>

عند تنشيط الحدث amp-form-submit أو amp-form-submit-success أو amp-form-submit-error، ينشئ المتغيرات التالية التي تحتوي على القيم التي تم تحديدها في النموذج:

• formId
• formFields[comment]

عرض استجابة النجاح/الخطأ

يمكنك عرض استجابات النجاح أو الخطأ في النموذج باستخدام النماذج الموسَّعة، مثل amp-mustache، أو عرض استجابات النجاح من خلال ربط البيانات باستخدام amp-bind وسمات الاستجابة التالية:

لعرض الاستجابات باستخدام النماذج، يمكنك:

• تطبيق سمة استجابة على أي عنصر ثانوي مباشر للعنصر <form>
• عرض الاستجابة في العنصر الثانوي من خلال إدراج نموذج عبر العلامة <template></template> أو <script type="text/plain"></script> داخل العنصر أو بالإشارة إلى النموذج باستخدام السمة template="id_of_other_template"
• توفير كائن JSON صالح للاستجابة للسمة submit-success وsubmit-error. يجب أن تحتوي استجابات النجاح والخطأ على الرأس Content-Type: application/json.

مثال: نموذج يعرض رسائل النجاح والخطأ والإرسال

في المثال التالي، يتم عرض الاستجابات في نموذج مضمّن داخل النموذج.

<form ...>
  <fieldset>
    <input type="text" name="firstName" />
    ...
  </fieldset>
  <div verify-error>
    <template type="amp-mustache">
      There is a mistake in the form!
      {{#verifyErrors}}{{message}}{{/verifyErrors}}
    </template>
  </div>
  <div submitting>
    <template type="amp-mustache">
      Form submitting... Thank you for waiting {{name}}.
    </template>
  </div>
  <div submit-success>
    <template type="amp-mustache">
      Success! Thanks {{name}} for subscribing! Please make sure to check your email {{email}}
      to confirm! After that we'll start sending you weekly articles on {{#interests}}<b>{{name}}</b> {{/interests}}.
    </template>
  </div>
  <div submit-error>
    <template type="amp-mustache">
      Oops! {{name}}, {{message}}.
    </template>
  </div>
</form>

تعرض نقطة نهاية action-xhr للناشر استجابات JSON التالية:

عند النجاح:

{
  "name": "Jane Miller",
  "interests": [{"name": "Basketball"}, {"name": "Swimming"}, {"name": "Reading"}],
  "email": "email@example.com"
}

عند حدوث خطأ:

{
  "name": "Jane Miller",
  "message": "The email (email@example.com) you used is already subscribed."
}

يمكنك عرض الاستجابات في نموذج مرجعي تم تعريفه مسبقًا في المستند باستخدام معرّف النموذج كقيمة لسمة template وتعيين العناصر ذات السمات submit-success submit-error.

<template type="amp-mustache" id="submit_success_template">
  Success! Thanks {{name}} for subscribing! Please make sure to check your email {{email}}
  to confirm! After that we'll start sending you weekly articles on {{#interests}}<b>{{name}}</b> {{/interests}}.
</template>
<template type="amp-mustache" id="submit_error_template">
  Oops! {{name}}, {{message}}.
</template>

<form ...>
  <fieldset>
  ...
  </fieldset>
  <div submit-success template="submit_success_template"></div>
  <div submit-error template="submit_error_template"></div>
</form>

يمكن الاطّلاع على المثال بالكامل هنا.

لعرض استجابة ناجحة باستخدام ربط البيانات

• استخدِم السمة on لربط سمة النموذج submit-success بالإجراء AMP.setState().
• استخدِم الخاصية event لاستخراج بيانات الاستجابة.
• أضِف سمة الحالة إلى العنصر المطلوب لربط استجابة النموذج.

يوضح المثال التالي استجابة submit-success للنموذج باستخدام amp-bind:

<p [text]="'Thanks, ' + subscribe +'! You have successfully subscribed.'">Subscribe to our newsletter</p>
<form method="post"
      action-xhr="/components/amp-form/submit-form-input-text-xhr"
      target="_top"
      on="submit-success: AMP.setState({'subscribe': event.response.name})">
  <div>
    <input type="text"
        name="name"
        placeholder="Name..."
        required>
    <input type="email"
      name="email"
      placeholder="Email..."
      required>
  </div>
  <input type="submit" value="Subscribe">
</form>

عند إرسال النموذج بنجاح، سيعرض استجابة JSON مشابهة لما يلي:

{
  "name": "Jane Miller"