تحكمات الاكتمال الخفيفة باستخدام قائمة بيانات HTML5

في هذا البرنامج التعليمي، سنغوص في عمق عنصر HTML5 الأقل استخدامًا <datalist>. يمكن استخدامه لتنفيذ عنصر تحديد النموذج الخفيف الوزن والقابل للوصول ومتوافق عبر متصفحات دون الحاجة إلى JavaScript.

ما الخطأ في <select>؟

عناصر HTML5 <select> مثالية عندما ترغب في أن يختار المستخدم من نطاق صغير من الخيارات. ليست عملية عندما:

• هناك العديد من الخيارات، مثل الدول أو عناوين الوظائف
• يرغب المستخدم في إدخال خياره الخاص وهو غير موجود في القائمة

الحل الواضح هو عنصر التلاعب بالبحث. يسمح هذا بإدخال المستخدم لبضعة أحرف، مما يحد من الخيارات المتاحة للاختيار السريع.

<select> سينتقل إلى الموضع الصحيح عند بدء الكتابة، لكن هذا ليس واضحًا دائمًا. لن يعمل على جميع الأجهزة (مثل شاشات اللمس)، ويعيد تعيينها خلال ثانية أو ثانيتين.

غالبًا ما يتجه المطورون إلى إحدى العديد من حلول تعمل بالجافا سكريبت، لكن عنصر التلاعب بالبحث المخصص ليس ضروريًا دائمًا. عنصر HTML5 <datalist> خفيف الوزن، قابل للوصول، وليس لديه اعتمادات JavaScript. قد سمعت أنه مشوش أو يفتقر إلى الدعم. هذا ليس صحيحًا في عام 2021، لكن هناك اختلافات وشروط متصفحات.

<datalist> البدء السريع

اختيار بلدك من قائمة تحتوي على أكثر من 200 خيار هو مرشح مثالي لتحكم التلاعب التلقائي. قم بتعريف <datalist> مع عناصر <option> تابعة لـكل بلد مباشرة في صفحة HTML:

<datalist id="countrydata">
  <option>Afghanistan</option>
  <option>Åland Islands</option>
  <option>Albania</option>
  <option>Algeria</option>
  <option>American Samoa</option>
  <option>Andorra</option>
  <option>Angola</option>
  <option>Anguilla</option>
  <option>Antarctica</option>
  ...etc...
</datalist>

يمكن بعد ذلك استشهاد بـ id للقائمة في أي حقل <input>:

<label for="country">country</label>

<input type="text"
  list="countrydata"
  id="country" name="country"
  size="50"
  autocomplete="off" />

مربكًا ، من الأفضل تعيين autocomplete="off". يضمن هذا عرض القيم في <datalist> ولكن ليس القيم التي أدخلها المستخدم من قبل في المتصفح.

النتيجة:

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

<option> خيارات

استخدام التسمية كنص تابع لـ <option> شائع:

<datalist id="mylist">
  <option>label one</option>
  <option>label two</option>
  <option>label three</option>
</datalist>

استخدام سمة value ينتج نتائج مماثلة:

<datalist id="mylist">
  <option value="label one" />
  <option value="label two" />
  <option value="label three" />
</datalist>

ملاحظة: مائل الإغلاق /> غير إلزامي في HTML5 ، على الرغم من أنه قد يساعد في منع أخطاء البرمجة.

يمكنك أيضًا تعيين قيمة وفقًا للتسمية المختارة باستخدام أي من التنسيقات التالية.

خيار 1:

<datalist id="mylist">
  <option value="1">label one</option>
  <option value="2">label two</option>
  <option value="3">label three</option>
</datalist>

خيار 2:

<datalist id="mylist">
  <option value="1" label="label one" />
  <option value="2" label="label two" />
  <option value="3" label="label three" />
</datalist>

في كلتا الحالتين ، يتم تعيين حقل الإدخال إلى 1 ، 2 أو 3 عندما يتم اختيار خيار صالح ، لكن الواجهة التقنية تختلف عبر المتصفحات:

• يظهر Chrome قائمة بكل من القيمة والتسمية. تبقى القيمة وحدها بعد اختيار خيار.
• يظهر Firefox قائمة بالتسمية فقط. يتحول إلى القيمة بعد اختيار خيار.
• يظهر Edge القيمة فقط.

يوضح المثال التالي على CodePen جميع الاختلافات:

انظر إلى Pen
HTML5 <datalist> autocomplete examples by SitePoint (@SitePoint)
on CodePen.

ستتطور التطبيقات ولكن، في الوقت الحالي، أوصي بعدم استخدام قيمة وتسمية لأنه من المحتمل أن يظهر المستخدمين. (يتم نقاش حل جانبي أدناه.)

