أداة اختيار جهات الاتصال على الويب

توفّر Contact Picker API طريقة سهلة للمستخدمين لمشاركة جهات الاتصال من قائمة جهات الاتصال.

Pete LePage

ما هي Contact Picker API؟

استخدام Contact Picker API

تتطلّب واجهة برمجة التطبيقات Contact Picker API طلب طريقة مع مَعلمة خيارات تحدّد أنواع معلومات الاتصال التي تريدها. تخبرك الطريقة الثانية بالمعلومات التي سيقدّمها النظام الأساسي.

رصد الميزات

للتأكّد من توفّر Contact Picker API، استخدِم الرمز التالي:

const supported = ('contacts' in navigator && 'ContactsManager' in window);

بالإضافة إلى ذلك، تتطلّب أداة اختيار جهات الاتصال على Android الإصدار Android M أو إصدارًا أحدث.

فتح "أداة اختيار جهات الاتصال"

نقطة الدخول إلى Contact Picker API هي navigator.contacts.select(). عند استدعاء هذه الطريقة، تعرض وعدًا وتُظهر أداة اختيار جهات الاتصال، ما يتيح للمستخدم اختيار جهات الاتصال التي يريد مشاركتها مع الموقع الإلكتروني. بعد اختيار المحتوى الذي تريد مشاركته والنقر على تم، يتم تنفيذ الوعد باستخدام مصفوفة جهات الاتصال التي اختارها المستخدم.

عند طلب select()، يجب تقديم مجموعة من الخصائص التي تريد عرضها كنتيجة كالمَعلمة الأولى (مع القيم المسموح بها التي يمكن أن تكون أيًا من 'name' أو 'email' أو 'tel' أو 'address' أو 'icon')، ويمكنك اختياريًا تحديد ما إذا كان يمكن اختيار جهات اتصال متعددة كالمَعلمة الثانية.

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
  const contacts = await navigator.contacts.select(props, opts);
  handleResults(contacts);
} catch (ex) {
  // Handle any errors here.
}

لا يمكن استدعاء واجهة برمجة التطبيقات Contacts Picker إلا من سياق تصفّح آمن من المستوى الأعلى، وكما هو الحال مع واجهات برمجة التطبيقات القوية الأخرى، تتطلّب هذه الواجهة إيماءة من المستخدم.

رصد المواقع المتاحة

للكشف عن الخصائص المتاحة، استخدِم الدالة navigator.contacts.getProperties(). تعرض هذه الدالة وعدًا يتم تنفيذه باستخدام صفيف من السلاسل يشير إلى الخصائص المتاحة. على سبيل المثال: ['name', 'email', 'tel', 'address']. يمكنك تمرير هذه القيم إلى select().

يُرجى العِلم أنّ السمات ليست متاحة دائمًا، وقد تتم إضافة سمات جديدة. في المستقبل، قد تحظر منصات أخرى ومصادر جهات الاتصال مشاركة بعض الخصائص.

التعامل مع النتائج

تعرض واجهة برمجة التطبيقات Contact Picker API مصفوفة من جهات الاتصال، وتتضمّن كل جهة اتصال مصفوفة من السمات المطلوبة. إذا لم تتوفّر بيانات جهة اتصال للسمة المطلوبة، أو إذا اختار المستخدم إيقاف مشاركة سمة معيّنة، ستعرض واجهة برمجة التطبيقات مصفوفة فارغة. (أوضّح كيفية اختيار المستخدم للخصائص في قسم تحكّم المستخدم).

على سبيل المثال، إذا طلب موقع إلكتروني name وemail وtel، واختار المستخدم جهة اتصال واحدة تتضمّن بيانات في حقل الاسم، وقدّم رقمَي هاتف، ولكن لم يقدّم عنوان بريد إلكتروني، سيكون الردّ الذي تم إرجاعه كما يلي:

[{
  "email": [],
  "name": ["Queen O'Hearts"],
  "tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

الأمان والأذونات

صمَّم فريق Chrome واجهة برمجة التطبيقات Contact Picker API ونفَّذها باستخدام المبادئ الأساسية المحدّدة في التحكّم في الوصول إلى الميزات الفعّالة لمنصة الويب، بما في ذلك تحكّم المستخدم والشفافية وبيئة العمل المريحة. سأشرح كلّ منها.

تحكّم المستخدم

يتم الوصول إلى جهات اتصال المستخدمين من خلال أداة الاختيار، ولا يمكن استدعاؤها إلا بإيماءة من المستخدم، وذلك في سياق تصفّح آمن وعالي المستوى. يضمن ذلك عدم إمكانية عرض أداة الاختيار عند تحميل الصفحة أو عرضها بشكل عشوائي بدون أي سياق.

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

الشفافية

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

سيؤدي الضغط مع الاستمرار على جهة اتصال إلى عرض جميع المعلومات التي ستتم مشاركتها في حال اختيار جهة الاتصال. (اطّلِع على صورة جهة الاتصال "قطة شيشاير").

عدم استمرار الأذونات

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

الملاحظات

يريد فريق Chrome معرفة تجاربك مع واجهة برمجة التطبيقات Contact Picker.

هل تواجه مشكلة في التنفيذ؟

هل عثرت على خطأ في تنفيذ Chrome؟ أو هل يختلف التنفيذ عن المواصفات؟

• أبلِغ عن الخطأ على https://new.crbug.com. احرص على تضمين أكبر قدر ممكن من التفاصيل، وقدِّم تعليمات بسيطة لإعادة إنتاج الخطأ، واضبط المكوّنات على Blink>Contacts.

هل تخطّط لاستخدام واجهة برمجة التطبيقات؟

هل تخطّط لاستخدام Contact Picker API؟ يساعد دعمك العلني فريق Chrome في تحديد أولويات الميزات، ويوضّح لمورّدي المتصفّحات الآخرين مدى أهمية توفيرها.

• شارِك كيف تخطّط لاستخدامه في سلسلة محادثات WICG Discourse.
• أرسِل تغريدة إلى ‎@ChromiumDev باستخدام الهاشتاغ #ContactPicker وأخبِرنا عن مكان استخدامك لهذه الميزة وكيفية استخدامها.

روابط مفيدة

• شرح علني
• مواصفات "أداة اختيار جهات الاتصال"
• عرض توضيحي لواجهة Contact Picker API ومصدر العرض التوضيحي لواجهة Contact Picker API
• خطأ في التتبُّع
• إدخال ChromeStatus.com
• مكوّن Blink: Blink>Contacts

شكرًا

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

ملاحظة: الأسماء في أداة اختيار جهات الاتصال هي شخصيات من رواية "أليس في بلاد العجائب".