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

توفر واجهة برمجة تطبيقات "أداة اختيار جهات الاتصال" للمستخدمين طريقة سهلة لمشاركة جهات الاتصال من قائمة جهات الاتصال.

Pete LePage

ما هي واجهة برمجة التطبيقات Contact Picker API؟

استخدام واجهة برمجة التطبيقات Contact Picker API

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

رصد الميزات

للتحقّق من توفّر واجهة برمجة التطبيقات Contact Picker API، استخدِم:

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

بالإضافة إلى ذلك، تتطلب "أداة اختيار جهات الاتصال" على نظام التشغيل Android M من Android أو إصدار أحدث.

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

نقطة الدخول إلى 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 API إلا من سياق تصفّح آمن من المستوى الأعلى، ومثل واجهات برمجة التطبيقات القوية الأخرى، تتطلّب إيماءة المستخدم.

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

لتحديد المواقع المتوفّرة، اتصل على 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 فقط، ستعرض أداة الاختيار الاسم وأرقام الهاتف فقط.

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

عدم تثبيت الأذونات

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

ملاحظات

يريد فريق Chrome معرفة تجاربك مع واجهة برمجة التطبيقات لتطبيق "أداة اختيار جهات الاتصال".

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

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

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

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

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

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

روابط مفيدة

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

شكرًا

أريد أن أشكر كلًا من "فينور ثورارينسون" و"ريان كانسو" اللذَين ينفذان الميزة و"بيتر بيفيرلو" الذي سرقت الرمز البرمجي الخاص به بدون خجل وأعددتُه من أجل العرض التقديمي.

ملاحظة: الأسماء الواردة في منتقي جهات الاتصال هي أحرف من Alice in Wonderland.