<datalist> دعم المتصفح والخيارات البديلة

عنصر <datalist> مدعوم جيدًا في متصفحات العالم الحديث وكذلك Internet Explorer 10 و 11:

هناك عدة ملاحظات تنفيذية، ولكنها لن تؤثر على معظم الاستخدامات. الأسوأ هو أن يتراجع الحقل إلى إدخال نص تقليدي.

إذا كان عليك تأكيد الدعم لـ IE9 وأقل، هناك نمط بديل يستخدم <select> تقليدي بالإضافة إلى إدخال نص عندما يفشل <datalist>. تكييف مثال البلد:

<label for="country">country</label>

<datalist id="countrydata">

  <select name="countryselect">
    <option></option>
    <option>Afghanistan</option>
    <option>Åland Islands</option>
    <option>Albania</option>
    <option>Algeria</option>
    <option>American Samoa</option>
    <option>Andorra</option>
    <option>Angola</option>
    <option>Anguilla</option>
    <option>Antarctica</option>
    ...etc...
  </select>

  <label for="country">or other</label>

</datalist>

<input type="text"
  id="country" name="country"
  size="50"
  list="countrydata"
  autocomplete="off" />

انظر إلى القلمية
HTML5 <datalist> autocomplete fallback بواسطة SitePoint (@SitePoint)
على CodePen.

في المتصفحات الحديثة، تصبح عناصر <option> جزءًا من <datalist> ولا يظهر تسمية “أو غير ذلك”. يبدو مطابقًا للمثال فوق، لكن قيمة النموذج countryselect ستصبح سلسلة فارغة.

في IE9 وأقل منه، يكون كلا الحقلين (الطويل جدًا) <select> والحقول النصية نشطة:

يمكن إدخال قيمتين في الإصدارات القديمة من IE. يجب أن يقرر تطبيقك إما:

• تحديد الأكثر صلاحية، أو
• استخدام دالة جافاسكربت صغيرة لإعادة تعيين أحدهما عند تغيير الآخر

استخدام <datalist> على عناصر غير نصية

يمكن للمتصفحات المبنية على كروم أيضًا تطبيق قيم <datalist> على:

1. حقل إدخال بنوع "date". يمكن للمستخدم اختيار من نطاق من الخيارات المحددة بقيم YYYY-MM-DD ولكنها تُعرض بتنسيق اللغة المحلية.

2. حقل مدخل بنوع "لون". يمكن للمستخدم اختيار من مجموعة من خيارات الألوان المحددة بقيم سداسية الرقمين (لا تعمل القيم ثلاثية الأرقام).

3. حقل مدخل بنوع "نطاق". يظهر المنزلق علامات مداه، ولكن هذا لا يحد من قيمة يمكن إدخالها.

راجع الكود
HTML5 <datalist> على أنواع مدخلات أخرى من قبل SitePoint (@SitePoint)
على CodePen.

<datalist> تصميم CSS

إذا كادت أزماتك في تصميم <select>، … كان ذلك سهلاً!

يمكن تصميم <input> كالعادة، ولكن <datalist> المرتبط وعناصره الفرعية <option> لا يمكن تصميمها في CSS. تقرر عرض القائمة بالكامل من قبل المنصة والمتصفح.

I hope this situation improves, but for now, a solution is proposed at MDN which:

1. يزيل السلوك الافتراضي للمتصفح
2. يعامل الـ <datalist> مثل <div> لتمكين تصميمها في CSS
3. يعيد تكرار جميع وظائف التلقائي في JavaScript

I’ve enhanced it further and the code is available on GitHub. To use it, load the script anywhere in your HTML page as an ES6 module. The jsDelivr CDN URL can be used:

<script src="https://cdn.jsdelivr.net/npm/datalist-css/dist/datalist-css.min.js"></script>

أو يمكنك تثبيته باستخدام npm إذا كنت تستخدم مترانج:

npm install datalist-css

يجب أن تستخدم عناصر <datalist> الخاصة بك تنسيق <option>value</option>. على سبيل المثال:

<datalist id="mylist">
  <option>label one</option>
  <option>label two</option>
  <option>label three</option>
</datalist>

ملاحظة: لا يمكن استخدام <option value="value" /> ، حيث يؤدي إلى عنصر فارغ لا يمكن تصميمه!

يمكن إضافة ال CSS بعد ذلك لتصميم بعض أو كل <datalist> و <option> العناصر. على سبيل المثال:

datalist {
  position: absolute;
  max-height: 20em;
  border: 0 none;
  overflow-x: hidden;
  overflow-y: auto;
}

