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

توفّر واجهة برمجة التطبيقات 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 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 في تحديد الميزات ذات الأولوية، ويُظهر لموفّري المتصفّحات الآخرين مدى أهمية توفير هذه الميزات.

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

روابط مفيدة

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

شكرًا

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

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