AMP

amp-form

Description

Allows you to create forms to submit input fields in an AMP document.

 

Required Scripts

<script async custom-element="amp-form" src="https://cdn.ampproject.org/v0/amp-form-0.1.js"></script>
الوصف يسمح لك هذا المكّوِن بإنشاء العلامتَين form وinput.
النص البرمجي المطلوب <script async custom-element="amp-form" src="https://cdn.ampproject.org/v0/amp-form-0.1.js"></script>
التنسيقات المعتمدة لا ينطبق
أمثلة راجِع مثال amp-form على موقع "AMP بالمثال".

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

السلوك

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

إذا كنت ترسل بيانات في النموذج، يجب أن تنفذ نقطة نهاية الخادم لديك متطلبات أمان CORS.

قبل إنشاء <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.

يتم استخدام سمات target وaction فقط لطلبات GET غير xhr. سيستخدم وقت تشغيل AMP action-xhr لإنشاء الطلب وسيتجاهل action وtarget. عند عدم توفر action-xhr، ينشئ AMP طلب GET إلى نقطة النهاية action ويستخدم target لفتح نافذة جديدة (إذا كانت _blank). قد يعود وقت تشغيل AMP أيضًا إلى استخدام action وtarget في حالات تعذّر تحميل الإضافة amp-form.

action-xhr

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

يجب أن تنفذ نقطة نهاية متطلبات أمان CORS.

هذه السمة مطلوبة للطريقة 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 الإجراءات التالية:

الإجراء الوصف
submit يتيح لك تشغيل إرسال النموذج عند حدوث إجراء محدد، مثل النقر على رابط أو إرسال نموذج عن تغيير الإدخالات.
clear يعمل على تفريغ القيم من كل الإدخالات في النموذج. ويسمح هذا للمستخدِمين بسرعة ملء النماذج مرة ثانية.

الأحداث

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

الحدث موعد تنشيطه
submit عند إرسال النموذج وقبل اكتمال الإرسال
submit-success عند إتمام إرسال النموذج وعرض الاستجابة "ناجح"
submit-error عند إتمام إرسال النموذج وعرض الاستجابة "خطأ"
verify بدء التحقق غير المتزامن
verify-error عند إتمام التحقق غير المتزامن وعرض الاستجابة "خطأ"
valid عند تغير حالة التحقق للنموذج إلى "صالح" (وفقًا لاستراتيجية إعداد التقارير)
invalid عند تغير حالة التحقق للنموذج إلى "غير صالح" (وفقًا لاستراتيجية إعداد التقارير)

يمكن استخدام هذه الأحداث عبر السمة 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-form-submit عند بدء طلب نموذج
amp-form-submit-success عند تلقي استجابة ناجحة (أي عندما تكون حالة الاستجابة 2XX)
amp-form-submit-error عند تلقي استجابة غير ناجحة (أي عندما لا تكون حالة الاستجابة 2XX)

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

<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 وسمات الاستجابة التالية:

سمة الاستجابة الوصف
submit-success يمكن استخدامها لعرض رسالة نجاح في حال نجاح الاستجابة (أي أن تكون حالتها 2XX).
submit-error يمكن استخدامها لعرض رسالة "خطأ في الإرسال" في حال عدم نجاح الاستجابة (أي ألا تكون حالتها 2XX).
submitting يمكن استخدامها لعرض رسالة عند إرسال النموذج. يتمتع نموذج هذه السمة بحق الوصول إلى حقول إدخالات النموذج لغرض عرض أي رسائل. يرجى الاطّلاع على مثال النموذج الكامل أدناه لمعرفة كيفية استخدام السمة submitting.

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

  • تطبيق سمة استجابة على أي عنصر ثانوي مباشر للعنصر <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",
  "email": "email@example.com"
}

ثم يعدّل amp-bind نص العنصر <p> لمطابقة الحالة subscibe:

...
  <p [text]="'Thanks, ' + subscribe +'! You have successfully subscribed.'">Thanks Jane Miller! You have successfully subscribed.</p>
...

إعادة التوجيه بعد إرسال النموذج