datalist option {
  font-size: 0.8em;
  padding: 0.3em 1em;
  background-color: #ccc;
  cursor: pointer;
}

/* تصميم الخيار النشط */
datalist option:hover, datalist option:focus {
  color: #fff;
  background-color: #036;
  outline: 0 none;
}

مثال:

انظر إلى قليل
تصميم CSS التلقائي لـ HTML5 <datalist> بواسطة SitePoint (@SitePoint)
على CodePen.

يعمل التصميم ، لكن هل يستحق الجهد؟ أظن أنه لا …

• إعادة تنفيذ مفاتيح المتصفح القياسية ، والفأرة وتحكم الاتصال بشكل معقول صعب. ال مثال MDN لا يدعم أحداث المفاتيح و، على الرغم من أنني حاولت تحسينه ، سيكون هناك بالتأكيد مشاكل في بعض الأجهزة.
• كنت تعتمد على 200 سطر من JavaScript لحل مشكلة CSS. يتم تصغيره إلى 1.5 كيلو بايت ، ولكن قد يؤدي إلى مشاكل أداء إذا كنت في حاجة إلى العديد من <datalist> العناصر الطويلة على نفس الصفحة.
• إذا كانت متطلبات JavaScript، فهل يفضل استخدام مكون JavaScript أكثر جمالًا واتساقًا ومجربًا؟

يعود التحكم إلى إطار عمل HTML5 القياسي <datalist> بدون تهيئة عندما يفشل JavaScript، ولكن هذا فوز بسيط.

إنشاء <datalist> معزز بـ Ajax

على افتراض أن مصممك يرضى باختلافات تهيئة المتصفح، فمن الممكن تعزيز وظائف <datalist> القياسية باستخدام JavaScript. على سبيل المثال:

1. تنفيذ التحقق من الصحة إلزامي القبول فقط قيمة معروفة في <datalist>.
2. تعيين عناصر <option> من البيانات التي تم إرجاعها بواسطة استدعاءات Ajax إلى واجهات برمجة التطبيقات للبحث.
3. تعيين قيم أخرى للحقول عندما يتم اختيار خيار. على سبيل المثال، اختيار “الولايات المتحدة الأمريكية” يعين “US” في إدخال مخفي.

يجب أن يعيد الكود في الغالب تعريف عناصر <option>، على الرغم من وجود عدد من الاعتبارات البرمجية:

• يجب أن يحدث استدعاء واجهة برمجة التطبيقات Ajax فقط بعد إدخال عدد أدنى من الأحرف.
• يجب أن تكون أحداث الكتابة مضبوطة. أي أن استدعاء Ajax يتم تنفيذه فقط بعد أن توقف المستخدم عن الكتابة لمدة على الأقل نصف ثانية.
• يجب تخزين نتائج الاستعلام بحيث لا يلزم تكرار أو تحليل الاتصالات المتطابقة.
• يجب تجنب الاستعلامات غير الضرورية. على سبيل المثال، إدخال “un” يعيد 12 دولة. لا داعي لإجراء مزيد من استدعاءات Ajax لـ “unit” أو “united” لأن جميع الخيارات الناتجة موجودة في النتائج الأصلية 12.

I’ve created a standard Web Component for this, and the code is available on GitHub. The CodePen example below allows you to select a valid country after entering at least two characters. A music artist autocomplete then returns artists who originated in that country with names matching the search string:

انظر إلى صفحة
HTML5 <datalist> with Ajax autocomplete من SitePoint (@SitePoint)
على CodePen.

• من API البحث عن البلدومقدم بواسطة restcountries.eu.
• من API البحث عن فناني الموسيقى مقدم بواسطة musicbrainz.org.

لاستخدامه في تطبيقك الخاص، قم بتحميل السكريبت في أي مكان في صفحة HTML الخاصة بك كوحدة ES6. يمكن استخدام عنوان CDN jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/datalist-ajax/dist/datalist-ajax.min.js"></script>

أو يمكنك تثبيته باستخدام npm إذا كنت تستخدم مترجم:

npm install datalist-ajax

قم بإنشاء عنصر <auto-complete> مع طفل <input> لاستخدامه كحقل إدخال البيانات. على سبيل المثال، يستخدم البحث عن البلدان هذا:

<label for="country">country lookup:</label>

<auto-complete
  api="https://restcountries.eu/rest/v2/name/${country}?fields=name;alpha2Code;region"
  resultname="name"
  querymin="2"
  optionmax="50"
  valid="please select a valid country"
>
  <input type="text" id="country" name="country" size="50" required />
</auto-complete>

سمات عنصر <auto-complete>:

attribute	description
api	the REST API URL (required)
resultdata	the name of the property containing a result array of objects in the returned API JSON (not required if only results are returned)
resultname	the name of the property in each result object which matches the search input and is used for datalist <option> elements (required)
querymin	the minimum number of characters to enter before a search is triggered (default: 1)
inputdelay	the minimum time to wait in milliseconds between keypresses before a search occurs (default debounce: 300)
optionmax	the maximum number of autocomplete options to show (default: 20)
valid	if set, this error message is shown when an invalid value is selected

يجب أن يحتوي URL REST على معرّف ${id} على الأقل، والذي يُستبدل بالقيمة المعيّنة في <input> الذي يحمل ذلك id. في المثال أعلاه، ${country} في URL api يشير إلى القيمة في الإدخال الطفل <input>، الذي يمتلك id من "country". سيستخدم الرابط عادةً الإدخال الطفل، لكن يمكن استشارة أي حقول أخرى على الصفحة.

تُرجع واجهة restcountries.eu API كائنًا واحدًا أو مجموعة من الكائنات تحتوي على بيانات البلد. على سبيل المثال:

[
  {
    "name": "Cyprus",
    "alpha2Code": "CY",
    "region": "Europe"
  },
  {
    "name": "Sao Tome and Principe",
    "alpha2Code": "ST",
    "region": "Africa"
  },
  {
    "name": "Andorra",
    "alpha2Code": "AD",
    "region": "Europe"
  }
]

لا يحتاج سمة resultdata إلى أن تُعيّن لأن هذه هي البيانات الوحيدة المرتجعة (ليس هناك كائن غلاف). يجب أن تُعيّن سمة resultname إلى "name" لأن هذا الملكية تُستخدم لملء عناصر <option> datalist.

يمكن ملء حقول أخرى تلقائيًا عند اختيار خيار. تتلقى الإدخالات التالية البيانات للملكيات "alpha2Code" و "region" لأنه تم تعيين سمة data-autofill:

<input data-autofill="alpha2Code" type="text" id="countrycode" name="countrycode" readonly />

<input data-autofill="region" type="text" id="region" name="region" readonly />

كيف يعمل datalist-ajax

يمكنك تخطي هذا القسم إذا كنت تفضل عدم قراءة 230 سطر من التعليمات البرمجية والحفاظ على السحر!

يبدأ الكود بإنشاء عنصر <datalist> جديد داخل <auto-complete>، ويعلقه في العنصر <input> الإبن باستخدام سمة الـ list. يراقب معالج حدث input العنصر <input> ويستدعي دالة runQuery() عندما يتم إدخال عدد أدنى من الأحرف والمستخدم لم يعُد يكتب.

تقوم runQuery() ببناء عنوان URL الـ API من البيانات في النموذج وتجري استدعاء Ajax باستخدام Fetch API. يتم تحليل الـ JSON المرتجع، ثم يتم بناء قطعة DOM قابلة لإعادة الاستخدام تحتوي على عناصر <option> ووضعها في مكعب.

A datalistUpdate() function is called, which updates the <datalist> with the appropriate cached DOM fragment. Further calls to runQuery() avoid Ajax calls if a query has already been cached or a previous query can be used.

A change event handler also monitors the <input>, which is triggered when focus is moved from the field and the value has been modified. The function checks that the value matches a known option and, if necessary, uses the Constraint Validation API to show the error message provided in the valid attribute.

على افتراض أن قيمة صالحة قد تم اختيارها، تملأ دالة معالج التغيير جميع الحقول بأترتب سمة data-autofill مطابقة. يتم الاحتفاظ بمرجع الحقول التلقائية لإعادة تعيينها إذا تم إدخال خيار غير صالح لاحقًا.

لاحظ أن DOM الظّلام لا يتم استخدامه. هذا يضمن أن عنصر الـ <input> (و<datalist>) التلقائي يمكن تصميمها بواسطة الـ CSS والوصول إليها من قبل سِـطور أخرى من البرمجيات إذا لزم الأمر.

Dunkin’ <datalist>

عنصر HTML5 <datalist> له قيود لكنه مثالي إذا كنت تحتاج إلى حقل تلقائي غير مرتبط ببنية برمجية بسيطة. عدم دعم CSS هو عار، لكن مزوّدي المتصفحات قد يعالجون ذلك الإهمال في النهاية.

يمكن اعتماد أيٍ من الكود والأمثلة الموضحة في هذا البرنامج التعليمي لمشاريعك الخاصة.

الأسئلة الشائعة حول تحكم التلائم الخفيفة مع قائمة HTML5