يمكنك إعادة توجيه المستخدِمين إلى صفحة جديدة بعد إرسال النموذج بنجاح عن طريق تعيين رأس الاستجابة AMP-Redirect-To وتحديد عنوان URL لإعادة التوجيه. يجب أن يكون عنوان URL هذا هو عنوان HTTPS URL، وإلا ستعرض AMP رسالة خطأ ولن تتم إعادة التوجيه. تتم تهيئة رؤوس استجابة HTTP عبر الخادم لديك.

احرِص على تعديل رأس الاستجابة Access-Control-Expose-Headers لتضمين AMP-Redirect-To إلى قائمة الرؤوس المسموح بها. يمكنك التعرّف على مزيد من المعلومات عن هذه الرؤوس في أمان CORS في AMP.

مثال لرؤوس الاستجابة:

AMP-Redirect-To: https://example.com/forms/thank-you
Access-Control-Expose-Headers: AMP-Access-Control-Allow-Source-Origin, AMP-Redirect-To

راجِع إرسال النموذج مع التعديل في موقع "AMP بالمثال" وصفحة المنتج للحصول على توضيح لاستخدام إعادة التوجيه بعد إرسال النموذج.

عمليات التحقق المخصصة

تتيح لك الإضافة amp-form إنشاء واجهة مستخدِم مخصصة للتحقق باستخدام السمة custom-validation-reporting جنبًا إلى جنب مع إحدى استراتيجيات إعداد التقارير التالية: show-first-on-submit أو show-all-on-submit أو as-you-go .

لتحديد التحقق المخصص من صحة البيانات في النموذج:

  1. عيِّن السمة custom-validation-reporting في form على إحدى إستراتيجيات إعداد تقارير التحقق من صحة البيانات.
  2. وفِّر واجهة مستخدِم التحقق مع ترميزها بسمات خاصة. ستكتشف AMP السمات الخاصة وتبلغ عنها في الوقت المناسب اعتمادًا على استراتيجية إعداد التقارير التي حددتها.

وفي ما يلي مثال لذلك:



<form method="post"
    action-xhr="https://example.com/subscribe"
    custom-validation-reporting="show-all-on-submit"  
    target="_blank">
    <fieldset>
      <label>
        <span>Name:</span>
        <input type="text"
          name="name"
          id="name5"
          required
          pattern="\w+\s\w+">
        <span visible-when-invalid="valueMissing"
          validation-for="name5"></span>
        <span visible-when-invalid="patternMismatch"
          validation-for="name5">
          Please enter your first and last name separated by a space (e.g. Jane Miller)
        </span>
      </label>
      <br>
      <label>
        <span>Email:</span>
        <input type="email"
          name="email"
          id="email5"
          required>
        <span visible-when-invalid="valueMissing"
          validation-for="email5"></span>
        <span visible-when-invalid="typeMismatch"
          validation-for="email5"></span>
      </label>
      <br>
      <input type="submit"
        value="Subscribe">
    </fieldset>
  </form>
فتح هذه القصاصة في الساحة

لمزيد من الأمثلة، راجِع examples/forms.amp.html.

بالنسبة إلى رسائل التحقق من صحة البيانات، إذا كان العنصر لا يتضمن محتوى نصيًا، ستعمل AMP على ملئه بالرسالة التلقائية للمتصفح للتحقق من صحة البيانات. في المثال أعلاه، عندما يكون الإدخال name5 فارغًا ويتم بدء التحقق من صحة البيانات (حاول المستخدِم مثلاً إرسال النموذج)، ستملأ AMP <span visible-when-invalid="valueMissing" validation-for="name5"></span> برسالة التحقق للمتصفح وتعرض العلامة span هذه للمستخدِم.

يجب تقديم واجهة مستخدِم للتحقق من صحة البيانات الخاصة بك لكل نوع من الحالات غير الصالحة التي يمكن أن يمر بها الإدخال. في حال عدم توفير هذه الواجهات، فلن يرى المستخدموِن أي custom-validation-reporting لحالة الخطأ المتعلقة بفقدان الإدخالات. يمكن العثور على حالات الصلاحية في وثائق W3C الرسمية المتعلقة بإعداد تقارير التحقق من صحة HTML.

استراتيجيات إعداد التقارير

حدِّد أحد خيارات إعداد التقارير التالية للسمة custom-validation-reporting:

Show First on Submit

يحاكي خيار إعداد التقارير show-first-on-submit السلوك التلقائي للمتصفح عند بدء عملية التحقق التلقائية من صحة البيانات. ويعرض أول خطأ يجده في عملية التحقق ثم يتوقف عند هذا الحد.

Show All on Submit

يعرض خيار إعداد التقارير show-all-on-submit جميع أخطاء التحقق من جميع الإدخالات غير الصالحة عند إرسال النموذج. ويفيد إذا أردت عرض ملخص لعمليات التحقق من صحة البيانات.

As You Go

يتيح خيار إعداد التقارير as-you-go للمستخدِم رؤية رسائل التحقق من صحة البيانات أثناء تفاعله مع الإدخال. إذا كتب المستخدِم مثلاً عنوان بريد إلكتروني غير صالح، سيرى المستخدِم الخطأ على الفور. وبعد تصحيح القيمة، يختفي الخطأ.

Interact and Submit

يجمع خيار إعداد التقارير interact-and-submit بين سلوك show-all-on-submit وas-you-go. ستعرض الحقول الفردية أي أخطاء فور التفاعل، وستظهر أخطاء جميع الحقول غير الصالحة عند إرسال النموذج.

التأكيد

يعطي التحقق من توافق HTML5 تعليقات بناءً على المعلومات المتوفرة فقط على الصفحة، مثل ما إذا كانت القيمة تتطابق مع نمط معين. مع التأكيد في amp-form يمكنك إعطاء المستخدِم ملاحظات لا يمكن للتحقق من توافق HTML5 بمفرده تقديمها. يمكن أن يستخدم النموذج مثلاً التأكيد للتحقق مما إذا كان عنوان بريد إلكتروني مسجلاً. ويأتي تأكيد تطابق حقل المدينة وحقل الرمز البريدي بين حالات الاستخدام الأخرى.

في ما يلي مثال لذلك:


<h4>Verification example</h4>
<form
  method="post"
  action-xhr="/form/verify-json/post"
  verify-xhr="/form/verify-json/post"{% if not format=='email'%}  
  target="_blank"{% endif %}>
    <fieldset>
        <label>
            <span>Email</span>
            <input type="text" name="email" required>
        </label>
        <label>
            <span>Zip Code</span>
            <input type="tel" name="zip" required pattern="[0-9]{5}(-[0-9]{4})?">
        </label>
        <label>
            <span>City</span>
            <input type="text" name="city" required>
        </label>
        <label>
            <span>Document</span>
            <input type="file" name="document" no-verify>
        </label>
        <div class="spinner"></div>
        <input type="submit" value="Submit">
    </fieldset>
    <div submit-success>
        <template type="amp-mustache">
            <p>Congratulations! You are registered with {{email}}</p>
        </template>
    </div>
    <div submit-error>
        <template type="amp-mustache">
            {{#verifyErrors}}
                <p>{{message}}</p>
            {{/verifyErrors}}
            {{^verifyErrors}}
                <p>Something went wrong. Try again later?</p>
            {{/verifyErrors}}
        </template>
    </div>
</form>

يرسل النموذج حقل __amp_form_verify باعتباره جزءًا من بيانات النموذج كتلميح إلى الخادم بأن الطلب عبارة عن طلب للتأكيد وليس إرسالاً رسميًا. ويفيد هذا في إعلام الخادم بعدم تخزين طلب التحقق إذا تم استخدام نقطة النهاية نفسها للتأكيد ولإرسال النموذج.

في ما يلي مثال لشكل استجابة الخطأ للتأكيد:

{
  "verifyErrors": [
    {"name": "email", "message": "That email is already taken."},
    {"name": "zip", "message": "The city and zip do not match."}
  ]
}

لإزالة حقل من طلب verify-xhr، أضِف السمة no-verify إلى عنصر الإدخال.

لمزيد من الأمثلة، راجِع examples/forms.amp.html.

استبدال المتغيرات

تتيح الإضافة amp-form استبدال المتغيرات في المنصة للإدخالات المخفية والتي تحتوي على السمة data-amp-replace. عند كل عملية إرسال للنموذج، يعثر amp-form على كل input[type=hidden][data-amp-replace] في النموذج ويطبق استبدال المتغيرات على السمة value ويغيّرها بنتيجة الاستبدال.

عليك تقديم المتغيرات التي تستخدمها لكل استبدال في كل إدخال عن طريق تحديد سلسلة مفصول بينها بمسافات من المتغيرات المستخدَمة في data-amp-replace (انظر المثال أدناه). لن تستبدل AMP المتغيرات التي لم يتم تحديدها بشكل صريح.

في ما يلي مثال لإدخالات قبل الاستبدال وبعده (لاحظ أنك تحتاج إلى استخدام بنية المنصة لاستبدالات المتغيرات وليس الاستبدالات التحليلية):

<!-- Initial Load -->
<form ...>
  <input name="canonicalUrl" type="hidden"
        value="The canonical URL is: CANONICAL_URL - RANDOM - CANONICAL_HOSTNAME"
        data-amp-replace="CANONICAL_URL RANDOM">
  <input name="clientId" type="hidden"
        value="CLIENT_ID(myid)"
        data-amp-replace="CLIENT_ID">
  ...
</form>

بعد أن يحاول المستخدِم إرسال النموذج، ستحاول AMP حل المتغيرات وتعديل سمة value لجميع الحقول بالاستبدالات المناسبة. بالنسبة إلى عمليات إرسال XHR، يتم على الأرجح استبدال جميع المتغيرات وحلها. ومع ذلك، في عمليات الإرسال غير XHR GET، قد لا تتوفر القيم التي تتطلب حلاً غير متزامن بسبب عدم حلها مسبقًا. لن يتم مثلاً حل القيمة CLIENT_ID إذا لم يتم حلها وتخزينها مؤقتًا مسبقًا.

<!-- User submits the form, variables values are resolved into fields' value -->
<form ...>
  <input name="canonicalUrl" type="hidden"
        value="The canonical URL is: https://example.com/hello - 0.242513759125 - CANONICAL_HOSTNAME"
        data-amp-replace="CANONICAL_URL RANDOM">
  <input name="clientId" type="hidden"
        value="amp:asqar893yfaiufhbas9g879ab9cha0cja0sga87scgas9ocnas0ch"
        data-amp-replace="CLIENT_ID">
    ...
</form>

لاحظ أنه لم يتم استبدال CANONICAL_HOSTNAME في المثال أعلاه لأنه لم يكن في القائمة البيضاء من خلال السمة data-amp-replace في الحقل الأول.

ستحدث عمليات الاستبدال عند كل إرسال لاحق. يمكنك قراءة المزيد عن عمليات استبدال المتغيرات في AMP.

تعويض الميزات المفقودة من المتصفحات

توفر الإضافة amp-form تعويضات للسلوكيات والوظائف المفقودة من بعض المتصفحات أو الجاري تنفيذها في الإصدار التالي من CSS.

حظر الإرسال غير الصالح وفقاعة رسائل التحقق

لا تتيح المتصفحات التي تستخدم محركات مستندة إلى الويب حاليًا (اعتبارًا من آب (أغسطس) 2016) عمليات إرسال النماذج غير الصالحة. وتشمل المتصفح Safari على جميع المنصات بالإضافة إلى جميع متصفحات iOS. تعوّض الإضافة amp-form هذا السلوك لحظر أي عمليات إرسال غير صالحة وتعرض فقاعات لرسائل التحقق من الإدخالات غير صالحة.

الفئات الزائفة المستندة إلى تفاعل المستخدِم

إن الفئات الزائفة :user-invalid و:user-valid جزء من المواصفات المستقبلية لمحددات CSS 4 ويتم استخدامها لإتاحة عناصر الهوك بشكل أفضل بهدف تصميم الحقول الصالحة/غير الصالحة بناء على بضع معايير.

إن وقت استخدام :invalid و:user-invalid على العنصر واحد من أوجه الاختلاف الرئيسية بينهما. يتم تطبيق الفئة :user-invalid بعد تفاعل مهم من المستخدِم مع الحقل (كأن يكتب المستخدِم في الحقل أو يتم تعتيم الحقل عنه).

توفر الإضافة amp-form فئات لتعويض ما تفقده هذه الفئات الزائفة. تنشر الإضافة amp-form أيضًا هذه الفئات على عناصر fieldset للكيانات الأصلية وform.

التحقق من <textarea>

مطابقة التعبيرات العادية هي ميزة تحقق شائعة متاحة بشكل أصلي على معظم عناصر الإدخال، باستثناء <textarea>. ونعمل على تعويض هذه الوظيفة ونتيح السمة pattern على عناصر <textarea>.

يوفر AMP Form سمة autoexpand لعناصر <textarea>. ويتيح هذا لـ textarea التوسع والتقليص لاستيعاب صفوف إدخال المستخدِم، وصولاً إلى الحجم الأقصى للحقل. إذا غيّر المستخدِم حجم الحقل يدويًا، ستتم إزالة السلوك autoexpand.

<textarea autoexpand></textarea>

التصميم

الفئات وعناصر الهوك CSS

توفر الإضافة amp-form فئات وعناصر الهوك CSS للناشرين لتصميم النماذج والإدخالات.

يمكن استخدام الفئات التالية لبيان حالة إرسال النموذج:

  • .amp-form-initial
  • .amp-form-verify
  • .amp-form-verify-error
  • .amp-form-submitting
  • .amp-form-submit-success
  • .amp-form-submit-error

الفئات التالية عبارة عن تعويض للفئات المزيفة المستندة إلى تفاعل المستخدِم:

  • .user-valid
  • .user-invalid

يمكن للناشرين استخدام هذه الفئات لتصميم الإدخالات والحقول بحيث تتجاوب مع إجراءات المستخدِم (مثل تمييز إدخال غير صالح بحد أحمر بعد تعتيم المستخدِم له).

انظر المثال الكامل هنا لهذا الاستخدام.

انتقِل إلى الموقع AMP Start للاطّلاع على عناصر AMP form المتجاوبة المُصمَّمة مسبقًا التي يمكن استخدامها في صفحات AMP.

الاعتبارات الأمنية

الحماية من XSRF

بالإضافة إلى اتباع التفاصيل الواردة في مواصفات AMP CORS، يُرجى توجيه العناية الفائقة للقسم "معالجة طلبات تغيير الحالة" #processing-state-changing-requests) للحماية من هجمات XSRF التي ينفذ فيها المهاجم أوامر غير مصرح بها باستخدام الجلسة الحالية للمستخدِم بدون علمه.

ضع في اعتبارك النقاط التالية بشكل عام عند قبول إدخال من المستخدِم:

  • استخدِم POST فقط لطلبات تغيير الحالة.
  • استخدِم طلبات GET غير XHR لأغراض التنقل فقط (مثل البحث).
    • لن تحصل طلبات GET غير XHR على أصل دقيق/ رؤوس دقيقة ولن تتمكن الخلفيات من الحماية من XSRF باستخدام الآلية المذكورة أعلاه.
    • بشكل عام، استخدِم طلبات GET من النوع XHR أو غيره للتنقل أو استرداد المعلومات فقط.
  • غير مسموح بطلبات POST غير XHR في مستندات AMP. ويرجع ذلك إلى تناقض تعيين رأس Origin على هذه الطلبات عبر المتصفحات. وسيتم تقديم المضاعفات الداعمة في الحماية من XSRF. وقد تتم إعادة النظر في هذا الأمر وتقديمه لاحقًا لذا يرجى تقديم موضوع إذا كنت تعتقد بضرورة هذا.
هل تحتاج إلى مزيد من المساعدة؟

لقد قرأت هذا المستند عشرات المرات ولكن ألم يُجِب عن جميع أسئلتك؟ ربما حصل ذات الأمر مع أشخاص آخرين: تواصل معهم على Stack Overflow.

الذهاب إلى Stack Overflow
هل وجدت خطأ أو تفتقد لميزة؟

يشجع مشروع AMP مشاركتك ومساهمتك بشدة! ونأمل أن تكون مشاركًا دائمًا في مجتمعنا مفتوح المصدر، ولكننا نشجع أيضًا المساهمات التي تحدث لمرة واحدة في الأمور التي تتحمس لها.

الانتقال إلى GitHub